src/lib/elm_spinner.h

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