2 * @defgroup Calendar Calendar
4 * This is a Calendar widget.
5 * XXX: add more documentation.
7 * Signals that you can add callbacks for are:
8 * - @c "changed" - XXX: add docs
10 * Supported elm_object common APIs.
11 * @li elm_object_signal_emit
12 * @li elm_object_signal_callback_add
13 * @li elm_object_signal_callback_del
18 * @addtogroup Calendar
23 * @enum _Elm_Calendar_Mark_Repeat
24 * @typedef Elm_Calendar_Mark_Repeat
26 * Event periodicity, used to define if a mark should be repeated
27 * @b beyond event's day. It's set when a mark is added.
29 * So, for a mark added to 13th May with periodicity set to WEEKLY,
30 * there will be marks every week after this date. Marks will be displayed
31 * at 13th, 20th, 27th, 3rd June ...
33 * Values don't work as bitmask, only one can be chosen.
35 * @see elm_calendar_mark_add()
41 ELM_CALENDAR_UNIQUE, /**< Default value. Marks will be displayed only on event day. */
42 ELM_CALENDAR_DAILY, /**< Marks will be displayed everyday after event day (inclusive). */
43 ELM_CALENDAR_WEEKLY, /**< Marks will be displayed every week after event day (inclusive) - i.e. each seven days. */
44 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*/
45 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. */
46 } Elm_Calendar_Mark_Repeat;
47 // XXX: Elm_Calendar_Mark_Repeat_Type
49 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(). */
52 * Add a new calendar widget to the given parent Elementary
55 * @param parent The parent object.
56 * @return a new calendar widget handle or @c NULL, on errors.
58 * This function inserts a new calendar widget on the canvas.
60 * @ref calendar_example_01
64 EAPI Evas_Object *elm_calendar_add(Evas_Object *parent);
67 * Get weekdays names displayed by the calendar.
69 * @param obj The calendar object.
70 * @return Array of seven strings to be used as weekday names.
72 * By default, weekdays abbreviations get from system are displayed:
73 * E.g. for an en_US locale: "Sun, Mon, Tue, Wed, Thu, Fri, Sat"
74 * The first string is related to Sunday, the second to Monday...
76 * @see elm_calendar_weekdays_name_set()
78 * @ref calendar_example_05
82 EAPI const char **elm_calendar_weekdays_names_get(const Evas_Object *obj);
85 * Set weekdays names to be displayed by the calendar.
87 * @param obj The calendar object.
88 * @param weekdays Array of seven strings to be used as weekday names.
89 * @warning It must have 7 elements, or it will access invalid memory.
90 * @warning The strings must be NULL terminated ('@\0').
92 * By default, weekdays abbreviations get from system are displayed:
93 * E.g. for an en_US locale: "Sun, Mon, Tue, Wed, Thu, Fri, Sat"
95 * The first string should be related to Sunday, the second to Monday...
97 * The usage should be like this:
99 * const char *weekdays[] =
101 * "Sunday", "Monday", "Tuesday", "Wednesday",
102 * "Thursday", "Friday", "Saturday"
104 * elm_calendar_weekdays_names_set(calendar, weekdays);
107 * @see elm_calendar_weekdays_name_get()
109 * @ref calendar_example_02
113 EAPI void elm_calendar_weekdays_names_set(Evas_Object *obj, const char *weekdays[]);
116 * Set the minimum and maximum values for the year
118 * @param obj The calendar object
119 * @param min The minimum year, greater than 1901;
120 * @param max The maximum year;
122 * Maximum must be greater than minimum, except if you don't want to set
124 * Default values are 1902 and -1.
126 * If the maximum year is a negative value, it will be limited depending
127 * on the platform architecture (year 2037 for 32 bits);
129 * @see elm_calendar_min_max_year_get()
131 * @ref calendar_example_03
135 EAPI void elm_calendar_min_max_year_set(Evas_Object *obj, int min, int max);
138 * Get the minimum and maximum values for the year
140 * @param obj The calendar object.
141 * @param min The minimum year.
142 * @param max The maximum year.
144 * Default values are 1902 and -1.
146 * @see elm_calendar_min_max_year_get() for more details.
148 * @ref calendar_example_05
152 EAPI void elm_calendar_min_max_year_get(const Evas_Object *obj, int *min, int *max);
155 * Enable or disable day selection
157 * @param obj The calendar object.
158 * @param enabled @c EINA_TRUE to enable selection or @c EINA_FALSE to
161 * Enabled by default. If disabled, the user still can select months,
162 * but not days. Selected days are highlighted on calendar.
163 * It should be used if you won't need such selection for the widget usage.
165 * When a day is selected, or month is changed, smart callbacks for
166 * signal "changed" will be called.
168 * @see elm_calendar_day_selection_enable_get()
170 * @ref calendar_example_04
174 // XXX: use disabled_set. it's enabled by default.
175 // EAPI void elm_calendar_day_selection_disabled_set(Evas_Object *obj, Eina_Bool disabled);
176 EAPI void elm_calendar_day_selection_enabled_set(Evas_Object *obj, Eina_Bool enabled);
179 * Get a value whether day selection is enabled or not.
181 * @see elm_calendar_day_selection_enable_set() for details.
183 * @param obj The calendar object.
184 * @return EINA_TRUE means day selection is enabled. EINA_FALSE indicates
185 * it's disabled. If @p obj is NULL, EINA_FALSE is returned.
187 * @ref calendar_example_05
191 // XXX: use disabled_get. it's enabled by default.
192 // EAPI Eina_Bool elm_calendar_day_selection_disabled_get(const Evas_Object *obj);
193 EAPI Eina_Bool elm_calendar_day_selection_enabled_get(const Evas_Object *obj);
196 * Set selected date to be highlighted on calendar.
198 * @param obj The calendar object.
199 * @param selected_time A @b tm struct to represent the selected date.
201 * Set the selected date, changing the displayed month if needed.
202 * Selected date changes when the user goes to next/previous month or
203 * select a day pressing over it on calendar.
205 * @see elm_calendar_selected_time_get()
207 * @ref calendar_example_04
211 EAPI void elm_calendar_selected_time_set(Evas_Object *obj, struct tm *selected_time);
216 * @param obj The calendar object
217 * @param selected_time A @b tm struct to point to selected date
218 * @return EINA_FALSE means an error occurred and returned time shouldn't
221 * Get date selected by the user or set by function
222 * elm_calendar_selected_time_set().
223 * Selected date changes when the user goes to next/previous month or
224 * select a day pressing over it on calendar.
226 * @see elm_calendar_selected_time_get()
228 * @ref calendar_example_05
232 EAPI Eina_Bool elm_calendar_selected_time_get(const Evas_Object *obj, struct tm *selected_time);
235 * Set a function to format the string that will be used to display
238 * @param obj The calendar object
239 * @param format_function Function to set the month-year string given
242 * By default it uses strftime with "%B %Y" format string.
243 * It should allocate the memory that will be used by the string,
244 * that will be freed by the widget after usage.
245 * A pointer to the string and a pointer to the time struct will be provided.
250 * _format_month_year(struct tm *selected_time)
253 * if (!strftime(buf, sizeof(buf), "%B %Y", selected_time)) return NULL;
254 * return strdup(buf);
257 * elm_calendar_format_function_set(calendar, _format_month_year);
260 * @ref calendar_example_02
264 EAPI void elm_calendar_format_function_set(Evas_Object *obj, char *(*format_function)(struct tm *stime));
267 * Add a new mark to the calendar
269 * @param obj The calendar object
270 * @param mark_type A string used to define the type of mark. It will be
271 * emitted to the theme, that should display a related modification on these
272 * days representation.
273 * @param mark_time A time struct to represent the date of inclusion of the
274 * mark. For marks that repeats it will just be displayed after the inclusion
275 * date in the calendar.
276 * @param repeat Repeat the event following this periodicity. Can be a unique
277 * mark (that don't repeat), daily, weekly, monthly or annually.
278 * @return The created mark or @p NULL upon failure.
280 * Add a mark that will be drawn in the calendar respecting the insertion
281 * time and periodicity. It will emit the type as signal to the widget theme.
282 * Default theme supports "holiday" and "checked", but it can be extended.
284 * It won't immediately update the calendar, drawing the marks.
285 * For this, call elm_calendar_marks_draw(). However, when user selects
286 * next or previous month calendar forces marks drawn.
288 * Marks created with this method can be deleted with
289 * elm_calendar_mark_del().
293 * struct tm selected_time;
294 * time_t current_time;
296 * current_time = time(NULL) + 5 * 84600;
297 * localtime_r(¤t_time, &selected_time);
298 * elm_calendar_mark_add(cal, "holiday", selected_time,
299 * ELM_CALENDAR_ANNUALLY);
301 * current_time = time(NULL) + 1 * 84600;
302 * localtime_r(¤t_time, &selected_time);
303 * elm_calendar_mark_add(cal, "checked", selected_time, ELM_CALENDAR_UNIQUE);
305 * elm_calendar_marks_draw(cal);
308 * @see elm_calendar_marks_draw()
309 * @see elm_calendar_mark_del()
311 * @ref calendar_example_06
315 EAPI Elm_Calendar_Mark *elm_calendar_mark_add(Evas_Object *obj, const char *mark_type, struct tm *mark_time, Elm_Calendar_Mark_Repeat repeat);
318 * Delete mark from the calendar.
320 * @param mark The mark to be deleted.
322 * If deleting all calendar marks is required, elm_calendar_marks_clear()
323 * should be used instead of getting marks list and deleting each one.
325 * @see elm_calendar_mark_add()
327 * @ref calendar_example_06
331 EAPI void elm_calendar_mark_del(Elm_Calendar_Mark *mark);
334 * Remove all calendar's marks
336 * @param obj The calendar object.
338 * @see elm_calendar_mark_add()
339 * @see elm_calendar_mark_del()
343 EAPI void elm_calendar_marks_clear(Evas_Object *obj);
346 * Get a list of all the calendar marks.
348 * @param obj The calendar object.
349 * @return An @c Eina_List of calendar marks objects, or @c NULL on failure.
351 * @see elm_calendar_mark_add()
352 * @see elm_calendar_mark_del()
353 * @see elm_calendar_marks_clear()
357 EAPI const Eina_List *elm_calendar_marks_get(const Evas_Object *obj);
360 * Draw calendar marks.
362 * @param obj The calendar object.
364 * Should be used after adding, removing or clearing marks.
365 * It will go through the entire marks list updating the calendar.
366 * If lots of marks will be added, add all the marks and then call
369 * When the month is changed, i.e. user selects next or previous month,
370 * marks will be drawn.
372 * @see elm_calendar_mark_add()
373 * @see elm_calendar_mark_del()
374 * @see elm_calendar_marks_clear()
376 * @ref calendar_example_06
380 EAPI void elm_calendar_marks_draw(Evas_Object *obj);
383 * Set the interval on time updates for an user mouse button hold
384 * on calendar widgets' month selection.
386 * @param obj The calendar object
387 * @param interval The (first) interval value in seconds
389 * This interval value is @b decreased while the user holds the
390 * mouse pointer either selecting next or previous month.
392 * This helps the user to get to a given month distant from the
393 * current one easier/faster, as it will start to change quicker and
394 * quicker on mouse button holds.
396 * The calculation for the next change interval value, starting from
397 * the one set with this call, is the previous interval divided by
398 * 1.05, so it decreases a little bit.
400 * The default starting interval value for automatic changes is
403 * @see elm_calendar_interval_get()
407 EAPI void elm_calendar_interval_set(Evas_Object *obj, double interval);
410 * Get the interval on time updates for an user mouse button hold
411 * on calendar widgets' month selection.
413 * @param obj The calendar object
414 * @return The (first) interval value, in seconds, set on it
416 * @see elm_calendar_interval_set() for more details
420 EAPI double elm_calendar_interval_get(const Evas_Object *obj);