src/lib/elm_datetime.h

   1 /**
   2  * @defgroup Datetime Datetime
   3  * @ingroup Elementary
   4  *
   5  *
   6  * @image html img/widget/datetime/preview-00.png
   7  * @image latex img/widget/datetime/preview-00.eps
   8  *
   9  * @image html img/widget/datetime/preview-01.png
  10  * @image latex img/widget/datetime/preview-01.eps
  11  *
  12  * @image html img/widget/datetime/preview-02.png
  13  * @image latex img/widget/datetime/preview-02.eps
  14  *
  15  * Datetime widget is used to display and input date & time values.
  16  * This widget displays date and time as per the <b>system's locale</b> settings (Date
  17  * includes Day, Month & Year along with the defined separators and
  18  * Time includes Hour, Minute & AM/PM fields. Separator for AM/PM field is ignored.
  19  *
  20  * The corresponding Month, AM/PM strings are displayed according to the
  21  * system’s language settings.
  22  *
  23  * Datetime format is a combination of LIBC standard characters like
  24  * “%%d %%b %%Y %%I : %%M  %%p” which, as a whole represents both Date as well as Time
  25  * format.
  26  *
  27  * Elm_datetime supports only the following sub set of libc date format specifiers:
  28  *
  29  * @b %%Y : The year as a decimal number including the century (example: 2011).
  30  *
  31  * @b %%y : The year as a decimal number without a century (range 00 to 99)
  32  *
  33  * @b %%m : The month as a decimal number (range 01 to 12).
  34  *
  35  * @b %%b : The abbreviated month name according to the current locale.
  36  *
  37  * @b %%B : The full month name according to the current locale.
  38  *
  39  * @b %%h : The abbreviated month name according to the current locale(same as %%b).
  40  *
  41  * @b %%d : The day of the month as a decimal number (range 01 to 31).
  42  *
  43  * @b %%e : The day of the month as a decimal number (range 1 to 31). single
  44  * digits are preceded by a blank.
  45  *
  46  * @b %%I : The hour as a decimal number using a 12-hour clock (range 01 to 12).
  47  *
  48  * @b %%H : The hour as a decimal number using a 24-hour clock (range 00 to 23).
  49  *
  50  * @b %%k : The hour (24-hour clock) as a decimal number (range 0 to 23). single
  51  * digits are preceded by a blank.
  52  *
  53  * @b %%l : The hour (12-hour clock) as a decimal number (range 1 to 12); single
  54  * digits are preceded by a blank.
  55  *
  56  * @b %%M : The minute as a decimal number (range 00 to 59).
  57  *
  58  * @b %%p : Either 'AM' or 'PM' according to the given time value, or the
  59  * corresponding strings for the current locale. Noon is treated as 'PM'
  60  * and midnight as 'AM'
  61  *
  62  * @b %%P : Like %p but in lower case: 'am' or 'pm' or a corresponding string for
  63  * the current locale.
  64  *
  65  * @b %%c : The preferred date and time representation for the current locale.
  66  *
  67  * @b %%x : The preferred date representation for the current locale without the time.
  68  *
  69  * @b %%X : The preferred time representation for the current locale without the date.
  70  *
  71  * @b %%r : The complete calendar time using the AM/PM format of the current locale.
  72  *
  73  * @b %%R : The hour and minute in decimal numbers using the format %H:%M.
  74  *
  75  * @b %%T : The time of day in decimal numbers using the format %H:%M:%S.
  76  *
  77  * @b %%D : The date using the format %%m/%%d/%%y.
  78  *
  79  * @b %%F : The date using the format %%Y-%%m-%%d.
  80  *
  81  * (For more reference on the available <b>LIBC date format specifiers</b>, please
  82  * visit the link:
  83  * http://www.gnu.org/s/hello/manual/libc.html#Formatting-Calendar-Time )
  84  *
  85  * Datetime widget can provide Unicode @b separators in between its fields
  86  * except for AM/PM field.
  87  * A separator can be any <b>Unicode character</b> other than the LIBC standard
  88  * date format specifiers.( Example: In the format %%b %%d @b , %%y %%H @b : %%M
  89  * comma(,) is separator for date field %%d and colon(:) is separator for
  90  * hour field %%H ).
  91  *
  92  * The default format is a predefined one, based on the system Locale.
  93  *
  94  * Hour format 12hr(1-12) or 24hr(0-23) display can be selected by setting
  95  * the corresponding user format.
  96  *
  97  * Datetime supports six fields: Year, Month, Date, Hour, Minute, AM/PM.
  98  * Depending on the Datetime module that is loaded, the user can see
  99  * different UI to select the individual field values.
 100  *
 101  * The individual fields of Datetime can be arranged in any order according to the format
 102  * set by application.
 103  *
 104  * There is a provision to set the visibility of a particular field as TRUE/ FALSE
 105  * so that <b>only time/ only date / only required fields</b> will be displayed.
 106  *
 107  * Each field is having a default minimum and maximum values just like the daily
 108  * calendar information. These min/max values can be modified as per the application usage.
 109  *
 110  * User can enter the values only in between the range of maximum and minimum.
 111  * Apart from these APIs, there is a provision to display only a limited set of
 112  * values out of the possible values. APIs to select the individual field limits
 113  * are intended for this purpose.
 114  *
 115  * The whole widget is left aligned and its size grows horizontally depending
 116  * on the current format and each field's visible/disabled state.
 117  *
 118  * Datetime individual field selection is implemented in a modular style.
 119  * Module can be implemented as a Ctxpopup based selection or an ISE based
 120  * selection or even a spinner like selection etc.
 121  *
 122  * <b>Datetime Module design:</b>
 123  *
 124  * The following functions are expected to be implemented in a Datetime module:
 125  *
 126  * <b>Field creation:</b>
 127  * <pre>
 128  *
 129  *  __________                                            __________
 130  * |          |----- obj_hook() ---------------------->>>|          |
 131  * |          |<<<----------------returns Mod_data ------|          |
 132  * | Datetime |_______                                   |          |
 133  * |  widget  |       |Assign module call backs          |  Module  |
 134  * |   base   |<<<____|                                  |          |
 135  * |          |                                          |          |
 136  * |          |----- field_create() ------------------>>>|          |
 137  * |__________|<<<----------------returns field_obj -----|__________|
 138  *
 139  * </pre>
 140  *
 141  * <b>Field value setting:</b>
 142  * <pre>
 143  *
 144  *  __________                                          __________
 145  * |          |                                        |          |
 146  * | Datetime |<<<----------elm_datetime_value_set()---|          |
 147  * |  widget  |                                        |  Module  |
 148  * |   base   |----display_field_value()------------>>>|          |
 149  * |__________|                                        |__________|
 150  *
 151  * </pre>
 152  *
 153  * <b>del_hook:</b>
 154  * <pre>
 155  *  __________                                          __________
 156  * |          |                                        |          |
 157  * | Datetime |----obj_unhook()-------------------->>>>|          |
 158  * |  widget  |                                        |  Module  |
 159  * |   base   |         <<<-----frees mod_data---------|          |
 160  * |__________|                                        |__________|
 161  *
 162  * </pre>
 163  *
 164  *
 165  * Any module can use the following shared functions that are implemented in elm_datetime.c :
 166  *
 167  * <b>field_format_get()</b> - gives the field format.
 168  *
 169  * <b>field_limit_get()</b>  - gives the field minimum, maximum limits.
 170  *
 171  * To enable a module, set the ELM_MODULES environment variable as shown:
 172  *
 173  * <b>export ELM_MODULES="datetime_input_ctxpopup>datetime/api"</b>
 174  *
 175  *
 176  * Datetime widgets emits the following signals:
 177  *
 178  * @li @b "changed" - whenever Datetime field value is changed, this signal is sent.
 179  *
 180  * @li @b "language,changed" - whenever system locale changes, this signal is sent.
 181  *
 182  * Here is an example on its usage:
 183  * @li @ref datetime_example
 184  *
 185  */
 186
 187 /**
 188  * @addtogroup Datetime
 189  * @{
 190  */
 191
 192 /**
 193  * Identifies a Datetime field, The widget supports 6 fields : Year, month,
 194  * Date, Hour, Minute, AM/PM
 195  *
 196  */
 197 typedef enum _Elm_Datetime_Field_Type
 198 {
 199    ELM_DATETIME_YEAR    = 0, /**< Indicates Year field */
 200    ELM_DATETIME_MONTH   = 1, /**< Indicates Month field */
 201    ELM_DATETIME_DATE    = 2, /**< Indicates Date field */
 202    ELM_DATETIME_HOUR    = 3, /**< Indicates Hour field */
 203    ELM_DATETIME_MINUTE  = 4, /**< Indicates Minute field */
 204    ELM_DATETIME_AMPM    = 5, /**< Indicates AM/PM field */
 205 } Elm_Datetime_Field_Type;
 206
 207 /**
 208  * @brief Adds a new datetime Widget
 209  *
 210  * The default datetime format and corresponding strings are based on current locale.
 211  *
 212  * @param parent The parent object
 213  * @return The new object or NULL if it cannot be created
 214  *
 215  * This function inserts a new datetime widget on the canvas.
 216  *
 217  * @ingroup Datetime
 218  */
 219 EAPI Evas_Object *elm_datetime_add(Evas_Object *parent);
 220
 221 /**
 222  * Get the datetime format. Format is a combination of allowed Libc date format
 223  * specifiers like: "%b %d, %Y %I : %M %p".
 224  *
 225  * Maximum allowed format length is 64 chars.
 226  *
 227  * Format can include separators for each individual datetime field except
 228  * for AM/PM field.
 229  *
 230  * Each separator can be a maximum of 6 UTF-8 bytes.
 231  * Space is also taken as a separator.
 232  *
 233  * Following are the allowed set of format specifiers for each datetime field.
 234  *
 235  * @b %%Y : The year as a decimal number including the century.
 236  *
 237  * @b %%y : The year as a decimal number without a century (range 00 to 99).
 238  *
 239  * @b %%m : The month as a decimal number (range 01 to 12).
 240  *
 241  * @b %%b : The abbreviated month name according to the current locale.
 242  *
 243  * @b %%B : The full month name according to the current locale.
 244  *
 245  * @b %%h : The abbreviated month name according to the current locale(same as %%b).
 246  *
 247  * @b %%d : The day of the month as a decimal number (range 01 to 31).
 248  *
 249  * @b %%e : The day of the month as a decimal number (range 1 to 31). single
 250  *      digits are preceded by a blank.
 251  *
 252  * @b %%I : The hour as a decimal number using a 12-hour clock (range 01 to 12).
 253  *
 254  * @b %%H : The hour as a decimal number using a 24-hour clock (range 00 to 23).
 255  *
 256  * @b %%k : The hour (24-hour clock) as a decimal number (range 0 to 23). single
 257  *      digits are preceded by a blank.
 258  *
 259  * @b %%l : The hour (12-hour clock) as a decimal number (range 1 to 12); single
 260  *      digits are preceded by a blank.
 261  *
 262  * @b %%M : The minute as a decimal number (range 00 to 59).
 263  *
 264  * @b %%p : Either 'AM' or 'PM' according to the given time value, or the
 265  *      corresponding strings for the current locale. Noon is treated as 'PM'
 266  *      and midnight as 'AM'.
 267  *
 268  * @b %%P : Like %p but in lower case: 'am' or 'pm' or a corresponding string for
 269  *      the current locale.
 270  *
 271  * @b %%c : The preferred date and time representation for the current locale.
 272  *
 273  * @b %%x : The preferred date representation for the current locale without the time.
 274  *
 275  * @b %%X : The preferred time representation for the current locale without the date.
 276  *
 277  * @b %%r : The complete calendar time using the AM/PM format of the current locale.
 278  *
 279  * @b %%R : The hour and minute in decimal numbers using the format %H:%M.
 280  *
 281  * @b %%T : The time of day in decimal numbers using the format %H:%M:%S.
 282  *
 283  * @b %%D : The date using the format %%m/%%d/%%y.
 284  *
 285  * @b %%F : The date using the format %%Y-%%m-%%d.
 286  *
 287  * These specifiers can be arranged in any order and the widget will display the
 288  * fields accordingly.
 289  *
 290  * Default format is taken as per the system locale settings.
 291  *
 292  * @param obj The datetime object
 293  * @return The datetime format string. Example: "%b %d, %Y %I : %M %p"
 294  *
 295  * @see elm_datetime_format_set()
 296  * @ingroup Datetime
 297  */
 298    EAPI const char *elm_datetime_format_get(const Evas_Object *obj);
 299
 300 /**
 301  * Set the datetime format. Format is a combination of allowed Libc date format
 302  * specifiers like: "%b %d, %Y %I : %M %p".
 303  *
 304  * Maximum allowed format length is 64 chars.
 305  *
 306  * Format can include separators for each individual datetime field except
 307  * for AM/PM field.
 308  *
 309  * Each separator can be a maximum of 6 UTF-8 bytes.
 310  * Space is also taken as a separator.
 311  *
 312  * Following are the allowed set of format specifiers for each datetime field.
 313  *
 314  * @b %%Y : The year as a decimal number including the century.
 315  *
 316  * @b %%y : The year as a decimal number without a century (range 00 to 99).
 317  *
 318  * @b %%m : The month as a decimal number (range 01 to 12).
 319  *
 320  * @b %%b : The abbreviated month name according to the current locale.
 321  *
 322  * @b %%B : The full month name according to the current locale.
 323  *
 324  * @b %%h : The abbreviated month name according to the current locale(same as %%b).
 325  *
 326  * @b %%d : The day of the month as a decimal number (range 01 to 31).
 327  *
 328  * @b %%e : The day of the month as a decimal number (range 1 to 31). single
 329  *      digits are preceded by a blank.
 330  *
 331  * @b %%I : The hour as a decimal number using a 12-hour clock (range 01 to 12).
 332  *
 333  * @b %%H : The hour as a decimal number using a 24-hour clock (range 00 to 23).
 334  *
 335  * @b %%k : The hour (24-hour clock) as a decimal number (range 0 to 23). single
 336  *      digits are preceded by a blank.
 337  *
 338  * @b %%l : The hour (12-hour clock) as a decimal number (range 1 to 12); single
 339  *      digits are preceded by a blank.
 340  *
 341  * @b %%M : The minute as a decimal number (range 00 to 59).
 342  *
 343  * @b %%p : Either 'AM' or 'PM' according to the given time value, or the
 344  *      corresponding strings for the current locale. Noon is treated as 'PM'
 345  *      and midnight as 'AM'.
 346  *
 347  * @b %%P : Like %p but in lower case: 'am' or 'pm' or a corresponding string for
 348  *      the current locale.
 349  *
 350  * @b %%c : The preferred date and time representation for the current locale.
 351  *
 352  * @b %%x : The preferred date representation for the current locale without the time.
 353  *
 354  * @b %%X : The preferred time representation for the current locale without the date.
 355  *
 356  * @b %%r : The complete calendar time using the AM/PM format of the current locale.
 357  *
 358  * @b %%R : The hour and minute in decimal numbers using the format %H:%M.
 359  *
 360  * @b %%T : The time of day in decimal numbers using the format %H:%M:%S.
 361  *
 362  * @b %%D : The date using the format %%m/%%d/%%y.
 363  *
 364  * @b %%F : The date using the format %%Y-%%m-%%d.
 365  *
 366  * These specifiers can be arranged in any order and the widget will display the
 367  * fields accordingly.
 368  *
 369  * Default format is taken as per the system locale settings.
 370  *
 371  * @param obj The datetime object
 372  * @param fmt The datetime format
 373  *
 374  * @see elm_datetime_format_get()
 375  * @ingroup Datetime
 376  */
 377 EAPI void elm_datetime_format_set(Evas_Object *obj, const char *fmt);
 378
 379 /**
 380   * @brief Get the upper boundary of a field.
 381   *
 382   * Year: years since 1900. Negative value represents year below 1900 (year
 383   * value -30 represents 1870). Year default range is from 70 to 137.
 384   *
 385   * Month: default value range is from 0 to 11.
 386   *
 387   * Date: default value range is from 1 to 31 according to the month value.
 388   *
 389   * Hour: default value will be in terms of 24 hr format (0~23)
 390   *
 391   * Minute: default value range is from 0 to 59.
 392   *
 393   * @param obj The datetime object
 394   * @param maxtime Time structure containing the maximum time value.
 395   * @return int The maximum value of the field.
 396   *
 397   * @see elm_datetime_value_max_set()
 398   * @ingroup Datetime
 399  */
 400 EAPI Eina_Bool elm_datetime_value_max_get(const Evas_Object *obj, struct tm *maxtime);
 401
 402 /**
 403  * @brief Set the upper boundary of a field.
 404  *
 405  * Year: years since 1900. Negative value represents year below 1900 (year
 406  * value -30 represents 1870). Year default range is from 70 to 137.
 407  *
 408  * Month: default value range is from 0 to 11.
 409  *
 410  * Date: default value range is from 1 to 31 according to the month value.
 411  *
 412  * Hour: default value will be in terms of 24 hr format (0~23)
 413  *
 414  * Minute: default value range is from 0 to 59.
 415  *
 416  * @param obj The datetime object
 417  * @param maxtime Time structure containing the maximum time value.
 418  * @return EINA_TRUE if maximum value is accepted.
 419  *
 420  * @see elm_datetime_value_max_get()
 421  * @ingroup Datetime
 422  */
 423 EAPI Eina_Bool elm_datetime_value_max_set(Evas_Object *obj, const struct tm *maxtime);
 424
 425 /**
 426  * @brief Get the lower boundary of a field.
 427  *
 428  * Year: years since 1900. Negative value represents year below 1900 (year
 429  * value -30 represents 1870). Year default range is from 70 to 137.
 430  *
 431  * Month: default value range is from 0 to 11.
 432  *
 433  * Date: default value range is from 1 to 31 according to the month value.
 434  *
 435  * Hour: default value will be in terms of 24 hr format (0~23)
 436  *
 437  * Minute: default value range is from 0 to 59.
 438  *
 439  * @param obj The datetime object
 440  * @param mintime Time structure.
 441  * @return EINA_TRUE if minimum value is successfully returned.
 442  *
 443  * @see elm_datetime_value_min_set()
 444  * @ingroup Datepicker
 445  */
 446 EAPI Eina_Bool elm_datetime_value_min_get(const Evas_Object *obj, struct tm *mintime);
 447
 448 /**
 449  * @brief Set the lower boundary of a field.
 450  *
 451  * Year: years since 1900. Negative value represents year below 1900 (year
 452  * value -30 represents 1870). Year default range is from 70 to 137.
 453  *
 454  * Month: default value range is from 0 to 11.
 455  *
 456  * Date: default value range is from 1 to 31 according to the month value.
 457  *
 458  * Hour: default value will be in terms of 24 hr format (0~23)
 459  *
 460  * Minute: default value range is from 0 to 59.
 461  *
 462  * @param obj The datetime object.
 463  * @param mintime Time structure containing the minimum time value.
 464  * @return EINA_TRUE if minimum value is accepted.
 465  *
 466  * @see elm_datetime_value_min_get()
 467  * @ingroup Datetime
 468  */
 469 EAPI Eina_Bool elm_datetime_value_min_set(Evas_Object *obj, const struct tm *mintime);
 470
 471 /**
 472  * @brief Get the field limits of a field.
 473  *
 474  * Limits can be set to individual fields, independently, except for AM/PM field.
 475  * Any field can display the values only in between these Minimum and Maximum limits unless
 476  * the corresponding time value is restricted from MinTime to MaxTime.
 477  * That is, Min/ Max field limits always works under the limitations of MinTime/ MaxTime.
 478  *
 479  * There is no provision to set the limits of AM/PM field.
 480  *
 481  * @param obj The datetime object
 482  * @param fieldtype Type of the field. ELM_DATETIME_YEAR etc.
 483  * @param min Reference to field's minimum value
 484  * @param max Reference to field's maximum value
 485  *
 486  * @see elm_datetime_field_limit_set()
 487  * @ingroup Datetime
 488  */
 489 EAPI void      elm_datetime_field_limit_get(const Evas_Object *obj, Elm_Datetime_Field_Type fieldtype, int *min, int *max);
 490
 491 /**
 492  * @brief Set the field limits of a field.
 493  *
 494  * Limits can be set to individual fields, independently, except for AM/PM field.
 495  * Any field can display the values only in between these Minimum and Maximum limits unless
 496  * the corresponding time value is restricted from MinTime to MaxTime.
 497  * That is, Min/ Max field limits always works under the limitations of MinTime/ MaxTime.
 498  *
 499  * There is no provision to set the limits of AM/PM field.
 500  *
 501  * @param obj The datetime object
 502  * @param fieldtype Type of the field. ELM_DATETIME_YEAR etc.
 503  * @param min Reference to field's minimum value
 504  * @param max Reference to field's maximum value
 505  *
 506  * @see elm_datetime_field_limit_set()
 507  * @ingroup Datetime
 508  */
 509 EAPI void      elm_datetime_field_limit_set(Evas_Object *obj, Elm_Datetime_Field_Type fieldtype, int min, int max);
 510
 511 /**
 512  * @brief Get the current value of a field.
 513  *
 514  * Year: years since 1900. Negative value represents year below 1900 (year
 515  * value -30 represents 1870). Year default range is from 70 to 137.
 516  *
 517  * Month: default value range is from 0 to 11.
 518  *
 519  * Date: default value range is from 1 to 31 according to the month value.
 520  *
 521  * Hour: default value will be in terms of 24 hr format (0~23)
 522  *
 523  * Minute: default value range is from 0 to 59.
 524  *
 525  * @param obj The datetime object.
 526  * @param currtime Time structure.
 527  * @return EINA_TRUE if current time is returned successfully.
 528  *
 529  * @see elm_datetime_field_value_set()
 530  * @ingroup Datetime
 531  */
 532 EAPI Eina_Bool elm_datetime_value_get(const Evas_Object *obj, struct tm *currtime);
 533
 534 /**
 535  * @brief Set the current value of a Datetime object.
 536  *
 537  * Year: years since 1900. Negative value represents year below 1900 (year
 538  * value -30 represents 1870). Year default range is from 70 to 137.
 539  *
 540  * Month: default value range is from 0 to 11.
 541  *
 542  * Date: default value range is from 1 to 31 according to the month value.
 543  *
 544  * Hour: default value will be in terms of 24 hr format (0~23)
 545  *
 546  * Minute: default value range is from 0 to 59.
 547  *
 548  *
 549  * @param obj The datetime object.
 550  * @param newtime Time structure filled with values to be set.
 551  * @return EINA_TRUE if current time is set successfully.
 552  *
 553  * @see elm_datetime_value_set()
 554  * @ingroup Datetime
 555  */
 556 EAPI Eina_Bool elm_datetime_value_set(Evas_Object *obj, const struct tm *newtime);
 557
 558 /**
 559  * @brief Get whether a field can be visible/not
 560  *
 561  * @param obj The datetime object
 562  * @param fieldtype Type of the field. ELM_DATETIME_YEAR etc
 563  * @return bool @c EINA_TRUE, if field can be visible. @c EINA_FALSE otherwise.
 564  *
 565  * @see elm_datetime_field_visible_set()
 566  * @ingroup Datetime
 567  */
 568 EAPI Eina_Bool elm_datetime_field_visible_get(const Evas_Object *obj, Elm_Datetime_Field_Type fieldtype);
 569
 570 /**
 571  * @brief Set a field to be visible or not.
 572  * Setting this API True does not ensure that the field is visible, apart from
 573  * this, the field's format must be present in Datetime overall format.
 574  * If a field's visibility is set to False then it won't appear even though
 575  * its format is present in overall format.
 576  * So if and only if this API is set true and the corresponding field's format
 577  * is present in Datetime format, the field is visible.
 578  *
 579  * By default the field visibility is set to True.
 580  *
 581  * @param obj The datetime object
 582  * @param fieldtype Type of the field. ELM_DATETIME_YEAR etc.
 583  * @param visible @c EINA_TRUE field can be visible, @c EINA_FALSE otherwise.
 584  *
 585  * @see elm_datetime_field_visible_get()
 586  * @ingroup Datetime
 587  */
 588 EAPI void elm_datetime_field_visible_set(Evas_Object *obj, Elm_Datetime_Field_Type fieldtype, Eina_Bool visible);
 589
 590 /**
 591  * @}
 592  */