2 * @defgroup Calendar Calendar
5 * @image html calendar_inheritance_tree.png
6 * @image latex calendar_inheritance_tree.eps
8 * This is a calendar widget. It helps applications to flexibly
9 * display a calender with day of the week, date, year and
10 * month. Applications are able to set specific dates to be reported
11 * back, when selected, in the smart callbacks of the calendar
12 * widget. The API of this widget lets the applications perform other
15 * - placing marks on specific dates
16 * - setting the bounds for the calendar (minimum and maximum years)
17 * - setting the day names of the week (e.g. "Thu" or "Thursday")
18 * - setting the year and month format.
20 * This widget inherits from the @ref Layout one, so that all the
21 * functions acting on it also work for calendar objects.
23 * This widget emits the following signals, besides the ones sent from
25 * - @c "changed" - emitted when the date in the calendar is changed.
26 * - @c "display,changed" - emitted when the current month displayed in the
27 * calendar is changed.
29 * Supported elm_object common APIs.
30 * @li @ref elm_object_signal_emit
31 * @li @ref elm_object_signal_callback_add
32 * @li @ref elm_object_signal_callback_del
34 * Here is some sample code using it:
35 * @li @ref calendar_example_01
36 * @li @ref calendar_example_02
37 * @li @ref calendar_example_03
38 * @li @ref calendar_example_04
39 * @li @ref calendar_example_05
40 * @li @ref calendar_example_06
44 * @addtogroup Calendar
50 ELM_CALENDAR_UNIQUE, /**< Default value. Marks will be displayed only on event day. */
51 ELM_CALENDAR_DAILY, /**< Marks will be displayed every day after event day (inclusive). */
52 ELM_CALENDAR_WEEKLY, /**< Marks will be displayed every week after event day (inclusive) - i.e. each seven days. */
53 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*/
54 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. */
55 ELM_CALENDAR_LAST_DAY_OF_MONTH /**< Marks will be displayed every last day of month after event day (inclusive). @since 1.7 */
56 } _Elm_Calendar_Mark_Repeat_Type;
59 * @enum _Elm_Calendar_Mark_Repeat_Type
60 * @typedef Elm_Calendar_Mark_Repeat_Type
62 * Event periodicity, used to define if a mark should be repeated
63 * @b beyond event's day. It's set when a mark is added.
65 * So, for a mark added to 13th May with periodicity set to WEEKLY,
66 * there will be marks every week after this date. Marks will be displayed
67 * at 13th, 20th, 27th, 3rd June ...
69 * Values don't work as bitmask, only one can be chosen.
71 * @see elm_calendar_mark_add()
75 typedef _Elm_Calendar_Mark_Repeat_Type Elm_Calendar_Mark_Repeat_Type;
87 } _Elm_Calendar_Weekday;
90 * @enum _Elm_Calendar_Weekday
91 * @typedef Elm_Calendar_Weekday
95 * @see elm_calendar_first_day_of_week_set()
99 typedef _Elm_Calendar_Weekday Elm_Calendar_Weekday;
104 ELM_CALENDAR_SELECT_MODE_DEFAULT = 0, /**< Default value. a day is always selected. */
105 ELM_CALENDAR_SELECT_MODE_ALWAYS, /**< a day is always selected. */
106 ELM_CALENDAR_SELECT_MODE_NONE, /**< None of the days can be selected. */
107 ELM_CALENDAR_SELECT_MODE_ONDEMAND /**< User may have selected a day or not. */
108 } _Elm_Calendar_Select_Mode;
111 * @enum _Elm_Calendar_Select_Mode
112 * @typedef Elm_Calendar_Select_Mode
114 * the mode, who determine how user could select a day
116 * @see elm_calendar_select_mode_set()
120 typedef _Elm_Calendar_Select_Mode Elm_Calendar_Select_Mode;
124 ELM_CALENDAR_SELECTABLE_NONE = 0,
125 ELM_CALENDAR_SELECTABLE_YEAR = (1 << 0),
126 ELM_CALENDAR_SELECTABLE_MONTH = (1 << 1),
127 ELM_CALENDAR_SELECTABLE_DAY = (1 << 2)
128 } _Elm_Calendar_Selectable;
131 * @enum _Elm_Calendar_Selectable
132 * @typedef Elm_Calendar_Selectable
134 * A bitmask used to define which fields of a @b tm struct will be taken into
135 * account, when elm_calendar_selected_time_set() is invoked.
138 * @see elm_calendar_selectable_set()
139 * @see elm_calendar_selected_time_set()
142 typedef _Elm_Calendar_Selectable Elm_Calendar_Selectable;
144 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(). */
147 * @typedef Elm_Calendar_Format_Cb
149 * This callback type is used to format the string that will be used
150 * to display month and year.
152 * @param stime Struct representing time.
153 * @return String representing time that will be set to calendar's text.
155 * @see elm_calendar_format_function_set()
159 typedef char * (*Elm_Calendar_Format_Cb)(struct tm *stime);
162 * Add a new calendar widget to the given parent Elementary
163 * (container) object.
165 * @param parent The parent object.
166 * @return a new calendar widget handle or @c NULL, on errors.
168 * This function inserts a new calendar widget on the canvas.
170 * @ref calendar_example_01
174 EAPI Evas_Object *elm_calendar_add(Evas_Object *parent);
177 * Get weekdays names displayed by the calendar.
179 * @param obj The calendar object.
180 * @return Array of seven strings to be used as weekday names.
182 * By default, weekdays abbreviations get from system are displayed:
183 * E.g. for an en_US locale: "Sun, Mon, Tue, Wed, Thu, Fri, Sat"
184 * The first string is related to Sunday, the second to Monday...
186 * @see elm_calendar_weekdays_name_set()
188 * @ref calendar_example_05
192 EAPI const char **elm_calendar_weekdays_names_get(const Evas_Object *obj);
195 * Set weekdays names to be displayed by the calendar.
197 * @param obj The calendar object.
198 * @param weekdays Array of seven strings to be used as weekday names.
199 * @warning It must have 7 elements, or it will access invalid memory.
200 * @warning The strings must be NULL terminated ('@\0').
202 * By default, weekdays abbreviations get from system are displayed:
203 * E.g. for an en_US locale: "Sun, Mon, Tue, Wed, Thu, Fri, Sat"
205 * The first string should be related to Sunday, the second to Monday...
207 * The usage should be like this:
209 * const char *weekdays[] =
211 * "Sunday", "Monday", "Tuesday", "Wednesday",
212 * "Thursday", "Friday", "Saturday"
214 * elm_calendar_weekdays_names_set(calendar, weekdays);
217 * @see elm_calendar_weekdays_name_get()
219 * @ref calendar_example_02
223 EAPI void elm_calendar_weekdays_names_set(Evas_Object *obj, const char *weekdays[]);
226 * Set the minimum and maximum values for the year
228 * @param obj The calendar object
229 * @param min The minimum year, greater than 1901;
230 * @param max The maximum year;
232 * Maximum must be greater than minimum, except if you don't want to set
234 * Default values are 1902 and -1.
236 * If the maximum year is a negative value, it will be limited depending
237 * on the platform architecture (year 2037 for 32 bits);
239 * @see elm_calendar_min_max_year_get()
241 * @ref calendar_example_03
245 EAPI void elm_calendar_min_max_year_set(Evas_Object *obj, int min, int max);
248 * Get the minimum and maximum values for the year
250 * @param obj The calendar object.
251 * @param min The minimum year.
252 * @param max The maximum year.
254 * Default values are 1902 and -1.
256 * @see elm_calendar_min_max_year_get() for more details.
258 * @ref calendar_example_05
262 EAPI void elm_calendar_min_max_year_get(const Evas_Object *obj, int *min, int *max);
265 * Set select day mode to use.
267 * @param obj The calendar object.
268 * @param mode The select mode to use.
270 * Set the day selection mode used.
274 EAPI void elm_calendar_select_mode_set(Evas_Object *obj, Elm_Calendar_Select_Mode mode);
277 * Get the select day mode used.
279 * @param obj The calendar object.
281 * @return the selected mode
283 * Get the day selection mode used.
285 * @see elm_calendar_select_mode_set() for more details
289 EAPI Elm_Calendar_Select_Mode elm_calendar_select_mode_get(const Evas_Object *obj);
292 * Set selected date to be highlighted on calendar.
294 * @param obj The calendar object.
295 * @param selected_time A @b tm struct to represent the selected date.
297 * Set the selected date, changing the displayed month if needed.
298 * Selected date changes when the user goes to next/previous month or
299 * select a day pressing over it on calendar.
301 * @see elm_calendar_selected_time_get()
303 * @ref calendar_example_04
307 EAPI void elm_calendar_selected_time_set(Evas_Object *obj, struct tm *selected_time);
312 * @param obj The calendar object
313 * @param selected_time A @b tm struct to point to selected date
314 * @return EINA_FALSE means an error occurred and returned time shouldn't
317 * Get date selected by the user or set by function
318 * elm_calendar_selected_time_set().
319 * Selected date changes when the user goes to next/previous month or
320 * select a day pressing over it on calendar.
322 * @see elm_calendar_selected_time_get()
324 * @ref calendar_example_05
328 EAPI Eina_Bool elm_calendar_selected_time_get(const Evas_Object *obj, struct tm *selected_time);
331 * Set a function to format the string that will be used to display
334 * @param obj The calendar object
335 * @param format_func Function to set the month-year string given
338 * By default it uses strftime with "%B %Y" format string.
339 * It should allocate the memory that will be used by the string,
340 * that will be freed by the widget after usage.
341 * A pointer to the string and a pointer to the time struct will be provided.
346 * _format_month_year(struct tm *selected_time)
349 * if (!strftime(buf, sizeof(buf), "%B %Y", selected_time)) return NULL;
350 * return strdup(buf);
353 * elm_calendar_format_function_set(calendar, _format_month_year);
356 * @ref calendar_example_02
360 EAPI void elm_calendar_format_function_set(Evas_Object *obj, Elm_Calendar_Format_Cb format_func);
363 * Add a new mark to the calendar
365 * @param obj The calendar object
366 * @param mark_type A string used to define the type of mark. It will be
367 * emitted to the theme, that should display a related modification on these
368 * days representation.
369 * @param mark_time A time struct to represent the date of inclusion of the
370 * mark. For marks that repeats it will just be displayed after the inclusion
371 * date in the calendar.
372 * @param repeat Repeat the event following this periodicity. Can be a unique
373 * mark (that don't repeat), daily, weekly, monthly or annually.
374 * @return The created mark or @p NULL upon failure.
376 * Add a mark that will be drawn in the calendar respecting the insertion
377 * time and periodicity. It will emit the type as signal to the widget theme.
378 * Default theme supports "holiday" and "checked", but it can be extended.
380 * It won't immediately update the calendar, drawing the marks.
381 * For this, call elm_calendar_marks_draw(). However, when user selects
382 * next or previous month calendar forces marks drawn.
384 * Marks created with this method can be deleted with
385 * elm_calendar_mark_del().
389 * struct tm selected_time;
390 * time_t current_time;
392 * current_time = time(NULL) + 5 * 84600;
393 * localtime_r(¤t_time, &selected_time);
394 * elm_calendar_mark_add(cal, "holiday", selected_time,
395 * ELM_CALENDAR_ANNUALLY);
397 * current_time = time(NULL) + 1 * 84600;
398 * localtime_r(¤t_time, &selected_time);
399 * elm_calendar_mark_add(cal, "checked", selected_time, ELM_CALENDAR_UNIQUE);
401 * elm_calendar_marks_draw(cal);
404 * @see elm_calendar_marks_draw()
405 * @see elm_calendar_mark_del()
407 * @ref calendar_example_06
411 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);
414 * Delete mark from the calendar.
416 * @param mark The mark to be deleted.
418 * If deleting all calendar marks is required, elm_calendar_marks_clear()
419 * should be used instead of getting marks list and deleting each one.
421 * @see elm_calendar_mark_add()
423 * @ref calendar_example_06
427 EAPI void elm_calendar_mark_del(Elm_Calendar_Mark *mark);
430 * Remove all calendar's marks
432 * @param obj The calendar object.
434 * @see elm_calendar_mark_add()
435 * @see elm_calendar_mark_del()
439 EAPI void elm_calendar_marks_clear(Evas_Object *obj);
442 * Get a list of all the calendar marks.
444 * @param obj The calendar object.
445 * @return An @c Eina_List of calendar marks objects, or @c NULL on failure.
447 * @see elm_calendar_mark_add()
448 * @see elm_calendar_mark_del()
449 * @see elm_calendar_marks_clear()
453 EAPI const Eina_List *elm_calendar_marks_get(const Evas_Object *obj);
456 * Draw calendar marks.
458 * @param obj The calendar object.
460 * Should be used after adding, removing or clearing marks.
461 * It will go through the entire marks list updating the calendar.
462 * If lots of marks will be added, add all the marks and then call
465 * When the month is changed, i.e. user selects next or previous month,
466 * marks will be drawn.
468 * @see elm_calendar_mark_add()
469 * @see elm_calendar_mark_del()
470 * @see elm_calendar_marks_clear()
472 * @ref calendar_example_06
476 EAPI void elm_calendar_marks_draw(Evas_Object *obj);
479 * Set the interval on time updates for an user mouse button hold
480 * on calendar widgets' month selection.
482 * @param obj The calendar object
483 * @param interval The (first) interval value in seconds
485 * This interval value is @b decreased while the user holds the
486 * mouse pointer either selecting next or previous month.
488 * This helps the user to get to a given month distant from the
489 * current one easier/faster, as it will start to change quicker and
490 * quicker on mouse button holds.
492 * The calculation for the next change interval value, starting from
493 * the one set with this call, is the previous interval divided by
494 * 1.05, so it decreases a little bit.
496 * The default starting interval value for automatic changes is
499 * @see elm_calendar_interval_get()
503 EAPI void elm_calendar_interval_set(Evas_Object *obj, double interval);
506 * Get the interval on time updates for an user mouse button hold
507 * on calendar widgets' month selection.
509 * @param obj The calendar object
510 * @return The (first) interval value, in seconds, set on it
512 * @see elm_calendar_interval_set() for more details
516 EAPI double elm_calendar_interval_get(const Evas_Object *obj);
519 * Set the first day of week to use on calendar widgets'.
521 * @param obj The calendar object
522 * @param day An int which correspond to the first day of the week (Sunday = 0, monday = 1,
527 EAPI void elm_calendar_first_day_of_week_set(Evas_Object *obj, Elm_Calendar_Weekday day);
530 * Get the first day of week, who are used on calendar widgets'.
532 * @param obj The calendar object
533 * @return An int which correspond to the first day of the week (Sunday = 0, monday = 1,
536 * @see elm_calendar_first_day_of_week_set() for more details
540 EAPI Elm_Calendar_Weekday elm_calendar_first_day_of_week_get(const Evas_Object *obj);
543 * Define which fields of a @b tm struct will be taken into account, when
544 * elm_calendar_selected_time_set() is invoked.
546 * @param obj The calendar object
547 * @param selectable A bitmask of Elm_Calendar_Selectable
549 * By Default the bitmask is set to use all fields of a @b tm struct (year,
550 * month and day of the month).
553 * @see elm_calendar_selected_time_set
556 EAPI void elm_calendar_selectable_set(Evas_Object *obj, Elm_Calendar_Selectable selectable);
560 * Get how elm_calendar_selected_time_set manage a date
562 * @param obj The calendar object
563 * @return The flag used to manage a date with a elm_calendar_selected_time_set
566 * @see elm_calendar_selectable_set
567 * @see elm_calendar_selected_time_set
570 EAPI Elm_Calendar_Selectable elm_calendar_selectable_get(const Evas_Object *obj);
573 * Get the current time displayed in the widget
575 * @param obj The calendar object
576 * @param selected_time A @b tm struct to point to displayed date
577 * @return EINA_FALSE means an error occurred. If it's an error the returned
578 * time is zero filled.
583 EAPI Eina_Bool elm_calendar_displayed_time_get(const Evas_Object *obj, struct tm *displayed_time);