elementary: add 2 API, the first one is to set the first day of week in elm_calendar...
[framework/uifw/elementary.git] / src / lib / elm_calendar.h
1 /**
2  * @defgroup Calendar Calendar
3  *
4  * This is a Calendar widget. Calender widget helps applications to flexibly
5  * display a calender with day of the week, day, year and month. Applications will be
6  * able to choose a specific date that will be reported in the smart_callbacks for
7  * the calendar widget. The APIs of calendar widget let the applications perform
8  * other functions like,
9  * placing marks on specific dates
10  * Setting the bounds for the calendar (minimum and maximum years)
11  * Setting the day names of the week. ( for ex. Thu. or Thursday)
12  * Setting the year and month format.
13  *
14  * Signals that you can add callbacks for are:
15  * - @c "changed" - emitted when the date in the calendar is changed.
16  *
17  * Supported elm_object common APIs.
18  * @li elm_object_signal_emit
19  * @li elm_object_signal_callback_add
20  * @li elm_object_signal_callback_del
21  *
22  * Here is some sample code using it:
23  * @li @ref calendar_example_01
24  * @li @ref calendar_example_02
25  * @li @ref calendar_example_03
26  * @li @ref calendar_example_04
27  * @li @ref calendar_example_05
28  * @li @ref calendar_example_06
29  */
30
31 /**
32  * @addtogroup Calendar
33  * @{
34  */
35
36 typedef enum
37 {
38    ELM_CALENDAR_UNIQUE, /**< Default value. Marks will be displayed only on event day. */
39    ELM_CALENDAR_DAILY, /**< Marks will be displayed every day after event day (inclusive). */
40    ELM_CALENDAR_WEEKLY, /**< Marks will be displayed every week after event day (inclusive) - i.e. each seven days. */
41    ELM_CALENDAR_MONTHLY, /**< Marks will be displayed every month day that coincides to event day. E.g.: if an event is set to 30th Jan, no marks will be displayed on Feb, but will be displayed on 30th Mar*/
42    ELM_CALENDAR_ANNUALLY /**< Marks will be displayed every year that coincides to event day (and month). E.g. an event added to 30th Jan 2012 will be repeated on 30th Jan 2013. */
43 } _Elm_Calendar_Mark_Repeat_Type;
44
45 /**
46  * @enum _Elm_Calendar_Mark_Repeat_Type
47  * @typedef Elm_Calendar_Mark_Repeat_Type
48  *
49  * Event periodicity, used to define if a mark should be repeated
50  * @b beyond event's day. It's set when a mark is added.
51  *
52  * So, for a mark added to 13th May with periodicity set to WEEKLY,
53  * there will be marks every week after this date. Marks will be displayed
54  * at 13th, 20th, 27th, 3rd June ...
55  *
56  * Values don't work as bitmask, only one can be chosen.
57  *
58  * @see elm_calendar_mark_add()
59  *
60  * @ingroup Calendar
61  */
62 typedef _Elm_Calendar_Mark_Repeat_Type Elm_Calendar_Mark_Repeat_Type;
63
64 typedef struct _Elm_Calendar_Mark Elm_Calendar_Mark;    /**< Item handle for a calendar mark. Created with elm_calendar_mark_add() and deleted with elm_calendar_mark_del(). */
65
66 /**
67  * @typedef Elm_Calendar_Format_Cb
68  *
69  * This callback type is used to format the string that will be used
70  * to display month and year.
71  *
72  * @param stime Struct representing time.
73  * @return String representing time that will be set to calendar's text.
74  *
75  * @see elm_calendar_format_function_set()
76  */
77 typedef char * (*Elm_Calendar_Format_Cb)(struct tm *stime);
78
79 /**
80  * Add a new calendar widget to the given parent Elementary
81  * (container) object.
82  *
83  * @param parent The parent object.
84  * @return a new calendar widget handle or @c NULL, on errors.
85  *
86  * This function inserts a new calendar widget on the canvas.
87  *
88  * @ref calendar_example_01
89  *
90  * @ingroup Calendar
91  */
92 EAPI Evas_Object         *elm_calendar_add(Evas_Object *parent);
93
94 /**
95  * Get weekdays names displayed by the calendar.
96  *
97  * @param obj The calendar object.
98  * @return Array of seven strings to be used as weekday names.
99  *
100  * By default, weekdays abbreviations get from system are displayed:
101  * E.g. for an en_US locale: "Sun, Mon, Tue, Wed, Thu, Fri, Sat"
102  * The first string is related to Sunday, the second to Monday...
103  *
104  * @see elm_calendar_weekdays_name_set()
105  *
106  * @ref calendar_example_05
107  *
108  * @ingroup Calendar
109  */
110 EAPI const char         **elm_calendar_weekdays_names_get(const Evas_Object *obj);
111
112 /**
113  * Set weekdays names to be displayed by the calendar.
114  *
115  * @param obj The calendar object.
116  * @param weekdays Array of seven strings to be used as weekday names.
117  * @warning It must have 7 elements, or it will access invalid memory.
118  * @warning The strings must be NULL terminated ('@\0').
119  *
120  * By default, weekdays abbreviations get from system are displayed:
121  * E.g. for an en_US locale: "Sun, Mon, Tue, Wed, Thu, Fri, Sat"
122  *
123  * The first string should be related to Sunday, the second to Monday...
124  *
125  * The usage should be like this:
126  * @code
127  *   const char *weekdays[] =
128  *   {
129  *      "Sunday", "Monday", "Tuesday", "Wednesday",
130  *      "Thursday", "Friday", "Saturday"
131  *   };
132  *   elm_calendar_weekdays_names_set(calendar, weekdays);
133  * @endcode
134  *
135  * @see elm_calendar_weekdays_name_get()
136  *
137  * @ref calendar_example_02
138  *
139  * @ingroup Calendar
140  */
141 EAPI void                 elm_calendar_weekdays_names_set(Evas_Object *obj, const char *weekdays[]);
142
143 /**
144  * Set the minimum and maximum values for the year
145  *
146  * @param obj The calendar object
147  * @param min The minimum year, greater than 1901;
148  * @param max The maximum year;
149  *
150  * Maximum must be greater than minimum, except if you don't want to set
151  * maximum year.
152  * Default values are 1902 and -1.
153  *
154  * If the maximum year is a negative value, it will be limited depending
155  * on the platform architecture (year 2037 for 32 bits);
156  *
157  * @see elm_calendar_min_max_year_get()
158  *
159  * @ref calendar_example_03
160  *
161  * @ingroup Calendar
162  */
163 EAPI void                 elm_calendar_min_max_year_set(Evas_Object *obj, int min, int max);
164
165 /**
166  * Get the minimum and maximum values for the year
167  *
168  * @param obj The calendar object.
169  * @param min The minimum year.
170  * @param max The maximum year.
171  *
172  * Default values are 1902 and -1.
173  *
174  * @see elm_calendar_min_max_year_get() for more details.
175  *
176  * @ref calendar_example_05
177  *
178  * @ingroup Calendar
179  */
180 EAPI void                 elm_calendar_min_max_year_get(const Evas_Object *obj, int *min, int *max);
181
182 /**
183  * Enable or disable day selection
184  *
185  * @param obj The calendar object.
186  * @param disabled @c EINA_TRUE to disable selection or @c EINA_FALSE to
187  * enable it.
188  *
189  * Enabled by default. If disabled, the user still can select months,
190  * but not days. Selected days are highlighted on calendar.
191  * It should be used if you won't need such selection for the widget usage.
192  *
193  * When a day is selected, or month is changed, smart callbacks for
194  * signal "changed" will be called.
195  *
196  * @see elm_calendar_day_selection_disabled_get()
197  *
198  * @ref calendar_example_04
199  *
200  * @ingroup Calendar
201  */
202 EAPI void                 elm_calendar_day_selection_disabled_set(Evas_Object *obj, Eina_Bool disabled);
203
204 /**
205  * Get a value whether day selection is disabled or not.
206  *
207  * @param obj The calendar object.
208  * @return EINA_TRUE means day selection is disabled. EINA_FALSE indicates
209  * it's enabled. If @p obj is NULL, EINA_FALSE is returned.
210  *
211  * @see elm_calendar_day_selection_disabled_set() for details.
212  *
213  * @ref calendar_example_05
214  *
215  * @ingroup Calendar
216  */
217 EAPI Eina_Bool            elm_calendar_day_selection_disabled_get(const Evas_Object *obj);
218
219 /**
220  * Set selected date to be highlighted on calendar.
221  *
222  * @param obj The calendar object.
223  * @param selected_time A @b tm struct to represent the selected date.
224  *
225  * Set the selected date, changing the displayed month if needed.
226  * Selected date changes when the user goes to next/previous month or
227  * select a day pressing over it on calendar.
228  *
229  * @see elm_calendar_selected_time_get()
230  *
231  * @ref calendar_example_04
232  *
233  * @ingroup Calendar
234  */
235 EAPI void                 elm_calendar_selected_time_set(Evas_Object *obj, struct tm *selected_time);
236
237 /**
238  * Get selected date.
239  *
240  * @param obj The calendar object
241  * @param selected_time A @b tm struct to point to selected date
242  * @return EINA_FALSE means an error occurred and returned time shouldn't
243  * be considered.
244  *
245  * Get date selected by the user or set by function
246  * elm_calendar_selected_time_set().
247  * Selected date changes when the user goes to next/previous month or
248  * select a day pressing over it on calendar.
249  *
250  * @see elm_calendar_selected_time_get()
251  *
252  * @ref calendar_example_05
253  *
254  * @ingroup Calendar
255  */
256 EAPI Eina_Bool            elm_calendar_selected_time_get(const Evas_Object *obj, struct tm *selected_time);
257
258 /**
259  * Set a function to format the string that will be used to display
260  * month and year;
261  *
262  * @param obj The calendar object
263  * @param format_func Function to set the month-year string given
264  * the selected date
265  *
266  * By default it uses strftime with "%B %Y" format string.
267  * It should allocate the memory that will be used by the string,
268  * that will be freed by the widget after usage.
269  * A pointer to the string and a pointer to the time struct will be provided.
270  *
271  * Example:
272  * @code
273  * static char *
274  * _format_month_year(struct tm *selected_time)
275  * {
276  *    char buf[32];
277  *    if (!strftime(buf, sizeof(buf), "%B %Y", selected_time)) return NULL;
278  *    return strdup(buf);
279  * }
280  *
281  * elm_calendar_format_function_set(calendar, _format_month_year);
282  * @endcode
283  *
284  * @ref calendar_example_02
285  *
286  * @ingroup Calendar
287  */
288 EAPI void                 elm_calendar_format_function_set(Evas_Object *obj, Elm_Calendar_Format_Cb format_func);
289
290 /**
291  * Add a new mark to the calendar
292  *
293  * @param obj The calendar object
294  * @param mark_type A string used to define the type of mark. It will be
295  * emitted to the theme, that should display a related modification on these
296  * days representation.
297  * @param mark_time A time struct to represent the date of inclusion of the
298  * mark. For marks that repeats it will just be displayed after the inclusion
299  * date in the calendar.
300  * @param repeat Repeat the event following this periodicity. Can be a unique
301  * mark (that don't repeat), daily, weekly, monthly or annually.
302  * @return The created mark or @p NULL upon failure.
303  *
304  * Add a mark that will be drawn in the calendar respecting the insertion
305  * time and periodicity. It will emit the type as signal to the widget theme.
306  * Default theme supports "holiday" and "checked", but it can be extended.
307  *
308  * It won't immediately update the calendar, drawing the marks.
309  * For this, call elm_calendar_marks_draw(). However, when user selects
310  * next or previous month calendar forces marks drawn.
311  *
312  * Marks created with this method can be deleted with
313  * elm_calendar_mark_del().
314  *
315  * Example
316  * @code
317  * struct tm selected_time;
318  * time_t current_time;
319  *
320  * current_time = time(NULL) + 5 * 84600;
321  * localtime_r(&current_time, &selected_time);
322  * elm_calendar_mark_add(cal, "holiday", selected_time,
323  *     ELM_CALENDAR_ANNUALLY);
324  *
325  * current_time = time(NULL) + 1 * 84600;
326  * localtime_r(&current_time, &selected_time);
327  * elm_calendar_mark_add(cal, "checked", selected_time, ELM_CALENDAR_UNIQUE);
328  *
329  * elm_calendar_marks_draw(cal);
330  * @endcode
331  *
332  * @see elm_calendar_marks_draw()
333  * @see elm_calendar_mark_del()
334  *
335  * @ref calendar_example_06
336  *
337  * @ingroup Calendar
338  */
339 EAPI Elm_Calendar_Mark   *elm_calendar_mark_add(Evas_Object *obj, const char *mark_type, struct tm *mark_time, Elm_Calendar_Mark_Repeat_Type repeat);
340
341 /**
342  * Delete mark from the calendar.
343  *
344  * @param mark The mark to be deleted.
345  *
346  * If deleting all calendar marks is required, elm_calendar_marks_clear()
347  * should be used instead of getting marks list and deleting each one.
348  *
349  * @see elm_calendar_mark_add()
350  *
351  * @ref calendar_example_06
352  *
353  * @ingroup Calendar
354  */
355 EAPI void                 elm_calendar_mark_del(Elm_Calendar_Mark *mark);
356
357 /**
358  * Remove all calendar's marks
359  *
360  * @param obj The calendar object.
361  *
362  * @see elm_calendar_mark_add()
363  * @see elm_calendar_mark_del()
364  *
365  * @ingroup Calendar
366  */
367 EAPI void                 elm_calendar_marks_clear(Evas_Object *obj);
368
369 /**
370  * Get a list of all the calendar marks.
371  *
372  * @param obj The calendar object.
373  * @return An @c Eina_List of calendar marks objects, or @c NULL on failure.
374  *
375  * @see elm_calendar_mark_add()
376  * @see elm_calendar_mark_del()
377  * @see elm_calendar_marks_clear()
378  *
379  * @ingroup Calendar
380  */
381 EAPI const Eina_List     *elm_calendar_marks_get(const Evas_Object *obj);
382
383 /**
384  * Draw calendar marks.
385  *
386  * @param obj The calendar object.
387  *
388  * Should be used after adding, removing or clearing marks.
389  * It will go through the entire marks list updating the calendar.
390  * If lots of marks will be added, add all the marks and then call
391  * this function.
392  *
393  * When the month is changed, i.e. user selects next or previous month,
394  * marks will be drawn.
395  *
396  * @see elm_calendar_mark_add()
397  * @see elm_calendar_mark_del()
398  * @see elm_calendar_marks_clear()
399  *
400  * @ref calendar_example_06
401  *
402  * @ingroup Calendar
403  */
404 EAPI void                 elm_calendar_marks_draw(Evas_Object *obj);
405
406 /**
407  * Set the interval on time updates for an user mouse button hold
408  * on calendar widgets' month selection.
409  *
410  * @param obj The calendar object
411  * @param interval The (first) interval value in seconds
412  *
413  * This interval value is @b decreased while the user holds the
414  * mouse pointer either selecting next or previous month.
415  *
416  * This helps the user to get to a given month distant from the
417  * current one easier/faster, as it will start to change quicker and
418  * quicker on mouse button holds.
419  *
420  * The calculation for the next change interval value, starting from
421  * the one set with this call, is the previous interval divided by
422  * 1.05, so it decreases a little bit.
423  *
424  * The default starting interval value for automatic changes is
425  * @b 0.85 seconds.
426  *
427  * @see elm_calendar_interval_get()
428  *
429  * @ingroup Calendar
430  */
431 EAPI void                 elm_calendar_interval_set(Evas_Object *obj, double interval);
432
433 /**
434  * Get the interval on time updates for an user mouse button hold
435  * on calendar widgets' month selection.
436  *
437  * @param obj The calendar object
438  * @return The (first) interval value, in seconds, set on it
439  *
440  * @see elm_calendar_interval_set() for more details
441  *
442  * @ingroup Calendar
443  */
444 EAPI double               elm_calendar_interval_get(const Evas_Object *obj);
445
446 /**
447  * Set the first day of week to use on calendar widgets'.
448  *
449  * @param obj The calendar object
450  * @param day An int which correspond to the first day of the week (Sunday = 0, monday = 1,
451  * ..., saturday = 6)
452  *
453  * @ingroup Calendar
454  */
455 EAPI void                 elm_calendar_first_day_of_week_set(Evas_Object *obj, int day);
456
457 /**
458  * Get the first day of week, who are used on calendar widgets'.
459  *
460  * @param obj The calendar object
461  * @return An int which correspond to the first day of the week (Sunday = 0, monday = 1,
462  * ..., saturday = 6)
463  *
464  * @see elm_calendar_first_day_of_week_set() for more details
465  *
466  * @ingroup Calendar
467  */
468 EAPI int                  elm_calendar_first_day_of_week_get(const Evas_Object *obj);
469
470 /**
471  * @}
472  */