wearable/src/lib/elm_spinner.h

   1 /**
   2  * @defgroup Spinner Spinner
   3  * @ingroup Elementary
   4  *
   5  * @image html spinner_inheritance_tree.png
   6  * @image latex spinner_inheritance_tree.eps
   7  *
   8  * @image html img/widget/spinner/preview-00.png
   9  * @image latex img/widget/spinner/preview-00.eps
  10  *
  11  * A spinner is a widget which allows the user to increase or decrease
  12  * numeric values using arrow buttons, or edit values directly, clicking
  13  * over it and typing the new value.
  14  *
  15  * By default the spinner will not wrap and has a label
  16  * of "%.0f" (just showing the integer value of the double).
  17  *
  18  * A spinner has a label that is formatted with floating
  19  * point values and thus accepts a printf-style format string, like
  20  * “%1.2f units”.
  21  *
  22  * It also allows specific values to be replaced by pre-defined labels.
  23  *
  24  * This widget inherits from the @ref Layout one, so that all the
  25  * functions acting on it also work for spinner objects.
  26  *
  27  * This widget emits the following signals, besides the ones sent from
  28  * @ref Layout:
  29  * - @c "changed" - Whenever the spinner value is changed.
  30  * - @c "delay,changed" - A short time after the value is changed by
  31  *    the user.  This will be called only when the user stops dragging
  32  *    for a very short period or when they release their finger/mouse,
  33  *    so it avoids possibly expensive reactions to the value change.
  34  * - @c "language,changed" - the program's language changed
  35  *
  36  * Available styles for it:
  37  * - @c "default";
  38  * - @c "vertical": up/down buttons at the right side and text left aligned.
  39  *
  40  * Supported elm_object common APIs.
  41  * @li @ref elm_object_signal_emit
  42  * @li @ref elm_object_signal_callback_add
  43  * @li @ref elm_object_signal_callback_del
  44  * @li @ref elm_object_disabled_set
  45  * @li @ref elm_object_disabled_get
  46  *
  47  * Here is an example on its usage:
  48  * @ref spinner_example
  49  */
  50
  51 /**
  52  * @addtogroup Spinner
  53  * @{
  54  */
  55
  56 /**
  57  * Add a new spinner widget to the given parent Elementary
  58  * (container) object.
  59  *
  60  * @param parent The parent object.
  61  * @return a new spinner widget handle or @c NULL, on errors.
  62  *
  63  * This function inserts a new spinner widget on the canvas.
  64  *
  65  * @ingroup Spinner
  66  *
  67  */
  68 EAPI Evas_Object *elm_spinner_add(Evas_Object *parent);
  69
  70 /**
  71  * Set the format string of the displayed label.
  72  *
  73  * @param obj The spinner object.
  74  * @param fmt The format string for the label display.
  75  *
  76  * If @c NULL, this sets the format to "%.0f". If not it sets the format
  77  * string for the label text. The label text is provided a floating point
  78  * value, so the label text can display up to 1 floating point value.
  79  * Note that this is optional.
  80  *
  81  * Use a format string such as "%1.2f meters" for example, and it will
  82  * display values like: "3.14 meters" for a value equal to 3.14159.
  83  *
  84  * Default is "%0.f".
  85  *
  86  * @see elm_spinner_label_format_get()
  87  *
  88  * @ingroup Spinner
  89  */
  90 EAPI void        elm_spinner_label_format_set(Evas_Object *obj, const char *fmt);
  91
  92 /**
  93  * Get the label format of the spinner.
  94  *
  95  * @param obj The spinner object.
  96  * @return The text label format string in UTF-8.
  97  *
  98  * @see elm_spinner_label_format_set() for details.
  99  *
 100  * @ingroup Spinner
 101  */
 102 EAPI const char *elm_spinner_label_format_get(const Evas_Object *obj);
 103
 104 /**
 105  * Set the minimum and maximum values for the spinner.
 106  *
 107  * @param obj The spinner object.
 108  * @param min The minimum value.
 109  * @param max The maximum value.
 110  *
 111  * Define the allowed range of values to be selected by the user.
 112  *
 113  * If actual value is less than @p min, it will be updated to @p min. If it
 114  * is bigger then @p max, will be updated to @p max. Actual value can be
 115  * get with elm_spinner_value_get().
 116  *
 117  * By default, min is equal to 0, and max is equal to 100.
 118  *
 119  * @warning Maximum must be greater than minimum.
 120  *
 121  * @see elm_spinner_min_max_get()
 122  *
 123  * @ingroup Spinner
 124  */
 125 EAPI void        elm_spinner_min_max_set(Evas_Object *obj, double min, double max);
 126
 127 /**
 128  * Get the minimum and maximum values of the spinner.
 129  *
 130  * @param obj The spinner object.
 131  * @param min Pointer to store the minimum value.
 132  * @param max Pointer to store the maximum value.
 133  *
 134  * @note If only one value is needed, the other pointer can be passed
 135  * as @c NULL.
 136  *
 137  * @see elm_spinner_min_max_set() for details.
 138  *
 139  * @ingroup Spinner
 140  */
 141 EAPI void        elm_spinner_min_max_get(const Evas_Object *obj, double *min, double *max);
 142
 143 /**
 144  * Set the step used to increment or decrement the spinner value.
 145  *
 146  * @param obj The spinner object.
 147  * @param step The step value.
 148  *
 149  * This value will be incremented or decremented to the displayed value.
 150  * It will be incremented while the user keep right or top arrow pressed,
 151  * and will be decremented while the user keep left or bottom arrow pressed.
 152  *
 153  * The interval to increment / decrement can be set with
 154  * elm_spinner_interval_set().
 155  *
 156  * By default step value is equal to 1.
 157  *
 158  * @see elm_spinner_step_get()
 159  *
 160  * @ingroup Spinner
 161  */
 162 EAPI void        elm_spinner_step_set(Evas_Object *obj, double step);
 163
 164 /**
 165  * Get the step used to increment or decrement the spinner value.
 166  *
 167  * @param obj The spinner object.
 168  * @return The step value.
 169  *
 170  * @see elm_spinner_step_get() for more details.
 171  *
 172  * @ingroup Spinner
 173  */
 174 EAPI double      elm_spinner_step_get(const Evas_Object *obj);
 175
 176 /**
 177  * Set the value the spinner displays.
 178  *
 179  * @param obj The spinner object.
 180  * @param val The value to be displayed.
 181  *
 182  * Value will be presented on the label following format specified with
 183  * elm_spinner_format_set().
 184  *
 185  * @warning The value must to be between min and max values. This values
 186  * are set by elm_spinner_min_max_set().
 187  *
 188  * @see elm_spinner_value_get().
 189  * @see elm_spinner_format_set().
 190  * @see elm_spinner_min_max_set().
 191  *
 192  * @ingroup Spinner
 193  */
 194 EAPI void        elm_spinner_value_set(Evas_Object *obj, double val);
 195
 196 /**
 197  * Get the value displayed by the spinner.
 198  *
 199  * @param obj The spinner object.
 200  * @return The value displayed.
 201  *
 202  * @see elm_spinner_value_set() for details.
 203  *
 204  * @ingroup Spinner
 205  */
 206 EAPI double      elm_spinner_value_get(const Evas_Object *obj);
 207
 208 /**
 209  * Set whether the spinner should wrap when it reaches its
 210  * minimum or maximum value.
 211  *
 212  * @param obj The spinner object.
 213  * @param wrap @c EINA_TRUE to enable wrap or @c EINA_FALSE to
 214  * disable it.
 215  *
 216  * Disabled by default. If disabled, when the user tries to increment the
 217  * value,
 218  * but displayed value plus step value is bigger than maximum value,
 219  * the new value will be the maximum value.
 220  * The same happens when the user tries to decrement it,
 221  * but the value less step is less than minimum value. In this case,
 222  * the new displayed value will be the minimum value.
 223  *
 224  * When wrap is enabled, when the user tries to increment the value,
 225  * but displayed value plus step value is bigger than maximum value,
 226  * the new value will be the minimum value. When the the user tries to
 227  * decrement it, but the value less step is less than minimum value,
 228  * the new displayed value will be the maximum value.
 229  *
 230  * E.g.:
 231  * @li min value = 10
 232  * @li max value = 50
 233  * @li step value = 20
 234  * @li displayed value = 20
 235  *
 236  * When the user decrement value (using left or bottom arrow), it will
 237  * displays @c 50.
 238  *
 239  * @see elm_spinner_wrap_get().
 240  *
 241  * @ingroup Spinner
 242  */
 243 EAPI void        elm_spinner_wrap_set(Evas_Object *obj, Eina_Bool wrap);
 244
 245 /**
 246  * Get whether the spinner should wrap when it reaches its
 247  * minimum or maximum value.
 248  *
 249  * @param obj The spinner object
 250  * @return @c EINA_TRUE means wrap is enabled. @c EINA_FALSE indicates
 251  * it's disabled. If @p obj is @c NULL, @c EINA_FALSE is returned.
 252  *
 253  * @see elm_spinner_wrap_set() for details.
 254  *
 255  * @ingroup Spinner
 256  */
 257 EAPI Eina_Bool   elm_spinner_wrap_get(const Evas_Object *obj);
 258
 259 /**
 260  * Set whether the spinner can be directly edited by the user or not.
 261  *
 262  * @param obj The spinner object.
 263  * @param editable @c EINA_TRUE to allow users to edit it or @c EINA_FALSE to
 264  * don't allow users to edit it directly.
 265  *
 266  * Spinner objects can have edition @b disabled, in which state they will
 267  * be changed only by arrows.
 268  * Useful for contexts
 269  * where you don't want your users to interact with it writing the value.
 270  * Specially
 271  * when using special values, the user can see real value instead
 272  * of special label on edition.
 273  *
 274  * It's enabled by default.
 275  *
 276  * @see elm_spinner_editable_get()
 277  *
 278  * @ingroup Spinner
 279  */
 280 EAPI void        elm_spinner_editable_set(Evas_Object *obj, Eina_Bool editable);
 281
 282 /**
 283  * Get whether the spinner can be directly edited by the user or not.
 284  *
 285  * @param obj The spinner object.
 286  * @return @c EINA_TRUE means edition is enabled. @c EINA_FALSE indicates
 287  * it's disabled. If @p obj is @c NULL, @c EINA_FALSE is returned.
 288  *
 289  * @see elm_spinner_editable_set() for details.
 290  *
 291  * @ingroup Spinner
 292  */
 293 EAPI Eina_Bool   elm_spinner_editable_get(const Evas_Object *obj);
 294
 295 /**
 296  * Set a special string to display in the place of the numerical value.
 297  *
 298  * @param obj The spinner object.
 299  * @param value The value to be replaced.
 300  * @param label The label to be used.
 301  *
 302  * It's useful for cases when a user should select an item that is
 303  * better indicated by a label than a value. For example, weekdays or months.
 304  *
 305  * E.g.:
 306  * @code
 307  * sp = elm_spinner_add(win);
 308  * elm_spinner_min_max_set(sp, 1, 3);
 309  * elm_spinner_special_value_add(sp, 1, "January");
 310  * elm_spinner_special_value_add(sp, 2, "February");
 311  * elm_spinner_special_value_add(sp, 3, "March");
 312  * evas_object_show(sp);
 313  * @endcode
 314  *
 315  * @note If another label was previously set to @p value, it will be replaced
 316  * by the new label.
 317  *
 318  * @see elm_spinner_special_value_get().
 319  * @see elm_spinner_special_value_del().
 320  *
 321  * @ingroup Spinner
 322  */
 323 EAPI void        elm_spinner_special_value_add(Evas_Object *obj, double value, const char *label);
 324
 325 /**
 326  * Delete the special string display in the place of the numerical value.
 327  *
 328  * @param obj The spinner object.
 329  * @param value The replaced value.
 330  *
 331  * It will remove a previously added special value. After this, the spinner
 332  * will display the value itself instead of a label.
 333  *
 334  * @see elm_spinner_special_value_add() for more details.
 335  *
 336  * @ingroup Spinner
 337  * @since 1.8
 338  */
 339 EAPI void elm_spinner_special_value_del(Evas_Object *obj, double value);
 340
 341 /**
 342  * Get the special string display in the place of the numerical value.
 343  *
 344  * @param obj The spinner object.
 345  * @param value The replaced value.
 346  * @return The used label.
 347  *
 348  * @see elm_spinner_special_value_add() for more details.
 349  *
 350  * @ingroup Spinner
 351  * @since 1.8
 352  */
 353 EAPI const char *elm_spinner_special_value_get(Evas_Object *obj, double value);
 354
 355 /**
 356  * Set the interval on time updates for an user mouse button hold
 357  * on spinner widgets' arrows.
 358  *
 359  * @param obj The spinner object.
 360  * @param interval The interval value in seconds.
 361  *
 362  * This interval value is @b decreased while the user holds the
 363  * mouse pointer either incrementing or decrementing spinner's value.
 364  *
 365  * This helps the user to get to a given value distant from the
 366  * current one easier/faster, as it updates the value in that set interval time
 367  * on mouse button holds.
 368  *
 369  * The default starting interval value for automatic changes is
 370  * @c 0.85 seconds.
 371  *
 372  * @see elm_spinner_interval_get()
 373  *
 374  * @ingroup Spinner
 375  */
 376 EAPI void        elm_spinner_interval_set(Evas_Object *obj, double interval);
 377
 378 /**
 379  * Get the interval on time updates for an user mouse button hold
 380  * on spinner widgets' arrows.
 381  *
 382  * @param obj The spinner object.
 383  * @return The interval value, in seconds, set on it.
 384  *
 385  * @see elm_spinner_interval_set() for more details.
 386  *
 387  * @ingroup Spinner
 388  */
 389 EAPI double      elm_spinner_interval_get(const Evas_Object *obj);
 390
 391 /**
 392  * Set the base for rounding
 393  *
 394  * @param obj The spinner object
 395  * @param base The base value
 396  *
 397  * Rounding works as follows:
 398  *
 399  * rounded_val = base + (double)(((value - base) / round) * round)
 400  *
 401  * Where rounded_val, value and base are doubles, and round is an integer.
 402  *
 403  * This means that things will be rounded to increments (or decrements) of
 404  * "round" starting from value @p base. The default base for rounding is 0.
 405  *
 406  * Example: round = 3, base = 2
 407  * Values:  3, 6, 9, 12, 15, ...
 408  *
 409  * Example: round = 2, base = 5.5
 410  * Values: 5.5, 7.5, 9.5, 11.5, ...
 411  *
 412  * @see elm_spinner_round_get()
 413  * @see elm_spinner_base_get() too.
 414  *
 415  * @ingroup Spinner
 416  */
 417 EAPI void elm_spinner_base_set(Evas_Object *obj, double base);
 418
 419 /**
 420  * Get the base for rounding
 421  *
 422  * @param obj The spinner object
 423  * @return The base rounding value
 424  *
 425  * This returns the base for rounding.
 426  *
 427  * @see elm_spinner_round_set() too.
 428  * @see elm_spinner_base_set() too.
 429  *
 430  * @ingroup Spinner
 431  */
 432 EAPI double elm_spinner_base_get(const Evas_Object *obj);
 433
 434 /**
 435  * Set the round value for rounding
 436  *
 437  * @param obj The spinner object
 438  * @param rnd The rounding value
 439  *
 440  * Sets the rounding value used for value rounding in the spinner.
 441  *
 442  * @see elm_spinner_round_get()
 443  * @see elm_spinner_base_set()
 444  *
 445  * @ingroup Spinner
 446  */
 447 EAPI void elm_spinner_round_set(Evas_Object *obj, int rnd);
 448
 449 /**
 450  * Get the round value for rounding
 451  *
 452  * @param obj The spinner object
 453  * @return The rounding value
 454  *
 455  * This returns the round value for rounding.
 456  *
 457  * @see elm_spinner_round_set() too.
 458  * @see elm_spinner_base_set() too.
 459  *
 460  * @ingroup Spinner
 461  */
 462 EAPI int elm_spinner_round_get(const Evas_Object *obj);
 463
 464 /**
 465  * @}
 466  */