2 * @defgroup Datetime Datetime
5 * @image html datetime_inheritance_tree.png
6 * @image latex datetime_inheritance_tree.eps
8 * @image html img/widget/datetime/preview-00.png
9 * @image latex img/widget/datetime/preview-00.eps
11 * @image html img/widget/datetime/preview-01.png
12 * @image latex img/widget/datetime/preview-01.eps
14 * @image html img/widget/datetime/preview-02.png
15 * @image latex img/widget/datetime/preview-02.eps
17 * Datetime widget is used to display and input date & time values.
18 * This widget displays date and time as per the <b>system's locale</b> settings (Date
19 * includes Day, Month & Year along with the defined separators and
20 * Time includes Hour, Minute & AM/PM fields. Separator for AM/PM field is ignored.
22 * The corresponding Month, AM/PM strings are displayed according to the
23 * system’s language settings.
25 * Datetime format is a combination of LIBC standard characters like
26 * “%%d %%b %%Y %%I : %%M %%p” which, as a whole represents both Date as well as Time
29 * Elm_datetime supports only the following sub set of libc date format specifiers:
31 * @b %%Y : The year as a decimal number including the century (example: 2011).
33 * @b %%y : The year as a decimal number without a century (range 00 to 99)
35 * @b %%m : The month as a decimal number (range 01 to 12).
37 * @b %%b : The abbreviated month name according to the current locale.
39 * @b %%B : The full month name according to the current locale.
41 * @b %%h : The abbreviated month name according to the current locale(same as %%b).
43 * @b %%d : The day of the month as a decimal number (range 01 to 31).
45 * @b %%e : The day of the month as a decimal number (range 1 to 31). single
46 * digits are preceded by a blank.
48 * @b %%I : The hour as a decimal number using a 12-hour clock (range 01 to 12).
50 * @b %%H : The hour as a decimal number using a 24-hour clock (range 00 to 23).
52 * @b %%k : The hour (24-hour clock) as a decimal number (range 0 to 23). single
53 * digits are preceded by a blank.
55 * @b %%l : The hour (12-hour clock) as a decimal number (range 1 to 12); single
56 * digits are preceded by a blank.
58 * @b %%M : The minute as a decimal number (range 00 to 59).
60 * @b %%p : Either 'AM' or 'PM' according to the given time value, or the
61 * corresponding strings for the current locale. Noon is treated as 'PM'
62 * and midnight as 'AM'
64 * @b %%P : Like %p but in lower case: 'am' or 'pm' or a corresponding string for
67 * @b %%c : The preferred date and time representation for the current locale.
69 * @b %%x : The preferred date representation for the current locale without the time.
71 * @b %%X : The preferred time representation for the current locale without the date.
73 * @b %%r : The complete calendar time using the AM/PM format of the current locale.
75 * @b %%R : The hour and minute in decimal numbers using the format %H:%M.
77 * @b %%T : The time of day in decimal numbers using the format %H:%M:%S.
79 * @b %%D : The date using the format %%m/%%d/%%y.
81 * @b %%F : The date using the format %%Y-%%m-%%d.
83 * (For more reference on the available <b>LIBC date format specifiers</b>, please
85 * http://www.gnu.org/s/hello/manual/libc.html#Formatting-Calendar-Time )
87 * Datetime widget can provide Unicode @b separators in between its fields
88 * except for AM/PM field.
89 * A separator can be any <b>Unicode character</b> other than the LIBC standard
90 * date format specifiers.( Example: In the format %%b %%d @b , %%y %%H @b : %%M
91 * comma(,) is separator for date field %%d and colon(:) is separator for
94 * The default format is a predefined one, based on the system Locale.
96 * Hour format 12hr(1-12) or 24hr(0-23) display can be selected by setting
97 * the corresponding user format.
99 * Datetime supports six fields: Year, Month, Date, Hour, Minute, AM/PM.
100 * Depending on the Datetime module that is loaded, the user can see
101 * different UI to select the individual field values.
103 * The individual fields of Datetime can be arranged in any order according to the format
104 * set by application.
106 * There is a provision to set the visibility of a particular field as TRUE/ FALSE
107 * so that <b>only time/ only date / only required fields</b> will be displayed.
109 * Each field is having a default minimum and maximum values just like the daily
110 * calendar information. These min/max values can be modified as per the application usage.
112 * User can enter the values only in between the range of maximum and minimum.
113 * Apart from these APIs, there is a provision to display only a limited set of
114 * values out of the possible values. APIs to select the individual field limits
115 * are intended for this purpose.
117 * The whole widget is left aligned and its size grows horizontally depending
118 * on the current format and each field's visible/disabled state.
120 * Datetime individual field selection is implemented in a modular style.
121 * Module can be implemented as a Ctxpopup based selection or an ISE based
122 * selection or even a spinner like selection etc.
124 * <b>Datetime Module design:</b>
126 * The following functions are expected to be implemented in a Datetime module:
128 * <b>Field creation:</b>
131 * __________ __________
132 * | |----- obj_hook() ---------------------->>>| |
133 * | |<<<----------------returns Mod_data ------| |
134 * | Datetime |_______ | |
135 * | widget | |Assign module call backs | Module |
136 * | base |<<<____| | |
138 * | |----- field_create() ------------------>>>| |
139 * |__________|<<<----------------returns field_obj -----|__________|
143 * <b>Field value setting:</b>
146 * __________ __________
148 * | Datetime |<<<----------elm_datetime_value_set()---| |
149 * | widget | | Module |
150 * | base |----display_field_value()------------>>>| |
151 * |__________| |__________|
157 * __________ __________
159 * | Datetime |----obj_unhook()-------------------->>>>| |
160 * | widget | | Module |
161 * | base | <<<-----frees mod_data---------| |
162 * |__________| |__________|
167 * Any module can use the following shared functions that are implemented in elm_datetime.c :
169 * <b>field_format_get()</b> - gives the field format.
171 * <b>field_limit_get()</b> - gives the field minimum, maximum limits.
173 * To enable a module, set the ELM_MODULES environment variable as shown:
175 * <b>export ELM_MODULES="datetime_input_ctxpopup>datetime/api"</b>
177 * This widget inherits from the @ref Layout one, so that all the
178 * functions acting on it also work for datetime objects.
180 * This widget emits the following signals, besides the ones sent from
182 * @li @b "changed" - whenever Datetime field value is changed, this
185 * @li @b "language,changed" - whenever system locale changes, this
188 * Here is an example on its usage:
189 * @li @ref datetime_example
194 * @addtogroup Datetime
199 * Identifies a Datetime field, The widget supports 6 fields : Year, month,
200 * Date, Hour, Minute, AM/PM
203 typedef enum _Elm_Datetime_Field_Type
205 ELM_DATETIME_YEAR = 0, /**< Indicates Year field */
206 ELM_DATETIME_MONTH = 1, /**< Indicates Month field */
207 ELM_DATETIME_DATE = 2, /**< Indicates Date field */
208 ELM_DATETIME_HOUR = 3, /**< Indicates Hour field */
209 ELM_DATETIME_MINUTE = 4, /**< Indicates Minute field */
210 ELM_DATETIME_AMPM = 5, /**< Indicates AM/PM field */
211 } Elm_Datetime_Field_Type;
214 * @brief Adds a new datetime Widget
216 * The default datetime format and corresponding strings are based on current locale.
218 * @param parent The parent object
219 * @return The new object or NULL if it cannot be created
221 * This function inserts a new datetime widget on the canvas.
225 EAPI Evas_Object *elm_datetime_add(Evas_Object *parent);
228 * Get the datetime format. Format is a combination of allowed Libc date format
229 * specifiers like: "%b %d, %Y %I : %M %p".
231 * Maximum allowed format length is 64 chars.
233 * Format can include separators for each individual datetime field except
236 * Each separator can be a maximum of 6 UTF-8 bytes.
237 * Space is also taken as a separator.
239 * Following are the allowed set of format specifiers for each datetime field.
241 * @b %%Y : The year as a decimal number including the century.
243 * @b %%y : The year as a decimal number without a century (range 00 to 99).
245 * @b %%m : The month as a decimal number (range 01 to 12).
247 * @b %%b : The abbreviated month name according to the current locale.
249 * @b %%B : The full month name according to the current locale.
251 * @b %%h : The abbreviated month name according to the current locale(same as %%b).
253 * @b %%d : The day of the month as a decimal number (range 01 to 31).
255 * @b %%e : The day of the month as a decimal number (range 1 to 31). single
256 * digits are preceded by a blank.
258 * @b %%I : The hour as a decimal number using a 12-hour clock (range 01 to 12).
260 * @b %%H : The hour as a decimal number using a 24-hour clock (range 00 to 23).
262 * @b %%k : The hour (24-hour clock) as a decimal number (range 0 to 23). single
263 * digits are preceded by a blank.
265 * @b %%l : The hour (12-hour clock) as a decimal number (range 1 to 12); single
266 * digits are preceded by a blank.
268 * @b %%M : The minute as a decimal number (range 00 to 59).
270 * @b %%p : Either 'AM' or 'PM' according to the given time value, or the
271 * corresponding strings for the current locale. Noon is treated as 'PM'
272 * and midnight as 'AM'.
274 * @b %%P : Like %p but in lower case: 'am' or 'pm' or a corresponding string for
275 * the current locale.
277 * @b %%c : The preferred date and time representation for the current locale.
279 * @b %%x : The preferred date representation for the current locale without the time.
281 * @b %%X : The preferred time representation for the current locale without the date.
283 * @b %%r : The complete calendar time using the AM/PM format of the current locale.
285 * @b %%R : The hour and minute in decimal numbers using the format %H:%M.
287 * @b %%T : The time of day in decimal numbers using the format %H:%M:%S.
289 * @b %%D : The date using the format %%m/%%d/%%y.
291 * @b %%F : The date using the format %%Y-%%m-%%d.
293 * These specifiers can be arranged in any order and the widget will display the
294 * fields accordingly.
296 * Default format is taken as per the system locale settings.
298 * @param obj The datetime object
299 * @return The datetime format string. Example: "%b %d, %Y %I : %M %p"
301 * @see elm_datetime_format_set()
304 EAPI const char *elm_datetime_format_get(const Evas_Object *obj);
307 * Set the datetime format. Format is a combination of allowed Libc date format
308 * specifiers like: "%b %d, %Y %I : %M %p".
310 * Maximum allowed format length is 64 chars.
312 * Format can include separators for each individual datetime field except
315 * Each separator can be a maximum of 6 UTF-8 bytes.
316 * Space is also taken as a separator.
318 * Following are the allowed set of format specifiers for each datetime field.
320 * @b %%Y : The year as a decimal number including the century.
322 * @b %%y : The year as a decimal number without a century (range 00 to 99).
324 * @b %%m : The month as a decimal number (range 01 to 12).
326 * @b %%b : The abbreviated month name according to the current locale.
328 * @b %%B : The full month name according to the current locale.
330 * @b %%h : The abbreviated month name according to the current locale(same as %%b).
332 * @b %%d : The day of the month as a decimal number (range 01 to 31).
334 * @b %%e : The day of the month as a decimal number (range 1 to 31). single
335 * digits are preceded by a blank.
337 * @b %%I : The hour as a decimal number using a 12-hour clock (range 01 to 12).
339 * @b %%H : The hour as a decimal number using a 24-hour clock (range 00 to 23).
341 * @b %%k : The hour (24-hour clock) as a decimal number (range 0 to 23). single
342 * digits are preceded by a blank.
344 * @b %%l : The hour (12-hour clock) as a decimal number (range 1 to 12); single
345 * digits are preceded by a blank.
347 * @b %%M : The minute as a decimal number (range 00 to 59).
349 * @b %%p : Either 'AM' or 'PM' according to the given time value, or the
350 * corresponding strings for the current locale. Noon is treated as 'PM'
351 * and midnight as 'AM'.
353 * @b %%P : Like %p but in lower case: 'am' or 'pm' or a corresponding string for
354 * the current locale.
356 * @b %%c : The preferred date and time representation for the current locale.
358 * @b %%x : The preferred date representation for the current locale without the time.
360 * @b %%X : The preferred time representation for the current locale without the date.
362 * @b %%r : The complete calendar time using the AM/PM format of the current locale.
364 * @b %%R : The hour and minute in decimal numbers using the format %H:%M.
366 * @b %%T : The time of day in decimal numbers using the format %H:%M:%S.
368 * @b %%D : The date using the format %%m/%%d/%%y.
370 * @b %%F : The date using the format %%Y-%%m-%%d.
372 * These specifiers can be arranged in any order and the widget will display the
373 * fields accordingly.
375 * Default format is taken as per the system locale settings.
377 * @param obj The datetime object
378 * @param fmt The datetime format
380 * @see elm_datetime_format_get()
383 EAPI void elm_datetime_format_set(Evas_Object *obj, const char *fmt);
386 * @brief Get the upper boundary of a field.
388 * Year: years since 1900. Negative value represents year below 1900 (year
389 * value -30 represents 1870). Year default range is from 70 to 137.
391 * Month: default value range is from 0 to 11.
393 * Date: default value range is from 1 to 31 according to the month value.
395 * Hour: default value will be in terms of 24 hr format (0~23)
397 * Minute: default value range is from 0 to 59.
399 * @param obj The datetime object
400 * @param maxtime Time structure containing the maximum time value.
401 * @return EINA_TRUE if maximum value is returned successfully.
403 * @see elm_datetime_value_max_set()
406 EAPI Eina_Bool elm_datetime_value_max_get(const Evas_Object *obj, struct tm *maxtime);
409 * @brief Set the upper boundary of a field.
411 * Year: years since 1900. Negative value represents year below 1900 (year
412 * value -30 represents 1870). Year default range is from 70 to 137.
414 * Month: default value range is from 0 to 11.
416 * Date: default value range is from 1 to 31 according to the month value.
418 * Hour: default value will be in terms of 24 hr format (0~23)
420 * Minute: default value range is from 0 to 59.
422 * @param obj The datetime object
423 * @param maxtime Time structure containing the maximum time value.
424 * @return EINA_TRUE if maximum value is accepted.
426 * @see elm_datetime_value_max_get()
429 EAPI Eina_Bool elm_datetime_value_max_set(Evas_Object *obj, const struct tm *maxtime);
432 * @brief Get the lower boundary of a field.
434 * Year: years since 1900. Negative value represents year below 1900 (year
435 * value -30 represents 1870). Year default range is from 70 to 137.
437 * Month: default value range is from 0 to 11.
439 * Date: default value range is from 1 to 31 according to the month value.
441 * Hour: default value will be in terms of 24 hr format (0~23)
443 * Minute: default value range is from 0 to 59.
445 * @param obj The datetime object
446 * @param mintime Time structure.
447 * @return EINA_TRUE if minimum value is successfully returned.
449 * @see elm_datetime_value_min_set()
450 * @ingroup Datepicker
452 EAPI Eina_Bool elm_datetime_value_min_get(const Evas_Object *obj, struct tm *mintime);
455 * @brief Set the lower boundary of a field.
457 * Year: years since 1900. Negative value represents year below 1900 (year
458 * value -30 represents 1870). Year default range is from 70 to 137.
460 * Month: default value range is from 0 to 11.
462 * Date: default value range is from 1 to 31 according to the month value.
464 * Hour: default value will be in terms of 24 hr format (0~23)
466 * Minute: default value range is from 0 to 59.
468 * @param obj The datetime object.
469 * @param mintime Time structure containing the minimum time value.
470 * @return EINA_TRUE if minimum value is accepted.
472 * @see elm_datetime_value_min_get()
475 EAPI Eina_Bool elm_datetime_value_min_set(Evas_Object *obj, const struct tm *mintime);
478 * @brief Get the field limits of a field.
480 * Limits can be set to individual fields, independently, except for AM/PM field.
481 * Any field can display the values only in between these Minimum and Maximum limits unless
482 * the corresponding time value is restricted from MinTime to MaxTime.
483 * That is, Min/ Max field limits always works under the limitations of MinTime/ MaxTime.
485 * There is no provision to set the limits of AM/PM field.
487 * @param obj The datetime object
488 * @param fieldtype Type of the field. ELM_DATETIME_YEAR etc.
489 * @param min Reference to field's minimum value
490 * @param max Reference to field's maximum value
492 * @see elm_datetime_field_limit_set()
495 EAPI void elm_datetime_field_limit_get(const Evas_Object *obj, Elm_Datetime_Field_Type fieldtype, int *min, int *max);
498 * @brief Set the field limits of a field.
500 * Limits can be set to individual fields, independently, except for AM/PM field.
501 * Any field can display the values only in between these Minimum and Maximum limits unless
502 * the corresponding time value is restricted from MinTime to MaxTime.
503 * That is, Min/ Max field limits always works under the limitations of MinTime/ MaxTime.
505 * There is no provision to set the limits of AM/PM field.
507 * @param obj The datetime object
508 * @param fieldtype Type of the field. ELM_DATETIME_YEAR etc.
509 * @param min Reference to field's minimum value
510 * @param max Reference to field's maximum value
512 * @see elm_datetime_field_limit_set()
515 EAPI void elm_datetime_field_limit_set(Evas_Object *obj, Elm_Datetime_Field_Type fieldtype, int min, int max);
518 * @brief Get the current value of a field.
520 * Year: years since 1900. Negative value represents year below 1900 (year
521 * value -30 represents 1870). Year default range is from 70 to 137.
523 * Month: default value range is from 0 to 11.
525 * Date: default value range is from 1 to 31 according to the month value.
527 * Hour: default value will be in terms of 24 hr format (0~23)
529 * Minute: default value range is from 0 to 59.
531 * @param obj The datetime object.
532 * @param currtime Time structure.
533 * @return EINA_TRUE if current time is returned successfully.
535 * @see elm_datetime_field_value_set()
538 EAPI Eina_Bool elm_datetime_value_get(const Evas_Object *obj, struct tm *currtime);
541 * @brief Set the current value of a Datetime object.
543 * Year: years since 1900. Negative value represents year below 1900 (year
544 * value -30 represents 1870). Year default range is from 70 to 137.
546 * Month: default value range is from 0 to 11.
548 * Date: default value range is from 1 to 31 according to the month value.
550 * Hour: default value will be in terms of 24 hr format (0~23)
552 * Minute: default value range is from 0 to 59.
555 * @param obj The datetime object.
556 * @param newtime Time structure filled with values to be set.
557 * @return EINA_TRUE if current time is set successfully.
559 * @see elm_datetime_value_set()
562 EAPI Eina_Bool elm_datetime_value_set(Evas_Object *obj, const struct tm *newtime);
565 * @brief Get whether a field can be visible/not
567 * @param obj The datetime object
568 * @param fieldtype Type of the field. ELM_DATETIME_YEAR etc
569 * @return bool @c EINA_TRUE, if field can be visible. @c EINA_FALSE otherwise.
571 * @see elm_datetime_field_visible_set()
574 EAPI Eina_Bool elm_datetime_field_visible_get(const Evas_Object *obj, Elm_Datetime_Field_Type fieldtype);
577 * @brief Set a field to be visible or not.
578 * Setting this API True does not ensure that the field is visible, apart from
579 * this, the field's format must be present in Datetime overall format.
580 * If a field's visibility is set to False then it won't appear even though
581 * its format is present in overall format.
582 * So if and only if this API is set true and the corresponding field's format
583 * is present in Datetime format, the field is visible.
585 * By default the field visibility is set to True.
587 * @param obj The datetime object
588 * @param fieldtype Type of the field. ELM_DATETIME_YEAR etc.
589 * @param visible @c EINA_TRUE field can be visible, @c EINA_FALSE otherwise.
591 * @see elm_datetime_field_visible_get()
594 EAPI void elm_datetime_field_visible_set(Evas_Object *obj, Elm_Datetime_Field_Type fieldtype, Eina_Bool visible);