src/lib/elm_clock.h

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