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