Datetime

Widget description

Datetime widget is used to display and input date & time values.

This widget displays date and time as per the system’s locale settings (Date includes Day, Month & Year along with the defined separators and Time includes Hour, Minute & AM/PM fields). Separator for AM/PM field is ignored.

The corresponding Month, AM/PM strings are displayed according to the system’s language settings.

Datetime format is a combination of LIBC standard characters like “%%d %%b %%Y %%I : %%M %%p” which, as a whole represents both Date as well as Time format.

Elm_datetime supports only the following sub set of libc date format specifiers:

%%Y The year as a decimal number including the century (example: 2011).

%%y The year as a decimal number without a century (range 00 to 99)

%%m The month as a decimal number (range 01 to 12).

%%b The abbreviated month name according to the current locale.

%%B The full month name according to the current locale.

%%h The abbreviated month name according to the current locale(same as %%b).

%%d The day of the month as a decimal number (range 01 to 31).

%%e The day of the month as a decimal number (range 1 to 31). single

digits are preceded by a blank.

%%I The hour as a decimal number using a 12-hour clock (range 01 to 12).

%%H The hour as a decimal number using a 24-hour clock (range 00 to 23).

%%k The hour (24-hour clock) as a decimal number (range 0 to 23). single

digits are preceded by a blank.

%%l The hour (12-hour clock) as a decimal number (range 1 to 12); single

digits are preceded by a blank.

%%M The minute as a decimal number (range 00 to 59).

%%p Either ‘AM’ or ‘PM’ according to the given time value, or the

corresponding strings for the current locale. Noon is treated as ‘PM’ and midnight as ‘AM’

%%P Like %p but in lower case: ‘am’ or ‘pm’ or a corresponding string for

the current locale.

%%c The preferred date and time representation for the current locale.

%%x The preferred date representation for the current locale without the time.

%%X The preferred time representation for the current locale without the date.

%%r The complete calendar time using the AM/PM format of the current locale.

%%R The hour and minute in decimal numbers using the format %H:%M.

%%T The time of day in decimal numbers using the format %H:%M:%S.

%%D The date using the format %%m/%%d/%%y.

%%F The date using the format %%Y-%%m-%%d.

(For more reference on the available LIBC date format specifiers, please visit the link: http://www.gnu.org/s/hello/manual/libc.html#Formatting-Calendar-Time )

Datetime widget can provide Unicode separators in between its fields except for AM/PM field. A separator can be any Unicode character other than the LIBC standard date format specifiers.

Example: In the format:

%%b %%d **,** %%y %%H **:** %%M

comma(,) is separator for date field %%d and colon(:) is separator for hour field %%H.

The default format is a predefined one, based on the system Locale.

Hour format 12hr(1-12) or 24hr(0-23) display can be selected by setting the corresponding user format.

Datetime supports six fields: Year, Month, Date, Hour, Minute, AM/PM. Depending on the Datetime module that is loaded, the user can see different UI to select the individual field values.

The individual fields of Datetime can be arranged in any order according to the format set by application.

There is a provision to set the visibility of a particular field as TRUE/ FALSE so that only time/ only date / only required fields will be displayed.

Each field is having a default minimum and maximum values just like the daily calendar information. These min/max values can be modified as per the application usage.

User can enter the values only in between the range of maximum and minimum. Apart from these APIs, there is a provision to display only a limited set of values out of the possible values. APIs to select the individual field limits are intended for this purpose.

The whole widget is left aligned and its size grows horizontally depending on the current format and each field’s visible/disabled state.

Datetime individual field selection is implemented in a modular style. Module can be implemented as a Ctxpopup based selection or an ISE based selection or even a spinner like selection etc.

Datetime Module design

The following functions are expected to be implemented in a Datetime module:

Field creation:

 __________                                            __________
|          |----- obj_hook() ---------------------->>>|          |
|          |<<<----------------returns Mod_data ------|          |
| Datetime |_______                                   |          |
|  widget  |       |Assign module call backs          |  Module  |
|   base   |<<<____|                                  |          |
|          |                                          |          |
|          |----- field_create() ------------------>>>|          |
|__________|<<<----------------returns field_obj -----|__________|

Field value setting:

 __________                                          __________
|          |                                        |          |
| Datetime |<<<----------elm_datetime_value_set()---|          |
|  widget  |                                        |  Module  |
|   base   |----display_field_value()------------>>>|          |
|__________|                                        |__________|

del_hook:

 __________                                          __________
|          |                                        |          |
| Datetime |----obj_unhook()-------------------->>>>|          |
|  widget  |                                        |  Module  |
|   base   |         <<<-----frees mod_data---------|          |
|__________|                                        |__________|

Any module can use the following shared functions that are implemented in elm_datetime.c:

field_format_get() - gives the field format.

field_limit_get() - gives the field minimum, maximum limits.

To enable a module, set the ELM_MODULES environment variable as shown:

export ELM_MODULES=”datetime_input_ctxpopup>datetime/api”

Emitted signals

  • changed - whenever Datetime field value is changed, this signal is sent.

Enumerations

Datetime fields

efl.elementary.ELM_DATETIME_YEAR

Year

efl.elementary.ELM_DATETIME_MONTH

Month

efl.elementary.ELM_DATETIME_DATE

Date

efl.elementary.ELM_DATETIME_HOUR

Hour

efl.elementary.ELM_DATETIME_MINUTE

Minute

efl.elementary.ELM_DATETIME_AMPM

Am/Pm

Inheritance diagram

Inheritance diagram of Datetime
class efl.elementary.Datetime(Object parent, *args, **kwargs)

Bases: efl.elementary.__init__.Object

This is the class that actually implements the widget.

Parameters
  • parent (efl.evas.Object) – The parent object

  • **kwargs – All the remaining keyword arguments are interpreted as properties of the instance

callback_changed_add(func, *args, **kwargs)

Whenever Datetime field value is changed, this signal is sent.

callback_changed_del(func)
field_limit_get(fieldtype)

Get the field limits of a field.

Limits can be set to individual fields, independently, except for AM/PM field. Any field can display the values only in between these Minimum and Maximum limits unless the corresponding time value is restricted from MinTime to MaxTime. That is, Min/ Max field limits always works under the limitations of MinTime/ MaxTime.

There is no provision to set the limits of AM/PM field.

Parameters

fieldtype (Datetime fields) – Type of the field.

field_limit_set(fieldtype, min, max)

Set the field limits of a field.

Limits can be set to individual fields, independently, except for AM/PM field. Any field can display the values only in between these Minimum and Maximum limits unless the corresponding time value is restricted from MinTime to MaxTime. That is, Min/ Max field limits always works under the limitations of MinTime/ MaxTime.

There is no provision to set the limits of AM/PM field.

Parameters
  • fieldtype (Datetime fields) – Type of the field.

  • min (int) – Reference to field’s minimum value

  • max (int) – Reference to field’s maximum value

field_visible_get(fieldtype)

Whether a field can be visible/not

Parameters

fieldtype (Datetime fields) – Type of the field.

Returns

True, if field can be visible. False otherwise.

Return type

bool

field_visible_set(fieldtype, visible)

Set a field to be visible or not.

Setting this API True does not ensure that the field is visible, apart from this, the field’s format must be present in Datetime overall format. If a field’s visibility is set to False then it won’t appear even though its format is present in overall format. So if and only if this API is set true and the corresponding field’s format is present in Datetime format, the field is visible.

By default the field visibility is set to True.

Parameters
  • fieldtype (Datetime fields) – Type of the field.

  • visible (bool) – True field can be visible, False otherwise.

format

The datetime format. Format is a combination of allowed Libc date format specifiers like: “%b %d, %Y %I : %M %p”.

Maximum allowed format length is 64 chars.

Format can include separators for each individual datetime field except for AM/PM field.

Each separator can be a maximum of 6 UTF-8 bytes. Space is also taken as a separator.

Following are the allowed set of format specifiers for each datetime field.

%%Y The year as a decimal number including the century.

%%y The year as a decimal number without a century (range 00 to 99).

%%m The month as a decimal number (range 01 to 12).

%%b The abbreviated month name according to the current locale.

%%B The full month name according to the current locale.

%%h The abbreviated month name according to the current locale(same as %%b).

%%d The day of the month as a decimal number (range 01 to 31).

%%e The day of the month as a decimal number (range 1 to 31). single

digits are preceded by a blank.

%%I The hour as a decimal number using a 12-hour clock (range 01 to 12).

%%H The hour as a decimal number using a 24-hour clock (range 00 to 23).

%%k The hour (24-hour clock) as a decimal number (range 0 to 23). single

digits are preceded by a blank.

%%l The hour (12-hour clock) as a decimal number (range 1 to 12); single

digits are preceded by a blank.

%%M The minute as a decimal number (range 00 to 59).

%%p Either ‘AM’ or ‘PM’ according to the given time value, or the

corresponding strings for the current locale. Noon is treated as ‘PM’ and midnight as ‘AM’.

%%P Like %p but in lower case: ‘am’ or ‘pm’ or a corresponding string for

the current locale.

%%c The preferred date and time representation for the current locale.

%%x The preferred date representation for the current locale without the time.

%%X The preferred time representation for the current locale without the date.

%%r The complete calendar time using the AM/PM format of the current locale.

%%R The hour and minute in decimal numbers using the format %H:%M.

%%T The time of day in decimal numbers using the format %H:%M:%S.

%%D The date using the format %%m/%%d/%%y.

%%F The date using the format %%Y-%%m-%%d.

These specifiers can be arranged in any order and the widget will display the fields accordingly.

Default format is taken as per the system locale settings.

Type

string

value

The current value of a field.

Year: years since 1900. Negative value represents year below 1900 (year value -30 represents 1870). Year default range is from 70 to 137.

Month: default value range is from 0 to 11.

Date: default value range is from 1 to 31 according to the month value.

Hour: default value will be in terms of 24 hr format (0~23)

Minute: default value range is from 0 to 59.

Raises

RuntimeError – when the value could not be set.

Type

datetime.datetime

Changed in version 1.8: Returns None when the value cannot be fetched, raise RuntimeError when setting the value failed.

value_max

The upper boundary of a field.

Year: years since 1900. Negative value represents year below 1900 (year value -30 represents 1870). Year default range is from 70 to 137.

Month: default value range is from 0 to 11.

Date: default value range is from 1 to 31 according to the month value.

Hour: default value will be in terms of 24 hr format (0~23)

Minute: default value range is from 0 to 59.

Raises

RuntimeError – when the max value could not be set.

Type

datetime.datetime

Changed in version 1.8: Returns None when the max value cannot be fetched, raise RuntimeError when setting the max value failed.

value_min

The lower boundary of a field.

Year: years since 1900. Negative value represents year below 1900 (year value -30 represents 1870). Year default range is from 70 to 137.

Month: default value range is from 0 to 11.

Date: default value range is from 1 to 31 according to the month value.

Hour: default value will be in terms of 24 hr format (0~23)

Minute: default value range is from 0 to 59.

Raises

RuntimeError – when the min value could not be set.

Type

datetime.datetime

Changed in version 1.8: Returns None when the min value cannot be fetched, raise RuntimeError when setting the min value failed.