2 * @defgroup Calendar Calendar
5 * This is a Calendar widget. Calender widget helps applications to flexibly
6 * display a calender with day of the week, day, year and month. Applications will be
7 * able to choose a specific date that will be reported in the smart_callbacks for
8 * the calendar widget. The APIs of calendar widget let the applications perform
9 * other functions like,
10 * placing marks on specific dates
11 * Setting the bounds for the calendar (minimum and maximum years)
12 * Setting the day names of the week. ( for ex. Thu. or Thursday)
13 * Setting the year and month format.
15 * Signals that you can add callbacks for are:
16 * - @c "changed" - emitted when the date in the calendar is changed.
18 * Supported elm_object common APIs.
19 * @li @ref elm_object_signal_emit
20 * @li @ref elm_object_signal_callback_add
21 * @li @ref elm_object_signal_callback_del
23 * Here is some sample code using it:
24 * @li @ref calendar_example_01
25 * @li @ref calendar_example_02
26 * @li @ref calendar_example_03
27 * @li @ref calendar_example_04
28 * @li @ref calendar_example_05
29 * @li @ref calendar_example_06
33 * @addtogroup Calendar
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;
47 * @enum _Elm_Calendar_Mark_Repeat_Type
48 * @typedef Elm_Calendar_Mark_Repeat_Type
50 * Event periodicity, used to define if a mark should be repeated
51 * @b beyond event's day. It's set when a mark is added.
53 * So, for a mark added to 13th May with periodicity set to WEEKLY,
54 * there will be marks every week after this date. Marks will be displayed
55 * at 13th, 20th, 27th, 3rd June ...
57 * Values don't work as bitmask, only one can be chosen.
59 * @see elm_calendar_mark_add()
63 typedef _Elm_Calendar_Mark_Repeat_Type Elm_Calendar_Mark_Repeat_Type;
75 } _Elm_Calendar_Weekday;
78 * @enum _Elm_Calendar_Weekday
79 * @typedef Elm_Calendar_Weekday
83 * @see elm_calendar_first_day_of_week_set()
87 typedef _Elm_Calendar_Weekday Elm_Calendar_Weekday;
92 ELM_CALENDAR_SELECT_DEFAULT = 0, /**< Default value. a day is always selected. */
93 ELM_CALENDAR_SELECT_ALWAYS, /**< a day is always selected. */
94 ELM_CALENDAR_SELECT_NONE, /**< None of the days can be selected. */
95 ELM_CALENDAR_SELECT_ONDEMAND /**< User may have selected a day or not. (not supported yet)*/
96 } _Elm_Calendar_Select_Mode;
99 * @enum _Elm_Calendar_Select_Mode
100 * @typedef Elm_Calendar_Select_Mode
102 * the mode, who determine how user could select a day
104 * @see elm_calendar_select_mode_set()
108 typedef _Elm_Calendar_Select_Mode Elm_Calendar_Select_Mode;
110 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(). */
113 * @typedef Elm_Calendar_Format_Cb
115 * This callback type is used to format the string that will be used
116 * to display month and year.
118 * @param stime Struct representing time.
119 * @return String representing time that will be set to calendar's text.
121 * @see elm_calendar_format_function_set()
125 typedef char * (*Elm_Calendar_Format_Cb)(struct tm *stime);
128 * Add a new calendar widget to the given parent Elementary
129 * (container) object.
131 * @param parent The parent object.
132 * @return a new calendar widget handle or @c NULL, on errors.
134 * This function inserts a new calendar widget on the canvas.
136 * @ref calendar_example_01
140 EAPI Evas_Object *elm_calendar_add(Evas_Object *parent);
143 * Get weekdays names displayed by the calendar.
145 * @param obj The calendar object.
146 * @return Array of seven strings to be used as weekday names.
148 * By default, weekdays abbreviations get from system are displayed:
149 * E.g. for an en_US locale: "Sun, Mon, Tue, Wed, Thu, Fri, Sat"
150 * The first string is related to Sunday, the second to Monday...
152 * @see elm_calendar_weekdays_name_set()
154 * @ref calendar_example_05
158 EAPI const char **elm_calendar_weekdays_names_get(const Evas_Object *obj);
161 * Set weekdays names to be displayed by the calendar.
163 * @param obj The calendar object.
164 * @param weekdays Array of seven strings to be used as weekday names.
165 * @warning It must have 7 elements, or it will access invalid memory.
166 * @warning The strings must be NULL terminated ('@\0').
168 * By default, weekdays abbreviations get from system are displayed:
169 * E.g. for an en_US locale: "Sun, Mon, Tue, Wed, Thu, Fri, Sat"
171 * The first string should be related to Sunday, the second to Monday...
173 * The usage should be like this:
175 * const char *weekdays[] =
177 * "Sunday", "Monday", "Tuesday", "Wednesday",
178 * "Thursday", "Friday", "Saturday"
180 * elm_calendar_weekdays_names_set(calendar, weekdays);
183 * @see elm_calendar_weekdays_name_get()
185 * @ref calendar_example_02
189 EAPI void elm_calendar_weekdays_names_set(Evas_Object *obj, const char *weekdays[]);
192 * Set the minimum and maximum values for the year
194 * @param obj The calendar object
195 * @param min The minimum year, greater than 1901;
196 * @param max The maximum year;
198 * Maximum must be greater than minimum, except if you don't want to set
200 * Default values are 1902 and -1.
202 * If the maximum year is a negative value, it will be limited depending
203 * on the platform architecture (year 2037 for 32 bits);
205 * @see elm_calendar_min_max_year_get()
207 * @ref calendar_example_03
211 EAPI void elm_calendar_min_max_year_set(Evas_Object *obj, int min, int max);
214 * Get the minimum and maximum values for the year
216 * @param obj The calendar object.
217 * @param min The minimum year.
218 * @param max The maximum year.
220 * Default values are 1902 and -1.
222 * @see elm_calendar_min_max_year_get() for more details.
224 * @ref calendar_example_05
228 EAPI void elm_calendar_min_max_year_get(const Evas_Object *obj, int *min, int *max);
231 * Set select day mode to use.
233 * @param obj The calendar object.
234 * @param select_mdoe The select mode to use.
236 * Set the day selection mode used.
240 EAPI void elm_calendar_select_mode_set(Evas_Object *obj, Elm_Calendar_Select_Mode mode);
243 * Get the select day mode used.
245 * @param obj The calendar object.
247 * @return the selected mode
249 * Get the day selection mode used.
251 * @see elm_calendar_select_mode_set() for more details
255 EAPI Elm_Calendar_Select_Mode elm_calendar_select_mode_get(const Evas_Object *obj);
258 * Set selected date to be highlighted on calendar.
260 * @param obj The calendar object.
261 * @param selected_time A @b tm struct to represent the selected date.
263 * Set the selected date, changing the displayed month if needed.
264 * Selected date changes when the user goes to next/previous month or
265 * select a day pressing over it on calendar.
267 * @see elm_calendar_selected_time_get()
269 * @ref calendar_example_04
273 EAPI void elm_calendar_selected_time_set(Evas_Object *obj, struct tm *selected_time);
278 * @param obj The calendar object
279 * @param selected_time A @b tm struct to point to selected date
280 * @return EINA_FALSE means an error occurred and returned time shouldn't
283 * Get date selected by the user or set by function
284 * elm_calendar_selected_time_set().
285 * Selected date changes when the user goes to next/previous month or
286 * select a day pressing over it on calendar.
288 * @see elm_calendar_selected_time_get()
290 * @ref calendar_example_05
294 EAPI Eina_Bool elm_calendar_selected_time_get(const Evas_Object *obj, struct tm *selected_time);
297 * Set a function to format the string that will be used to display
300 * @param obj The calendar object
301 * @param format_func Function to set the month-year string given
304 * By default it uses strftime with "%B %Y" format string.
305 * It should allocate the memory that will be used by the string,
306 * that will be freed by the widget after usage.
307 * A pointer to the string and a pointer to the time struct will be provided.
312 * _format_month_year(struct tm *selected_time)
315 * if (!strftime(buf, sizeof(buf), "%B %Y", selected_time)) return NULL;
316 * return strdup(buf);
319 * elm_calendar_format_function_set(calendar, _format_month_year);
322 * @ref calendar_example_02
326 EAPI void elm_calendar_format_function_set(Evas_Object *obj, Elm_Calendar_Format_Cb format_func);
329 * Add a new mark to the calendar
331 * @param obj The calendar object
332 * @param mark_type A string used to define the type of mark. It will be
333 * emitted to the theme, that should display a related modification on these
334 * days representation.
335 * @param mark_time A time struct to represent the date of inclusion of the
336 * mark. For marks that repeats it will just be displayed after the inclusion
337 * date in the calendar.
338 * @param repeat Repeat the event following this periodicity. Can be a unique
339 * mark (that don't repeat), daily, weekly, monthly or annually.
340 * @return The created mark or @p NULL upon failure.
342 * Add a mark that will be drawn in the calendar respecting the insertion
343 * time and periodicity. It will emit the type as signal to the widget theme.
344 * Default theme supports "holiday" and "checked", but it can be extended.
346 * It won't immediately update the calendar, drawing the marks.
347 * For this, call elm_calendar_marks_draw(). However, when user selects
348 * next or previous month calendar forces marks drawn.
350 * Marks created with this method can be deleted with
351 * elm_calendar_mark_del().
355 * struct tm selected_time;
356 * time_t current_time;
358 * current_time = time(NULL) + 5 * 84600;
359 * localtime_r(¤t_time, &selected_time);
360 * elm_calendar_mark_add(cal, "holiday", selected_time,
361 * ELM_CALENDAR_ANNUALLY);
363 * current_time = time(NULL) + 1 * 84600;
364 * localtime_r(¤t_time, &selected_time);
365 * elm_calendar_mark_add(cal, "checked", selected_time, ELM_CALENDAR_UNIQUE);
367 * elm_calendar_marks_draw(cal);
370 * @see elm_calendar_marks_draw()
371 * @see elm_calendar_mark_del()
373 * @ref calendar_example_06
377 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);
380 * Delete mark from the calendar.
382 * @param mark The mark to be deleted.
384 * If deleting all calendar marks is required, elm_calendar_marks_clear()
385 * should be used instead of getting marks list and deleting each one.
387 * @see elm_calendar_mark_add()
389 * @ref calendar_example_06
393 EAPI void elm_calendar_mark_del(Elm_Calendar_Mark *mark);
396 * Remove all calendar's marks
398 * @param obj The calendar object.
400 * @see elm_calendar_mark_add()
401 * @see elm_calendar_mark_del()
405 EAPI void elm_calendar_marks_clear(Evas_Object *obj);
408 * Get a list of all the calendar marks.
410 * @param obj The calendar object.
411 * @return An @c Eina_List of calendar marks objects, or @c NULL on failure.
413 * @see elm_calendar_mark_add()
414 * @see elm_calendar_mark_del()
415 * @see elm_calendar_marks_clear()
419 EAPI const Eina_List *elm_calendar_marks_get(const Evas_Object *obj);
422 * Draw calendar marks.
424 * @param obj The calendar object.
426 * Should be used after adding, removing or clearing marks.
427 * It will go through the entire marks list updating the calendar.
428 * If lots of marks will be added, add all the marks and then call
431 * When the month is changed, i.e. user selects next or previous month,
432 * marks will be drawn.
434 * @see elm_calendar_mark_add()
435 * @see elm_calendar_mark_del()
436 * @see elm_calendar_marks_clear()
438 * @ref calendar_example_06
442 EAPI void elm_calendar_marks_draw(Evas_Object *obj);
445 * Set the interval on time updates for an user mouse button hold
446 * on calendar widgets' month selection.
448 * @param obj The calendar object
449 * @param interval The (first) interval value in seconds
451 * This interval value is @b decreased while the user holds the
452 * mouse pointer either selecting next or previous month.
454 * This helps the user to get to a given month distant from the
455 * current one easier/faster, as it will start to change quicker and
456 * quicker on mouse button holds.
458 * The calculation for the next change interval value, starting from
459 * the one set with this call, is the previous interval divided by
460 * 1.05, so it decreases a little bit.
462 * The default starting interval value for automatic changes is
465 * @see elm_calendar_interval_get()
469 EAPI void elm_calendar_interval_set(Evas_Object *obj, double interval);
472 * Get the interval on time updates for an user mouse button hold
473 * on calendar widgets' month selection.
475 * @param obj The calendar object
476 * @return The (first) interval value, in seconds, set on it
478 * @see elm_calendar_interval_set() for more details
482 EAPI double elm_calendar_interval_get(const Evas_Object *obj);
485 * Set the first day of week to use on calendar widgets'.
487 * @param obj The calendar object
488 * @param day An int which correspond to the first day of the week (Sunday = 0, monday = 1,
493 EAPI void elm_calendar_first_day_of_week_set(Evas_Object *obj, Elm_Calendar_Weekday day);
496 * Get the first day of week, who are used on calendar widgets'.
498 * @param obj The calendar object
499 * @return An int which correspond to the first day of the week (Sunday = 0, monday = 1,
502 * @see elm_calendar_first_day_of_week_set() for more details
506 EAPI Elm_Calendar_Weekday elm_calendar_first_day_of_week_get(const Evas_Object *obj);