1 /** 2 * @defgroup Elm_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 Elm_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 Elm_Layout : 182 * @li @b "changed" - whenever Datetime field value is changed, this 183 * signal is sent. 184 * @li @b "language,changed" - whenever system locale changes, this 185 * signal is sent. 186 * @li @c "focused" - When the datetime has received focus. (since 1.8) 187 * @li @c "unfocused" - When the datetime has lost focus. (since 1.8) 188 * 189 * Here is an example on its usage: 190 * @li @ref datetime_example 191 * 192 */ 193 194 /** 195 * @addtogroup Elm_Datetime 196 * @{ 197 */ 198 199 /** Identifies a Datetime field, The widget supports 6 fields : Year, month, 200 ** Date, Hour, Minute, AM/PM 201 ** 202 ** @ingroup Elm_Datetime 203 **/ 204 205 #ifndef _ELM_DATE_TIME_H 206 #define _ELM_DATE_TIME_H 207 #include <elm_clock_eo.h> 208 typedef enum 209 { 210 ELM_DATETIME_YEAR = 0, /**< Indicates Year field. */ 211 ELM_DATETIME_MONTH = 1, /**< Indicates Month field. */ 212 ELM_DATETIME_DATE = 2, /**< Indicates Date field. */ 213 ELM_DATETIME_HOUR = 3, /**< Indicates Hour field. */ 214 ELM_DATETIME_MINUTE = 4, /**< Indicates Minute field. */ 215 ELM_DATETIME_AMPM = 5 /**< Indicates AM/PM field . */ 216 } Elm_Datetime_Field_Type; 217 218 typedef Eo Elm_Datetime; 219 220 /** 221 * @brief Adds a new datetime Widget 222 * 223 * The default datetime format and corresponding strings are based on current locale. 224 * 225 * @param parent The parent object 226 * @return The new object or NULL if it cannot be created 227 * 228 * This function inserts a new datetime widget on the canvas. 229 * 230 * @ingroup Elm_Datetime 231 */ 232 EAPI Evas_Object *elm_datetime_add(Evas_Object *parent); 233 234 /** 235 * @brief Set the datetime format. Format is a combination of allowed Libc date 236 * format specifiers like: "%b %d, %Y %I : %M %p". 237 * 238 * Maximum allowed format length is 64 chars. 239 * 240 * Format can include separators for each individual datetime field except for 241 * AM/PM field. 242 * 243 * Each separator can be a maximum of 6 UTF-8 bytes. Space is also taken as a 244 * separator. 245 * 246 * These specifiers can be arranged in any order and the widget will display 247 * the fields accordingly. 248 * 249 * Default format is taken as per the system locale settings. 250 * 251 * @param[in] fmt The datetime format. 252 * 253 * @ingroup Elm_Datetime 254 */ 255 EAPI void elm_datetime_format_set(Evas_Object *obj, const char *fmt); 256 257 /** 258 * @brief Get the datetime format. 259 * 260 * @return The datetime format. 261 * 262 * @ingroup Elm_Datetime 263 */ 264 EAPI const char *elm_datetime_format_get(const Evas_Object *obj); 265 266 /** 267 * @brief Set the field limits of a field. 268 * 269 * Limits can be set to individual fields, independently, except for AM/PM 270 * field. Any field can display the values only in between these minimum and 271 * maximum limits unless the corresponding time value is restricted from 272 * MinTime to MaxTime. That is, min/max field limits always works under the 273 * limitations of mintime/maxtime. 274 * 275 * There is no provision to set the limits of AM/PM field. 276 * 277 * @param[in] type Type of the field. #ELM_DATETIME_YEAR etc. 278 * @param[in] min Reference to field's minimum value. 279 * @param[in] max Reference to field's maximum value. 280 * 281 * @ingroup Elm_Datetime 282 */ 283 EAPI void elm_datetime_field_limit_set(Evas_Object *obj, Elm_Datetime_Field_Type type, int min, int max); 284 285 /** 286 * @brief Get the field limits of a field. 287 * 288 * Limits can be set to individual fields, independently, except for AM/PM 289 * field. Any field can display the values only in between these minimum and 290 * maximum limits unless the corresponding time value is restricted from 291 * MinTime to MaxTime. That is, min/max field limits always works under the 292 * limitations of mintime/maxtime. 293 * 294 * There is no provision to set the limits of AM/PM field. 295 * 296 * @param[in] fieldtype Type of the field. #ELM_DATETIME_YEAR etc. 297 * @param[out] min Reference to field's minimum value. 298 * @param[out] max Reference to field's maximum value. 299 * 300 * @ingroup Elm_Datetime 301 */ 302 EAPI void elm_datetime_field_limit_get(const Evas_Object *obj, Elm_Datetime_Field_Type fieldtype, int *min, int *max); 303 304 /** 305 * @brief Set the lower boundary of a field. 306 * 307 * Year: years since 1900. Negative value represents year below 1900 (year 308 * value -30 represents 1870). Year default range is from 70 to 137. 309 * 310 * Month: default value range is from 0 to 11. 311 * 312 * Date: default value range is from 1 to 31 according to the month value. 313 * 314 * Hour: default value will be in terms of 24 hr format (0~23) 315 * 316 * Minute: default value range is from 0 to 59. 317 * 318 * @param[in] mintime Time structure containing the minimum time value. 319 * 320 * @return @c true if minimum value is accepted. 321 * 322 * @ingroup Elm_Datetime 323 */ 324 EAPI Eina_Bool elm_datetime_value_min_set(Evas_Object *obj, const Efl_Time *mintime); 325 326 /** 327 * @brief Get the lower boundary of a field. 328 * 329 * Year: years since 1900. Negative value represents year below 1900 (year 330 * value -30 represents 1870). Year default range is from 70 to 137. 331 * 332 * Month: default value range is from 0 to 11. 333 * 334 * Date: default value range is from 1 to 31 according to the month value. 335 * 336 * Hour: default value will be in terms of 24 hr format (0~23) 337 * 338 * Minute: default value range is from 0 to 59. 339 * 340 * @param[in,out] mintime Time structure. 341 * 342 * @return @c true if minimum value is successfully returned. 343 * 344 * @ingroup Elm_Datetime 345 */ 346 EAPI Eina_Bool elm_datetime_value_min_get(const Evas_Object *obj, Efl_Time *mintime); 347 348 /** 349 * @brief Set the current value of a Datetime object. 350 * 351 * Year: years since 1900. Negative value represents year below 1900 (year 352 * value -30 represents 1870). Year default range is from 70 to 137. 353 * 354 * Month: default value range is from 0 to 11. 355 * 356 * Date: default value range is from 1 to 31 according to the month value. 357 * 358 * Hour: default value will be in terms of 24 hr format (0~23) 359 * 360 * Minute: default value range is from 0 to 59. 361 * 362 * @param[in] newtime Time structure filled with values to be set. 363 * 364 * @return @c true if current time is set successfully. 365 * 366 * @ingroup Elm_Datetime 367 */ 368 EAPI Eina_Bool elm_datetime_value_set(Evas_Object *obj, const Efl_Time *newtime); 369 370 /** 371 * @brief Get the current value of a Datetime object. 372 * 373 * Year: years since 1900. Negative value represents year below 1900 (year 374 * value -30 represents 1870). Year default range is from 70 to 137. 375 * 376 * Month: default value range is from 0 to 11. 377 * 378 * Date: default value range is from 1 to 31 according to the month value. 379 * 380 * Hour: default value will be in terms of 24 hr format (0~23) 381 * 382 * Minute: default value range is from 0 to 59. 383 * 384 * @param[in,out] currtime Time structure. 385 * 386 * @return @c true if current time is returned successfully. 387 * 388 * @ingroup Elm_Datetime 389 */ 390 EAPI Eina_Bool elm_datetime_value_get(const Evas_Object *obj, Efl_Time *currtime); 391 392 /** 393 * @brief Set a field to be visible or not. 394 * 395 * Setting this API to @c true does not ensure that the field is visible, apart 396 * from this, the field's format must be present in Datetime overall format. 397 * If a field's visibility is set to @c false then it won't appear even though 398 * its format is present in overall format. So if and only if this API is set 399 * true and the corresponding field's format is present in Datetime format, the 400 * field is visible. 401 * 402 * By default the field visibility is set to @c true. 403 * 404 * @param[in] fieldtype Type of the field. #ELM_DATETIME_YEAR etc. 405 * @param[in] visible @c true field can be visible, @c false otherwise. 406 * 407 * @ingroup Elm_Datetime 408 */ 409 EAPI void elm_datetime_field_visible_set(Evas_Object *obj, Elm_Datetime_Field_Type fieldtype, Eina_Bool visible); 410 411 /** 412 * @brief Get whether a field can be visible/not. 413 * 414 * @param[in] fieldtype Type of the field. #ELM_DATETIME_YEAR etc. 415 * 416 * @return @c true, if field can be visible. @c false otherwise. 417 * 418 * @ingroup Elm_Datetime 419 */ 420 EAPI Eina_Bool elm_datetime_field_visible_get(const Evas_Object *obj, Elm_Datetime_Field_Type fieldtype); 421 422 /** 423 * @brief Set the upper boundary of a field. 424 * 425 * Year: years since 1900. Negative value represents year below 1900 (year 426 * value -30 represents 1870). Year default range is from 70 to 137. 427 * 428 * Month: default value range is from 0 to 11. 429 * 430 * Date: default value range is from 1 to 31 according to the month value. 431 * 432 * Hour: default value will be in terms of 24 hr format (0~23) 433 * 434 * Minute: default value range is from 0 to 59. 435 * 436 * @param[in] maxtime Time structure containing the maximum time value. 437 * 438 * @return @c true if maximum value is accepted. 439 * 440 * @ingroup Elm_Datetime 441 */ 442 EAPI Eina_Bool elm_datetime_value_max_set(Evas_Object *obj, const Efl_Time *maxtime); 443 444 /** 445 * @brief Get the upper boundary of a field. 446 * 447 * Year: years since 1900. Negative value represents year below 1900 (year 448 * value -30 represents 1870). Year default range is from 70 to 137. 449 * 450 * Month: default value range is from 0 to 11. 451 * 452 * Date: default value range is from 1 to 31 according to the month value. 453 * 454 * Hour: default value will be in terms of 24 hr format (0~23) 455 * 456 * Minute: default value range is from 0 to 59. 457 * 458 * @param[in,out] maxtime Time structure containing the maximum time value. 459 * 460 * @return @c true if maximum value is returned successfully. 461 * 462 * @ingroup Elm_Datetime 463 */ 464 EAPI Eina_Bool elm_datetime_value_max_get(const Evas_Object *obj, Efl_Time *maxtime); 465 466 #define ELM_DATETIME_EVENT_CHANGED ELM_CLOCK_EVENT_CHANGED 467 468 #endif 469 /** 470 * @} 471 */ 472
