src/lib/elm_clock.h

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