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      *elm_clock_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
  76
  77    /**
  78     * Set a clock widget's time, programmatically
  79     *
  80     * @param obj The clock widget object
  81     * @param hrs The hours to set
  82     * @param min The minutes to set
  83     * @param sec The secondes to set
  84     *
  85     * This function updates the time that is showed by the clock
  86     * widget.
  87     *
  88     *  Values @b must be set within the following ranges:
  89     * - 0 - 23, for hours
  90     * - 0 - 59, for minutes
  91     * - 0 - 59, for seconds,
  92     *
  93     * even if the clock is not in "military" mode.
  94     *
  95     * @warning The behavior for values set out of those ranges is @b
  96     * undefined.
  97     *
  98     * @ingroup Clock
  99     */
 100    EAPI void              elm_clock_time_set(Evas_Object *obj, int hrs, int min, int sec) EINA_ARG_NONNULL(1);
 101
 102    /**
 103     * Get a clock widget's time values
 104     *
 105     * @param obj The clock object
 106     * @param[out] hrs Pointer to the variable to get the hours value
 107     * @param[out] min Pointer to the variable to get the minutes value
 108     * @param[out] sec Pointer to the variable to get the seconds value
 109     *
 110     * This function gets the time set for @p obj, returning
 111     * it on the variables passed as the arguments to function
 112     *
 113     * @note Use @c NULL pointers on the time values you're not
 114     * interested in: they'll be ignored by the function.
 115     *
 116     * @ingroup Clock
 117     */
 118    EAPI void              elm_clock_time_get(const Evas_Object *obj, int *hrs, int *min, int *sec) EINA_ARG_NONNULL(1);
 119
 120    /**
 121     * Set whether a given clock widget is under <b>edition mode</b> or
 122     * under (default) displaying-only mode.
 123     *
 124     * @param obj The clock object
 125     * @param edit @c EINA_TRUE to put it in edition, @c EINA_FALSE to
 126     * put it back to "displaying only" mode
 127     *
 128     * This function makes a clock's time to be editable or not <b>by
 129     * user interaction</b>. When in edition mode, clocks @b stop
 130     * ticking, until one brings them back to canonical mode. The
 131     * elm_clock_digit_edit_set() function will influence which digits
 132     * of the clock will be editable. By default, all of them will be
 133     * (#ELM_CLOCK_NONE).
 134     *
 135     * @note am/pm sheets, if being shown, will @b always be editable
 136     * under edition mode.
 137     *
 138     * @see elm_clock_edit_get()
 139     *
 140     * @ingroup Clock
 141     */
 142    EAPI void              elm_clock_edit_set(Evas_Object *obj, Eina_Bool edit) EINA_ARG_NONNULL(1);
 143
 144    /**
 145     * Retrieve whether a given clock widget is under <b>edition
 146     * mode</b> or under (default) displaying-only mode.
 147     *
 148     * @param obj The clock object
 149     * @param edit @c EINA_TRUE, if it's in edition mode, @c EINA_FALSE
 150     * otherwise
 151     *
 152     * This function retrieves whether the clock's time can be edited
 153     * or not by user interaction.
 154     *
 155     * @see elm_clock_edit_set() for more details
 156     *
 157     * @ingroup Clock
 158     */
 159    EAPI Eina_Bool         elm_clock_edit_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 160
 161    /**
 162     * Set what digits of the given clock widget should be editable
 163     * when in edition mode.
 164     *
 165     * @param obj The clock object
 166     * @param digedit Bit mask indicating the digits to be editable
 167     * (values in #Elm_Clock_Digedit).
 168     *
 169     * If the @p digedit param is #ELM_CLOCK_NONE, editing will be
 170     * disabled on @p obj (same effect as elm_clock_edit_set(), with @c
 171     * EINA_FALSE).
 172     *
 173     * @see elm_clock_digit_edit_get()
 174     *
 175     * @ingroup Clock
 176     */
 177    EAPI void              elm_clock_digit_edit_set(Evas_Object *obj, Elm_Clock_Digedit digedit) EINA_ARG_NONNULL(1);
 178
 179    /**
 180     * Retrieve what digits of the given clock widget should be
 181     * editable when in edition mode.
 182     *
 183     * @param obj The clock object
 184     * @return Bit mask indicating the digits to be editable
 185     * (values in #Elm_Clock_Digedit).
 186     *
 187     * @see elm_clock_digit_edit_set() for more details
 188     *
 189     * @ingroup Clock
 190     */
 191    EAPI Elm_Clock_Digedit elm_clock_digit_edit_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 192
 193    /**
 194     * Set if the given clock widget must show hours in military or
 195     * am/pm mode
 196     *
 197     * @param obj The clock object
 198     * @param am_pm @c EINA_TRUE to put it in am/pm mode, @c EINA_FALSE
 199     * to military mode
 200     *
 201     * This function sets if the clock must show hours in military or
 202     * am/pm mode. In some countries like Brazil the military mode
 203     * (00-24h-format) is used, in opposition to the USA, where the
 204     * am/pm mode is more commonly used.
 205     *
 206     * @see elm_clock_show_am_pm_get()
 207     *
 208     * @ingroup Clock
 209     */
 210    EAPI void              elm_clock_show_am_pm_set(Evas_Object *obj, Eina_Bool am_pm) EINA_ARG_NONNULL(1);
 211
 212    /**
 213     * Get if the given clock widget shows hours in military or am/pm
 214     * mode
 215     *
 216     * @param obj The clock object
 217     * @return @c EINA_TRUE, if in am/pm mode, @c EINA_FALSE if in
 218     * military
 219     *
 220     * This function gets if the clock shows hours in military or am/pm
 221     * mode.
 222     *
 223     * @see elm_clock_show_am_pm_set() for more details
 224     *
 225     * @ingroup Clock
 226     */
 227    EAPI Eina_Bool         elm_clock_show_am_pm_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 228
 229    /**
 230     * Set if the given clock widget must show time with seconds or not
 231     *
 232     * @param obj The clock object
 233     * @param seconds @c EINA_TRUE to show seconds, @c EINA_FALSE otherwise
 234     *
 235     * This function sets if the given clock must show or not elapsed
 236     * seconds. By default, they are @b not shown.
 237     *
 238     * @see elm_clock_show_seconds_get()
 239     *
 240     * @ingroup Clock
 241     */
 242    EAPI void              elm_clock_show_seconds_set(Evas_Object *obj, Eina_Bool seconds) EINA_ARG_NONNULL(1);
 243
 244    /**
 245     * Get whether the given clock widget is showing time with seconds
 246     * or not
 247     *
 248     * @param obj The clock object
 249     * @return @c EINA_TRUE if it's showing seconds, @c EINA_FALSE otherwise
 250     *
 251     * This function gets whether @p obj is showing or not the elapsed
 252     * seconds.
 253     *
 254     * @see elm_clock_show_seconds_set()
 255     *
 256     * @ingroup Clock
 257     */
 258    EAPI Eina_Bool         elm_clock_show_seconds_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 259
 260    /**
 261     * Set the interval on time updates for an user mouse button hold
 262     * on clock widgets' time edition.
 263     *
 264     * @param obj The clock object
 265     * @param interval The (first) interval value in seconds
 266     *
 267     * This interval value is @b decreased while the user holds the
 268     * mouse pointer either incrementing or decrementing a given the
 269     * clock digit's value.
 270     *
 271     * This helps the user to get to a given time distant from the
 272     * current one easier/faster, as it will start to flip quicker and
 273     * quicker on mouse button holds.
 274     *
 275     * The calculation for the next flip interval value, starting from
 276     * the one set with this call, is the previous interval divided by
 277     * 1.05, so it decreases a little bit.
 278     *
 279     * The default starting interval value for automatic flips is
 280     * @b 0.85 seconds.
 281     *
 282     * @see elm_clock_interval_get()
 283     *
 284     * @ingroup Clock
 285     */
 286    EAPI void              elm_clock_interval_set(Evas_Object *obj, double interval) EINA_ARG_NONNULL(1);
 287
 288    /**
 289     * Get the interval on time updates for an user mouse button hold
 290     * on clock widgets' time edition.
 291     *
 292     * @param obj The clock object
 293     * @return The (first) interval value, in seconds, set on it
 294     *
 295     * @see elm_clock_interval_set() for more details
 296     *
 297     * @ingroup Clock
 298     */
 299    EAPI double            elm_clock_interval_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 300
 301    /**
 302     * @}
 303     */
 304