src/lib/elm_datetime.h

   1
   2    /**
   3     * @defgroup Datetime Datetime
   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     */