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 <<<<<<< HEAD
 125  * @param min Pointer where to store the minimum value.
 126  * @param max Pointer where to store the maximum value.
 127 =======
 128  * @param min Pointer to store the minimum value.
 129  * @param max Pointer to store the maximum value.
 130 >>>>>>> remotes/origin/upstream
 131  *
 132  * @note If only one value is needed, the other pointer can be passed
 133  * as @c NULL.
 134  *
 135  * @see elm_spinner_min_max_set() for details.
 136  *
 137  * @ingroup Spinner
 138  */
 139 EAPI void        elm_spinner_min_max_get(const Evas_Object *obj, double *min, double *max);
 140
 141 /**
 142  * Set the step used to increment or decrement the spinner value.
 143  *
 144  * @param obj The spinner object.
 145  * @param step The step value.
 146  *
 147  * This value will be incremented or decremented to the displayed value.
 148  * It will be incremented while the user keep right or top arrow pressed,
 149  * and will be decremented while the user keep left or bottom arrow pressed.
 150  *
 151  * The interval to increment / decrement can be set with
 152  * elm_spinner_interval_set().
 153  *
 154  * By default step value is equal to 1.
 155  *
 156  * @see elm_spinner_step_get()
 157  *
 158  * @ingroup Spinner
 159  */
 160 EAPI void        elm_spinner_step_set(Evas_Object *obj, double step);
 161
 162 /**
 163  * Get the step used to increment or decrement the spinner value.
 164  *
 165  * @param obj The spinner object.
 166  * @return The step value.
 167  *
 168  * @see elm_spinner_step_get() for more details.
 169  *
 170  * @ingroup Spinner
 171  */
 172 EAPI double      elm_spinner_step_get(const Evas_Object *obj);
 173
 174 /**
 175  * Set the value the spinner displays.
 176  *
 177  * @param obj The spinner object.
 178  * @param val The value to be displayed.
 179  *
 180  * Value will be presented on the label following format specified with
 181  * elm_spinner_format_set().
 182  *
 183  * @warning The value must to be between min and max values. This values
 184  * are set by elm_spinner_min_max_set().
 185  *
 186  * @see elm_spinner_value_get().
 187  * @see elm_spinner_format_set().
 188  * @see elm_spinner_min_max_set().
 189  *
 190  * @ingroup Spinner
 191  */
 192 EAPI void        elm_spinner_value_set(Evas_Object *obj, double val);
 193
 194 /**
 195  * Get the value displayed by the spinner.
 196  *
 197  * @param obj The spinner object.
 198  * @return The value displayed.
 199  *
 200  * @see elm_spinner_value_set() for details.
 201  *
 202  * @ingroup Spinner
 203  */
 204 EAPI double      elm_spinner_value_get(const Evas_Object *obj);
 205
 206 /**
 207  * Set whether the spinner should wrap when it reaches its
 208  * minimum or maximum value.
 209  *
 210  * @param obj The spinner object.
 211  * @param wrap @c EINA_TRUE to enable wrap or @c EINA_FALSE to
 212  * disable it.
 213  *
 214  * Disabled by default. If disabled, when the user tries to increment the
 215  * value,
 216  * but displayed value plus step value is bigger than maximum value,
 217  * the spinner
 218  * won't allow it. The same happens when the user tries to decrement it,
 219  * but the value less step is less than minimum value.
 220  *
 221  * When wrap is enabled, in such situations it will allow these changes,
 222  * but will get the value that would be less than minimum and subtracts
 223  * from maximum. Or add the value that would be more than maximum to
 224  * the minimum.
 225  *
 226  * E.g.:
 227  * @li min value = 10
 228  * @li max value = 50
 229  * @li step value = 20
 230  * @li displayed value = 20
 231  *
 232  * When the user decrement value (using left or bottom arrow), it will
 233  * displays @c 40, because max - (min - (displayed - step)) is
 234  * @c 50 - (@c 10 - (@c 20 - @c 20)) = @c 40.
 235  *
 236  * @see elm_spinner_wrap_get().
 237  *
 238  * @ingroup Spinner
 239  */
 240 EAPI void        elm_spinner_wrap_set(Evas_Object *obj, Eina_Bool wrap);
 241
 242 /**
 243  * Get whether the spinner should wrap when it reaches its
 244  * minimum or maximum value.
 245  *
 246  * @param obj The spinner object
 247  * @return @c EINA_TRUE means wrap is enabled. @c EINA_FALSE indicates
 248  * it's disabled. If @p obj is @c NULL, @c EINA_FALSE is returned.
 249  *
 250  * @see elm_spinner_wrap_set() for details.
 251  *
 252  * @ingroup Spinner
 253  */
 254 EAPI Eina_Bool   elm_spinner_wrap_get(const Evas_Object *obj);
 255
 256 /**
 257  * Set whether the spinner can be directly edited by the user or not.
 258  *
 259  * @param obj The spinner object.
 260  * @param editable @c EINA_TRUE to allow users to edit it or @c EINA_FALSE to
 261  * don't allow users to edit it directly.
 262  *
 263  * Spinner objects can have edition @b disabled, in which state they will
 264  * be changed only by arrows.
 265  * Useful for contexts
 266 <<<<<<< HEAD
 267  * where you don't want your users to interact with it writting the value.
 268 =======
 269  * where you don't want your users to interact with it writing the value.
 270 >>>>>>> remotes/origin/upstream
 271  * Specially
 272  * when using special values, the user can see real value instead
 273  * of special label on edition.
 274  *
 275  * It's enabled by default.
 276  *
 277  * @see elm_spinner_editable_get()
 278  *
 279  * @ingroup Spinner
 280  */
 281 EAPI void        elm_spinner_editable_set(Evas_Object *obj, Eina_Bool editable);
 282
 283 /**
 284  * Get whether the spinner can be directly edited by the user or not.
 285  *
 286  * @param obj The spinner object.
 287  * @return @c EINA_TRUE means edition is enabled. @c EINA_FALSE indicates
 288  * it's disabled. If @p obj is @c NULL, @c EINA_FALSE is returned.
 289  *
 290  * @see elm_spinner_editable_set() for details.
 291  *
 292  * @ingroup Spinner
 293  */
 294 EAPI Eina_Bool   elm_spinner_editable_get(const Evas_Object *obj);
 295
 296 /**
 297  * Set a special string to display in the place of the numerical value.
 298  *
 299  * @param obj The spinner object.
 300  * @param value The value to be replaced.
 301  * @param label The label to be used.
 302  *
 303  * It's useful for cases when a user should select an item that is
 304  * better indicated by a label than a value. For example, weekdays or months.
 305  *
 306  * E.g.:
 307  * @code
 308  * sp = elm_spinner_add(win);
 309  * elm_spinner_min_max_set(sp, 1, 3);
 310  * elm_spinner_special_value_add(sp, 1, "January");
 311  * elm_spinner_special_value_add(sp, 2, "February");
 312  * elm_spinner_special_value_add(sp, 3, "March");
 313  * evas_object_show(sp);
 314  * @endcode
 315  *
 316  * @ingroup Spinner
 317  */
 318 EAPI void        elm_spinner_special_value_add(Evas_Object *obj, double value, const char *label);
 319
 320 /**
 321  * Set the interval on time updates for an user mouse button hold
 322  * on spinner widgets' arrows.
 323  *
 324  * @param obj The spinner object.
 325  * @param interval The (first) interval value in seconds.
 326  *
 327  * This interval value is @b decreased while the user holds the
 328  * mouse pointer either incrementing or decrementing spinner's value.
 329  *
 330  * This helps the user to get to a given value distant from the
 331  * current one easier/faster, as it will start to change quicker and
 332  * quicker on mouse button holds.
 333  *
 334  * The calculation for the next change interval value, starting from
 335  * the one set with this call, is the previous interval divided by
 336  * @c 1.05, so it decreases a little bit.
 337  *
 338  * The default starting interval value for automatic changes is
 339  * @c 0.85 seconds.
 340  *
 341  * @see elm_spinner_interval_get()
 342  *
 343  * @ingroup Spinner
 344  */
 345 EAPI void        elm_spinner_interval_set(Evas_Object *obj, double interval);
 346
 347 /**
 348  * Get the interval on time updates for an user mouse button hold
 349  * on spinner widgets' arrows.
 350  *
 351  * @param obj The spinner object.
 352  * @return The (first) interval value, in seconds, set on it.
 353  *
 354  * @see elm_spinner_interval_set() for more details.
 355  *
 356  * @ingroup Spinner
 357  */
 358 EAPI double      elm_spinner_interval_get(const Evas_Object *obj);
 359
 360 /**
 361 <<<<<<< HEAD
 362 =======
 363  * Set the base for rounding
 364  *
 365  * @param obj The spinner object
 366  * @param base The base value
 367  *
 368  * Rounding works as follows:
 369  *
 370  * rounded_val = base + (double)(((value - base) / round) * round)
 371  *
 372  * Where rounded_val, value and base are doubles, and round is an integer.
 373  *
 374  * This means that things will be rounded to increments (or decrements) of
 375  * "round" starting from value @p base. The default base for rounding is 0.
 376  *
 377  * Example: round = 3, base = 2
 378  * Values:  3, 6, 9, 12, 15, ...
 379  *
 380  * Example: round = 2, base = 5.5
 381  * Values: 5.5, 7.5, 9.5, 11.5, ...
 382  *
 383  * @see elm_spinner_round_get()
 384  * @see elm_spinner_base_get() too.
 385  *
 386  * @ingroup Spinner
 387  */
 388 EAPI void elm_spinner_base_set(Evas_Object *obj, double base);
 389
 390 /**
 391  * Get the base for rounding
 392  *
 393  * @param obj The spinner object
 394  * @return The base rounding value
 395  *
 396  * This returns the base for rounding.
 397  *
 398  * @see elm_spinner_round_set() too.
 399  * @see elm_spinner_base_set() too.
 400  *
 401  * @ingroup Spinner
 402  */
 403 EAPI double elm_spinner_base_get(const Evas_Object *obj);
 404
 405 /**
 406  * Set the round value for rounding
 407  *
 408  * @param obj The spinner object
 409  * @param rnd The rounding value
 410  *
 411  * Sets the rounding value used for value rounding in the spinner.
 412  *
 413  * @see elm_spinner_round_get()
 414  * @see elm_spinner_base_set()
 415  *
 416  * @ingroup Spinner
 417  */
 418 EAPI void elm_spinner_round_set(Evas_Object *obj, int rnd);
 419
 420 /**
 421  * Get the round value for rounding
 422  *
 423  * @param obj The spinner object
 424  * @return The rounding value
 425  *
 426  * This returns the round value for rounding.
 427  *
 428  * @see elm_spinner_round_set() too.
 429  * @see elm_spinner_base_set() too.
 430  *
 431  * @ingroup Spinner
 432  */
 433 EAPI int elm_spinner_round_get(const Evas_Object *obj);
 434
 435 /**
 436 >>>>>>> remotes/origin/upstream
 437  * @}
 438  */