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