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