src/lib/elm_clock.h

   1 /**
   2  * @defgroup Clock Clock
   3  *
   4  * @image html img/widget/clock/preview-00.png
   5  * @image latex img/widget/clock/preview-00.eps
   6  *
   7  * This is a @b digital clock widget. In its default theme, it has a
   8  * vintage "flipping numbers clock" appearance, which will animate
   9  * sheets of individual algarisms individually as time goes by.
  10  *
  11  * A newly created clock will fetch system's time (already
  12  * considering local time adjustments) to start with, and will tick
  13 <<<<<<< HEAD
  14  * accondingly. It may or may not show seconds.
  15  *
  16  * Clocks have an @b edition mode. When in it, the sheets will
  17 =======
  18  * accordingly. It may or may not show seconds.
  19  *
  20  * Clocks have an @b edition  mode. When in it, the sheets will
  21 >>>>>>> remotes/origin/upstream
  22  * display extra arrow indications on the top and bottom and the
  23  * user may click on them to raise or lower the time values. After
  24  * it's told to exit edition mode, it will keep ticking with that
  25  * new time set (it keeps the difference from local time).
  26  *
  27  * Also, when under edition mode, user clicks on the cited arrows
  28  * which are @b held for some time will make the clock to flip the
  29 <<<<<<< HEAD
  30  * sheet, thus editing the time, continuosly and automatically for
  31 =======
  32  * sheet, thus editing the time, continuously and automatically for
  33 >>>>>>> remotes/origin/upstream
  34  * the user. The interval between sheet flips will keep growing in
  35  * time, so that it helps the user to reach a time which is distant
  36  * from the one set.
  37  *
  38  * The time display is, by default, in military mode (24h), but an
  39  * am/pm indicator may be optionally shown, too, when it will
  40  * switch to 12h.
  41  *
  42  * Smart callbacks one can register to:
  43  * - "changed" - the clock's user changed the time
  44  *
  45  * Supported elm_object common APIs.
  46  * @li elm_object_signal_emit
  47  * @li elm_object_signal_callback_add
  48 <<<<<<< HEAD
  49  * @li elm_object_signal_callbacka_del
  50 =======
  51  * @li elm_object_signal_callback_del
  52 >>>>>>> remotes/origin/upstream
  53  *
  54  * Here is an example on its usage:
  55  * @li @ref clock_example
  56  */
  57
  58 /**
  59  * @addtogroup Clock
  60  * @{
  61  */
  62
  63 /**
  64  * Identifiers for which clock digits should be editable, when a
  65 <<<<<<< HEAD
  66  * clock widget is in edition mode. Values may be ORed together to
  67  * make a mask, naturally.
  68  *
  69  * @see elm_clock_edit_set()
  70  * @see elm_clock_digit_edit_set()
  71  */
  72 typedef enum
  73 {
  74    ELM_CLOCK_NONE = 0, /**< Default value. Means that all digits are editable, when in edition mode. */
  75    ELM_CLOCK_HOUR_DECIMAL = 1 << 0, /**< Decimal algarism of hours value should be editable */
  76    ELM_CLOCK_HOUR_UNIT = 1 << 1, /**< Unit algarism of hours value should be editable */
  77    ELM_CLOCK_MIN_DECIMAL = 1 << 2, /**< Decimal algarism of minutes value should be editable */
  78    ELM_CLOCK_MIN_UNIT = 1 << 3, /**< Unit algarism of minutes value should be editable */
  79    ELM_CLOCK_SEC_DECIMAL = 1 << 4, /**< Decimal algarism of seconds value should be editable */
  80    ELM_CLOCK_SEC_UNIT = 1 << 5, /**< Unit algarism of seconds value should be editable */
  81    ELM_CLOCK_ALL = (1 << 6) - 1 /**< All digits should be editable */
  82 } Elm_Clock_Digedit;
  83 =======
  84  * clock widget is in edition mode. Values may be OR-ed together to
  85  * make a mask, naturally.
  86  *
  87  * @see elm_clock_edit_set()
  88  * @see elm_clock_edit_mode_set()
  89  */
  90 typedef enum
  91 {
  92    ELM_CLOCK_EDIT_DEFAULT = 0, /**< Default value. Means that all digits are editable, when in edition mode. */
  93    ELM_CLOCK_EDIT_HOUR_DECIMAL = 1 << 0, /**< Decimal algarism of hours value should be editable */
  94    ELM_CLOCK_EDIT_HOUR_UNIT = 1 << 1, /**< Unit algarism of hours value should be editable */
  95    ELM_CLOCK_EDIT_MIN_DECIMAL = 1 << 2, /**< Decimal algarism of minutes value should be editable */
  96    ELM_CLOCK_EDIT_MIN_UNIT = 1 << 3, /**< Unit algarism of minutes value should be editable */
  97    ELM_CLOCK_EDIT_SEC_DECIMAL = 1 << 4, /**< Decimal algarism of seconds value should be editable */
  98    ELM_CLOCK_EDIT_SEC_UNIT = 1 << 5, /**< Unit algarism of seconds value should be editable */
  99    ELM_CLOCK_EDIT_ALL = (1 << 6) - 1 /**< All digits should be editable */
 100 } Elm_Clock_Edit_Mode;
 101 >>>>>>> remotes/origin/upstream
 102
 103 /**
 104  * Add a new clock widget to the given parent Elementary
 105  * (container) object
 106  *
 107  * @param parent The parent object
 108  * @return a new clock widget handle or @c NULL, on errors
 109  *
 110  * This function inserts a new clock widget on the canvas.
 111  *
 112  * @ingroup Clock
 113  */
 114 EAPI Evas_Object      *elm_clock_add(Evas_Object *parent);
 115
 116 /**
 117  * Set a clock widget's time, programmatically
 118  *
 119  * @param obj The clock widget object
 120  * @param hrs The hours to set
 121  * @param min The minutes to set
 122 <<<<<<< HEAD
 123  * @param sec The secondes to set
 124 =======
 125  * @param sec The seconds to set
 126 >>>>>>> remotes/origin/upstream
 127  *
 128  * This function updates the time that is showed by the clock
 129  * widget.
 130  *
 131  *  Values @b must be set within the following ranges:
 132  * - 0 - 23, for hours
 133  * - 0 - 59, for minutes
 134  * - 0 - 59, for seconds,
 135  *
 136  * even if the clock is not in "military" mode.
 137  *
 138  * @warning The behavior for values set out of those ranges is @b
 139  * undefined.
 140  *
 141  * @ingroup Clock
 142  */
 143 EAPI void              elm_clock_time_set(Evas_Object *obj, int hrs, int min, int sec);
 144
 145 /**
 146  * Get a clock widget's time values
 147  *
 148  * @param obj The clock object
 149  * @param[out] hrs Pointer to the variable to get the hours value
 150  * @param[out] min Pointer to the variable to get the minutes value
 151  * @param[out] sec Pointer to the variable to get the seconds value
 152  *
 153  * This function gets the time set for @p obj, returning
 154  * it on the variables passed as the arguments to function
 155  *
 156  * @note Use @c NULL pointers on the time values you're not
 157  * interested in: they'll be ignored by the function.
 158  *
 159  * @ingroup Clock
 160  */
 161 EAPI void              elm_clock_time_get(const Evas_Object *obj, int *hrs, int *min, int *sec);
 162
 163 /**
 164  * Set whether a given clock widget is under <b>edition mode</b> or
 165  * under (default) displaying-only mode.
 166  *
 167  * @param obj The clock object
 168  * @param edit @c EINA_TRUE to put it in edition, @c EINA_FALSE to
 169  * put it back to "displaying only" mode
 170  *
 171  * This function makes a clock's time to be editable or not <b>by
 172  * user interaction</b>. When in edition mode, clocks @b stop
 173  * ticking, until one brings them back to canonical mode. The
 174 <<<<<<< HEAD
 175  * elm_clock_digit_edit_set() function will influence which digits
 176 =======
 177  * elm_clock_edit_mode_set() function will influence which digits
 178 >>>>>>> remotes/origin/upstream
 179  * of the clock will be editable. By default, all of them will be
 180  * (#ELM_CLOCK_NONE).
 181  *
 182  * @note am/pm sheets, if being shown, will @b always be editable
 183  * under edition mode.
 184  *
 185  * @see elm_clock_edit_get()
 186  *
 187  * @ingroup Clock
 188  */
 189 EAPI void              elm_clock_edit_set(Evas_Object *obj, Eina_Bool edit);
 190
 191 /**
 192  * Retrieve whether a given clock widget is under editing mode
 193  * or under (default) displaying-only mode.
 194  *
 195  * @param obj The clock object
 196  * @return @c EINA_TRUE, if it's in edition mode, @c EINA_FALSE otherwise
 197  *
 198  * This function retrieves whether the clock's time can be edited
 199  * or not by user interaction.
 200  *
 201  * @see elm_clock_edit_set() for more details
 202  *
 203  * @ingroup Clock
 204  */
 205 EAPI Eina_Bool         elm_clock_edit_get(const Evas_Object *obj);
 206
 207 /**
 208  * Set what digits of the given clock widget should be editable
 209  * when in edition mode.
 210  *
 211  * @param obj The clock object
 212  * @param digedit Bit mask indicating the digits to be editable
 213 <<<<<<< HEAD
 214  * (values in #Elm_Clock_Digedit).
 215 =======
 216  * (values in #Elm_Clock_Edit_Mode).
 217 >>>>>>> remotes/origin/upstream
 218  *
 219  * If the @p digedit param is #ELM_CLOCK_NONE, editing will be
 220  * disabled on @p obj (same effect as elm_clock_edit_set(), with @c
 221  * EINA_FALSE).
 222  *
 223 <<<<<<< HEAD
 224  * @see elm_clock_digit_edit_get()
 225  *
 226  * @ingroup Clock
 227  */
 228 EAPI void              elm_clock_digit_edit_set(Evas_Object *obj, Elm_Clock_Digedit digedit);
 229 =======
 230  * @see elm_clock_edit_mode_get()
 231  *
 232  * @ingroup Clock
 233  */
 234 EAPI void              elm_clock_edit_mode_set(Evas_Object *obj, Elm_Clock_Edit_Mode digedit);
 235 >>>>>>> remotes/origin/upstream
 236
 237 /**
 238  * Retrieve what digits of the given clock widget should be
 239  * editable when in edition mode.
 240  *
 241  * @param obj The clock object
 242  * @return Bit mask indicating the digits to be editable
 243 <<<<<<< HEAD
 244  * (values in #Elm_Clock_Digedit).
 245  *
 246  * @see elm_clock_digit_edit_set() for more details
 247  *
 248  * @ingroup Clock
 249  */
 250 EAPI Elm_Clock_Digedit elm_clock_digit_edit_get(const Evas_Object *obj);
 251 =======
 252  * (values in #Elm_Clock_Edit_Mode).
 253  *
 254  * @see elm_clock_edit_mode_set() for more details
 255  *
 256  * @ingroup Clock
 257  */
 258 EAPI Elm_Clock_Edit_Mode elm_clock_edit_mode_get(const Evas_Object *obj);
 259 >>>>>>> remotes/origin/upstream
 260
 261 /**
 262  * Set if the given clock widget must show hours in military or
 263  * am/pm mode
 264  *
 265  * @param obj The clock object
 266  * @param am_pm @c EINA_TRUE to put it in am/pm mode, @c EINA_FALSE
 267  * to military mode
 268  *
 269  * This function sets if the clock must show hours in military or
 270  * am/pm mode. In some countries like Brazil the military mode
 271  * (00-24h-format) is used, in opposition to the USA, where the
 272  * am/pm mode is more commonly used.
 273  *
 274  * @see elm_clock_show_am_pm_get()
 275  *
 276  * @ingroup Clock
 277  */
 278 EAPI void              elm_clock_show_am_pm_set(Evas_Object *obj, Eina_Bool am_pm);
 279
 280 /**
 281  * Get if the given clock widget shows hours in military or am/pm
 282  * mode
 283  *
 284  * @param obj The clock object
 285  * @return @c EINA_TRUE, if in am/pm mode, @c EINA_FALSE if in
 286  * military
 287  *
 288  * This function gets if the clock shows hours in military or am/pm
 289  * mode.
 290  *
 291  * @see elm_clock_show_am_pm_set() for more details
 292  *
 293  * @ingroup Clock
 294  */
 295 EAPI Eina_Bool         elm_clock_show_am_pm_get(const Evas_Object *obj);
 296
 297 /**
 298  * Set if the given clock widget must show time with seconds or not
 299  *
 300  * @param obj The clock object
 301  * @param seconds @c EINA_TRUE to show seconds, @c EINA_FALSE otherwise
 302  *
 303  * This function sets if the given clock must show or not elapsed
 304  * seconds. By default, they are @b not shown.
 305  *
 306  * @see elm_clock_show_seconds_get()
 307  *
 308  * @ingroup Clock
 309  */
 310 EAPI void              elm_clock_show_seconds_set(Evas_Object *obj, Eina_Bool seconds);
 311
 312 /**
 313  * Get whether the given clock widget is showing time with seconds
 314  * or not
 315  *
 316  * @param obj The clock object
 317  * @return @c EINA_TRUE if it's showing seconds, @c EINA_FALSE otherwise
 318  *
 319  * This function gets whether @p obj is showing or not the elapsed
 320  * seconds.
 321  *
 322  * @see elm_clock_show_seconds_set()
 323  *
 324  * @ingroup Clock
 325  */
 326 EAPI Eina_Bool         elm_clock_show_seconds_get(const Evas_Object *obj);
 327
 328 /**
 329 <<<<<<< HEAD
 330  * Set the interval on time updates for an user mouse button hold
 331  * on clock widgets' time edition.
 332  *
 333  * @param obj The clock object
 334  * @param interval The (first) interval value in seconds
 335 =======
 336  * Set the first interval on time updates for a user mouse button hold
 337  * on clock widgets' time edition.
 338  *
 339  * @param obj The clock object
 340  * @param interval The first interval value in seconds
 341 >>>>>>> remotes/origin/upstream
 342  *
 343  * This interval value is @b decreased while the user holds the
 344  * mouse pointer either incrementing or decrementing a given the
 345  * clock digit's value.
 346  *
 347  * This helps the user to get to a given time distant from the
 348  * current one easier/faster, as it will start to flip quicker and
 349  * quicker on mouse button holds.
 350  *
 351  * The calculation for the next flip interval value, starting from
 352  * the one set with this call, is the previous interval divided by
 353  * 1.05, so it decreases a little bit.
 354  *
 355  * The default starting interval value for automatic flips is
 356  * @b 0.85 seconds.
 357  *
 358 <<<<<<< HEAD
 359  * @see elm_clock_interval_get()
 360  *
 361  * @ingroup Clock
 362  */
 363 EAPI void              elm_clock_interval_set(Evas_Object *obj, double interval);
 364
 365 /**
 366  * Get the interval on time updates for an user mouse button hold
 367  * on clock widgets' time edition.
 368  *
 369  * @param obj The clock object
 370  * @return The (first) interval value, in seconds, set on it
 371  *
 372  * @see elm_clock_interval_set() for more details
 373  *
 374  * @ingroup Clock
 375  */
 376 EAPI double            elm_clock_interval_get(const Evas_Object *obj);
 377 =======
 378  * @see elm_clock_first_interval_get()
 379  *
 380  * @ingroup Clock
 381  */
 382 EAPI void              elm_clock_first_interval_set(Evas_Object *obj, double interval);
 383
 384 /**
 385  * Get the first interval on time updates for a user mouse button hold
 386  * on clock widgets' time edition.
 387  *
 388  * @param obj The clock object
 389  * @return The first interval value, in seconds, set on it
 390  *
 391  * @see elm_clock_first_interval_set() for more details
 392  *
 393  * @ingroup Clock
 394  */
 395 EAPI double            elm_clock_first_interval_get(const Evas_Object *obj);
 396 >>>>>>> remotes/origin/upstream
 397
 398 /**
 399  * @}
 400  */