src/lib/elm_datetime.h

   1 /**
   2  * @defgroup Datetime Datetime
   3  * @ingroup Elementary
   4  *
   5  * @image html datetime_inheritance_tree.png
   6  * @image latex datetime_inheritance_tree.eps
   7  *
   8  * @image html img/widget/datetime/preview-00.png
   9  * @image latex img/widget/datetime/preview-00.eps
  10  *
  11  * @image html img/widget/datetime/preview-01.png
  12  * @image latex img/widget/datetime/preview-01.eps
  13  *
  14  * @image html img/widget/datetime/preview-02.png
  15  * @image latex img/widget/datetime/preview-02.eps
  16  *
  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.
  21  *
  22  * The corresponding Month, AM/PM strings are displayed according to the
  23  * system’s language settings.
  24  *
  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
  27  * format.
  28  *
  29  * Elm_datetime supports only the following sub set of libc date format specifiers:
  30  *
  31  * @b %%Y : The year as a decimal number including the century (example: 2011).
  32  *
  33  * @b %%y : The year as a decimal number without a century (range 00 to 99)
  34  *
  35  * @b %%m : The month as a decimal number (range 01 to 12).
  36  *
  37  * @b %%b : The abbreviated month name according to the current locale.
  38  *
  39  * @b %%B : The full month name according to the current locale.
  40  *
  41  * @b %%h : The abbreviated month name according to the current locale(same as %%b).
  42  *
  43  * @b %%d : The day of the month as a decimal number (range 01 to 31).
  44  *
  45  * @b %%e : The day of the month as a decimal number (range 1 to 31). single
  46  * digits are preceded by a blank.
  47  *
  48  * @b %%I : The hour as a decimal number using a 12-hour clock (range 01 to 12).
  49  *
  50  * @b %%H : The hour as a decimal number using a 24-hour clock (range 00 to 23).
  51  *
  52  * @b %%k : The hour (24-hour clock) as a decimal number (range 0 to 23). single
  53  * digits are preceded by a blank.
  54  *
  55  * @b %%l : The hour (12-hour clock) as a decimal number (range 1 to 12); single
  56  * digits are preceded by a blank.
  57  *
  58  * @b %%M : The minute as a decimal number (range 00 to 59).
  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'
  63  *
  64  * @b %%P : Like %p but in lower case: 'am' or 'pm' or a corresponding string for
  65  * the current locale.
  66  *
  67  * @b %%c : The preferred date and time representation for the current locale.
  68  *
  69  * @b %%x : The preferred date representation for the current locale without the time.
  70  *
  71  * @b %%X : The preferred time representation for the current locale without the date.
  72  *
  73  * @b %%r : The complete calendar time using the AM/PM format of the current locale.
  74  *
  75  * @b %%R : The hour and minute in decimal numbers using the format %H:%M.
  76  *
  77  * @b %%T : The time of day in decimal numbers using the format %H:%M:%S.
  78  *
  79  * @b %%D : The date using the format %%m/%%d/%%y.
  80  *
  81  * @b %%F : The date using the format %%Y-%%m-%%d.
  82  *
  83  * (For more reference on the available <b>LIBC date format specifiers</b>, please
  84  * visit the link:
  85  * http://www.gnu.org/s/hello/manual/libc.html#Formatting-Calendar-Time )
  86  *
  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
  92  * hour field %%H ).
  93  *
  94  * The default format is a predefined one, based on the system Locale.
  95  *
  96  * Hour format 12hr(1-12) or 24hr(0-23) display can be selected by setting
  97  * the corresponding user format.
  98  *
  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.
 102  *
 103  * The individual fields of Datetime can be arranged in any order according to the format
 104  * set by application.
 105  *
 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.
 108  *
 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.
 111  *
 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.
 116  *
 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.
 119  *
 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.
 123  *
 124  * <b>Datetime Module design:</b>
 125  *
 126  * The following functions are expected to be implemented in a Datetime module:
 127  *
 128  * <b>Field creation:</b>
 129  * <pre>
 130  *
 131  *  __________                                            __________
 132  * |          |----- obj_hook() ---------------------->>>|          |
 133  * |          |<<<----------------returns Mod_data ------|          |
 134  * | Datetime |_______                                   |          |
 135  * |  widget  |       |Assign module call backs          |  Module  |
 136  * |   base   |<<<____|                                  |          |
 137  * |          |                                          |          |
 138  * |          |----- field_create() ------------------>>>|          |
 139  * |__________|<<<----------------returns field_obj -----|__________|
 140  *
 141  * </pre>
 142  *
 143  * <b>Field value setting:</b>
 144  * <pre>
 145  *
 146  *  __________                                          __________
 147  * |          |                                        |          |
 148  * | Datetime |<<<----------elm_datetime_value_set()---|          |
 149  * |  widget  |                                        |  Module  |
 150  * |   base   |----display_field_value()------------>>>|          |
 151  * |__________|                                        |__________|
 152  *
 153  * </pre>
 154  *
 155  * <b>del_hook:</b>
 156  * <pre>
 157  *  __________                                          __________
 158  * |          |                                        |          |
 159  * | Datetime |----obj_unhook()-------------------->>>>|          |
 160  * |  widget  |                                        |  Module  |
 161  * |   base   |         <<<-----frees mod_data---------|          |
 162  * |__________|                                        |__________|
 163  *
 164  * </pre>
 165  *
 166  *
 167  * Any module can use the following shared functions that are implemented in elm_datetime.c :
 168  *
 169  * <b>field_format_get()</b> - gives the field format.
 170  *
 171  * <b>field_limit_get()</b>  - gives the field minimum, maximum limits.
 172  *
 173  * To enable a module, set the ELM_MODULES environment variable as shown:
 174  *
 175  * <b>export ELM_MODULES="datetime_input_ctxpopup>datetime/api"</b>
 176  *
 177  * This widget inherits from the @ref Layout one, so that all the
 178  * functions acting on it also work for datetime objects.
 179  *
 180  * This widget emits the following signals, besides the ones sent from
 181  * @ref Layout:
 182  * @li @b "changed" - whenever Datetime field value is changed, this
 183  * signal is sent.
 184  *
 185  * @li @b "language,changed" - whenever system locale changes, this
 186  * signal is sent.
 187  *
 188  * Here is an example on its usage:
 189  * @li @ref datetime_example
 190  *
 191  */
 192
 193 /**
 194  * @addtogroup Datetime
 195  * @{
 196  */
 197
 198 /**
 199  * Identifies a Datetime field, The widget supports 6 fields : Year, month,
 200  * Date, Hour, Minute, AM/PM
 201  *
 202  */
 203 typedef enum _Elm_Datetime_Field_Type
 204 {
 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;
 212
 213 /**
 214  * @brief Adds a new datetime Widget
 215  *
 216  * The default datetime format and corresponding strings are based on current locale.
 217  *
 218  * @param parent The parent object
 219  * @return The new object or NULL if it cannot be created
 220  *
 221  * This function inserts a new datetime widget on the canvas.
 222  *
 223  * @ingroup Datetime
 224  */
 225 EAPI Evas_Object *elm_datetime_add(Evas_Object *parent);
 226
 227 /**
 228  * Get the datetime format. Format is a combination of allowed Libc date format
 229  * specifiers like: "%b %d, %Y %I : %M %p".
 230  *
 231  * Maximum allowed format length is 64 chars.
 232  *
 233  * Format can include separators for each individual datetime field except
 234  * for AM/PM field.
 235  *
 236  * Each separator can be a maximum of 6 UTF-8 bytes.
 237  * Space is also taken as a separator.
 238  *
 239  * Following are the allowed set of format specifiers for each datetime field.
 240  *
 241  * @b %%Y : The year as a decimal number including the century.
 242  *
 243  * @b %%y : The year as a decimal number without a century (range 00 to 99).
 244  *
 245  * @b %%m : The month as a decimal number (range 01 to 12).
 246  *
 247  * @b %%b : The abbreviated month name according to the current locale.
 248  *
 249  * @b %%B : The full month name according to the current locale.
 250  *
 251  * @b %%h : The abbreviated month name according to the current locale(same as %%b).
 252  *
 253  * @b %%d : The day of the month as a decimal number (range 01 to 31).
 254  *
 255  * @b %%e : The day of the month as a decimal number (range 1 to 31). single
 256  *      digits are preceded by a blank.
 257  *
 258  * @b %%I : The hour as a decimal number using a 12-hour clock (range 01 to 12).
 259  *
 260  * @b %%H : The hour as a decimal number using a 24-hour clock (range 00 to 23).
 261  *
 262  * @b %%k : The hour (24-hour clock) as a decimal number (range 0 to 23). single
 263  *      digits are preceded by a blank.
 264  *
 265  * @b %%l : The hour (12-hour clock) as a decimal number (range 1 to 12); single
 266  *      digits are preceded by a blank.
 267  *
 268  * @b %%M : The minute as a decimal number (range 00 to 59).
 269  *
 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'.
 273  *
 274  * @b %%P : Like %p but in lower case: 'am' or 'pm' or a corresponding string for
 275  *      the current locale.
 276  *
 277  * @b %%c : The preferred date and time representation for the current locale.
 278  *
 279  * @b %%x : The preferred date representation for the current locale without the time.
 280  *
 281  * @b %%X : The preferred time representation for the current locale without the date.
 282  *
 283  * @b %%r : The complete calendar time using the AM/PM format of the current locale.
 284  *
 285  * @b %%R : The hour and minute in decimal numbers using the format %H:%M.
 286  *
 287  * @b %%T : The time of day in decimal numbers using the format %H:%M:%S.
 288  *
 289  * @b %%D : The date using the format %%m/%%d/%%y.
 290  *
 291  * @b %%F : The date using the format %%Y-%%m-%%d.
 292  *
 293  * These specifiers can be arranged in any order and the widget will display the
 294  * fields accordingly.
 295  *
 296  * Default format is taken as per the system locale settings.
 297  *
 298  * @param obj The datetime object
 299  * @return The datetime format string. Example: "%b %d, %Y %I : %M %p"
 300  *
 301  * @see elm_datetime_format_set()
 302  * @ingroup Datetime
 303  */
 304    EAPI const char *elm_datetime_format_get(const Evas_Object *obj);
 305
 306 /**
 307  * Set the datetime format. Format is a combination of allowed Libc date format
 308  * specifiers like: "%b %d, %Y %I : %M %p".
 309  *
 310  * Maximum allowed format length is 64 chars.
 311  *
 312  * Format can include separators for each individual datetime field except
 313  * for AM/PM field.
 314  *
 315  * Each separator can be a maximum of 6 UTF-8 bytes.
 316  * Space is also taken as a separator.
 317  *
 318  * Following are the allowed set of format specifiers for each datetime field.
 319  *
 320  * @b %%Y : The year as a decimal number including the century.
 321  *
 322  * @b %%y : The year as a decimal number without a century (range 00 to 99).
 323  *
 324  * @b %%m : The month as a decimal number (range 01 to 12).
 325  *
 326  * @b %%b : The abbreviated month name according to the current locale.
 327  *
 328  * @b %%B : The full month name according to the current locale.
 329  *
 330  * @b %%h : The abbreviated month name according to the current locale(same as %%b).
 331  *
 332  * @b %%d : The day of the month as a decimal number (range 01 to 31).
 333  *
 334  * @b %%e : The day of the month as a decimal number (range 1 to 31). single
 335  *      digits are preceded by a blank.
 336  *
 337  * @b %%I : The hour as a decimal number using a 12-hour clock (range 01 to 12).
 338  *
 339  * @b %%H : The hour as a decimal number using a 24-hour clock (range 00 to 23).
 340  *
 341  * @b %%k : The hour (24-hour clock) as a decimal number (range 0 to 23). single
 342  *      digits are preceded by a blank.
 343  *
 344  * @b %%l : The hour (12-hour clock) as a decimal number (range 1 to 12); single
 345  *      digits are preceded by a blank.
 346  *
 347  * @b %%M : The minute as a decimal number (range 00 to 59).
 348  *
 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'.
 352  *
 353  * @b %%P : Like %p but in lower case: 'am' or 'pm' or a corresponding string for
 354  *      the current locale.
 355  *
 356  * @b %%c : The preferred date and time representation for the current locale.
 357  *
 358  * @b %%x : The preferred date representation for the current locale without the time.
 359  *
 360  * @b %%X : The preferred time representation for the current locale without the date.
 361  *
 362  * @b %%r : The complete calendar time using the AM/PM format of the current locale.
 363  *
 364  * @b %%R : The hour and minute in decimal numbers using the format %H:%M.
 365  *
 366  * @b %%T : The time of day in decimal numbers using the format %H:%M:%S.
 367  *
 368  * @b %%D : The date using the format %%m/%%d/%%y.
 369  *
 370  * @b %%F : The date using the format %%Y-%%m-%%d.
 371  *
 372  * These specifiers can be arranged in any order and the widget will display the
 373  * fields accordingly.
 374  *
 375  * Default format is taken as per the system locale settings.
 376  *
 377  * @param obj The datetime object
 378  * @param fmt The datetime format
 379  *
 380  * @see elm_datetime_format_get()
 381  * @ingroup Datetime
 382  */
 383 EAPI void elm_datetime_format_set(Evas_Object *obj, const char *fmt);
 384
 385 /**
 386   * @brief Get the upper boundary of a field.
 387   *
 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.
 390   *
 391   * Month: default value range is from 0 to 11.
 392   *
 393   * Date: default value range is from 1 to 31 according to the month value.
 394   *
 395   * Hour: default value will be in terms of 24 hr format (0~23)
 396   *
 397   * Minute: default value range is from 0 to 59.
 398   *
 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.
 402   *
 403   * @see elm_datetime_value_max_set()
 404   * @ingroup Datetime
 405  */
 406 EAPI Eina_Bool elm_datetime_value_max_get(const Evas_Object *obj, struct tm *maxtime);
 407
 408 /**
 409  * @brief Set the upper boundary of a field.
 410  *
 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.
 413  *
 414  * Month: default value range is from 0 to 11.
 415  *
 416  * Date: default value range is from 1 to 31 according to the month value.
 417  *
 418  * Hour: default value will be in terms of 24 hr format (0~23)
 419  *
 420  * Minute: default value range is from 0 to 59.
 421  *
 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.
 425  *
 426  * @see elm_datetime_value_max_get()
 427  * @ingroup Datetime
 428  */
 429 EAPI Eina_Bool elm_datetime_value_max_set(Evas_Object *obj, const struct tm *maxtime);
 430
 431 /**
 432  * @brief Get the lower boundary of a field.
 433  *
 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.
 436  *
 437  * Month: default value range is from 0 to 11.
 438  *
 439  * Date: default value range is from 1 to 31 according to the month value.
 440  *
 441  * Hour: default value will be in terms of 24 hr format (0~23)
 442  *
 443  * Minute: default value range is from 0 to 59.
 444  *
 445  * @param obj The datetime object
 446  * @param mintime Time structure.
 447  * @return EINA_TRUE if minimum value is successfully returned.
 448  *
 449  * @see elm_datetime_value_min_set()
 450  * @ingroup Datepicker
 451  */
 452 EAPI Eina_Bool elm_datetime_value_min_get(const Evas_Object *obj, struct tm *mintime);
 453
 454 /**
 455  * @brief Set the lower boundary of a field.
 456  *
 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.
 459  *
 460  * Month: default value range is from 0 to 11.
 461  *
 462  * Date: default value range is from 1 to 31 according to the month value.
 463  *
 464  * Hour: default value will be in terms of 24 hr format (0~23)
 465  *
 466  * Minute: default value range is from 0 to 59.
 467  *
 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.
 471  *
 472  * @see elm_datetime_value_min_get()
 473  * @ingroup Datetime
 474  */
 475 EAPI Eina_Bool elm_datetime_value_min_set(Evas_Object *obj, const struct tm *mintime);
 476
 477 /**
 478  * @brief Get the field limits of a field.
 479  *
 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.
 484  *
 485  * There is no provision to set the limits of AM/PM field.
 486  *
 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
 491  *
 492  * @see elm_datetime_field_limit_set()
 493  * @ingroup Datetime
 494  */
 495 EAPI void      elm_datetime_field_limit_get(const Evas_Object *obj, Elm_Datetime_Field_Type fieldtype, int *min, int *max);
 496
 497 /**
 498  * @brief Set the field limits of a field.
 499  *
 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.
 504  *
 505  * There is no provision to set the limits of AM/PM field.
 506  *
 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
 511  *
 512  * @see elm_datetime_field_limit_set()
 513  * @ingroup Datetime
 514  */
 515 EAPI void      elm_datetime_field_limit_set(Evas_Object *obj, Elm_Datetime_Field_Type fieldtype, int min, int max);
 516
 517 /**
 518  * @brief Get the current value of a field.
 519  *
 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.
 522  *
 523  * Month: default value range is from 0 to 11.
 524  *
 525  * Date: default value range is from 1 to 31 according to the month value.
 526  *
 527  * Hour: default value will be in terms of 24 hr format (0~23)
 528  *
 529  * Minute: default value range is from 0 to 59.
 530  *
 531  * @param obj The datetime object.
 532  * @param currtime Time structure.
 533  * @return EINA_TRUE if current time is returned successfully.
 534  *
 535  * @see elm_datetime_field_value_set()
 536  * @ingroup Datetime
 537  */
 538 EAPI Eina_Bool elm_datetime_value_get(const Evas_Object *obj, struct tm *currtime);
 539
 540 /**
 541  * @brief Set the current value of a Datetime object.
 542  *
 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.
 545  *
 546  * Month: default value range is from 0 to 11.
 547  *
 548  * Date: default value range is from 1 to 31 according to the month value.
 549  *
 550  * Hour: default value will be in terms of 24 hr format (0~23)
 551  *
 552  * Minute: default value range is from 0 to 59.
 553  *
 554  *
 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.
 558  *
 559  * @see elm_datetime_value_set()
 560  * @ingroup Datetime
 561  */
 562 EAPI Eina_Bool elm_datetime_value_set(Evas_Object *obj, const struct tm *newtime);
 563
 564 /**
 565  * @brief Get whether a field can be visible/not
 566  *
 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.
 570  *
 571  * @see elm_datetime_field_visible_set()
 572  * @ingroup Datetime
 573  */
 574 EAPI Eina_Bool elm_datetime_field_visible_get(const Evas_Object *obj, Elm_Datetime_Field_Type fieldtype);
 575
 576 /**
 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.
 584  *
 585  * By default the field visibility is set to True.
 586  *
 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.
 590  *
 591  * @see elm_datetime_field_visible_get()
 592  * @ingroup Datetime
 593  */
 594 EAPI void elm_datetime_field_visible_set(Evas_Object *obj, Elm_Datetime_Field_Type fieldtype, Eina_Bool visible);
 595
 596 /**
 597  * @}
 598  */