2 * @defgroup Spinner Spinner
5 * @image html spinner_inheritance_tree.png
6 * @image latex spinner_inheritance_tree.eps
8 * @image html img/widget/spinner/preview-00.png
9 * @image latex img/widget/spinner/preview-00.eps
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.
15 * By default the spinner will not wrap and has a label
16 * of "%.0f" (just showing the integer value of the double).
18 * A spinner has a label that is formatted with floating
19 * point values and thus accepts a printf-style format string, like
22 * It also allows specific values to be replaced by pre-defined labels.
24 * This widget inherits from the @ref Layout one, so that all the
25 * functions acting on it also work for spinner objects.
27 * This widget emits the following signals, besides the ones sent from
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.
35 * Available styles for it:
37 * - @c "vertical": up/down buttons at the right side and text left aligned.
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
46 * Here is an example on its usage:
47 * @ref spinner_example
56 * Add a new spinner widget to the given parent Elementary
59 * @param parent The parent object.
60 * @return a new spinner widget handle or @c NULL, on errors.
62 * This function inserts a new spinner widget on the canvas.
67 EAPI Evas_Object *elm_spinner_add(Evas_Object *parent);
70 * Set the format string of the displayed label.
72 * @param obj The spinner object.
73 * @param fmt The format string for the label display.
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.
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.
85 * @see elm_spinner_label_format_get()
89 EAPI void elm_spinner_label_format_set(Evas_Object *obj, const char *fmt);
92 * Get the label format of the spinner.
94 * @param obj The spinner object.
95 * @return The text label format string in UTF-8.
97 * @see elm_spinner_label_format_set() for details.
101 EAPI const char *elm_spinner_label_format_get(const Evas_Object *obj);
104 * Set the minimum and maximum values for the spinner.
106 * @param obj The spinner object.
107 * @param min The minimum value.
108 * @param max The maximum value.
110 * Define the allowed range of values to be selected by the user.
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().
116 * By default, min is equal to 0, and max is equal to 100.
118 * @warning Maximum must be greater than minimum.
120 * @see elm_spinner_min_max_get()
124 EAPI void elm_spinner_min_max_set(Evas_Object *obj, double min, double max);
127 * Get the minimum and maximum values of the spinner.
129 * @param obj The spinner object.
130 * @param min Pointer to store the minimum value.
131 * @param max Pointer to store the maximum value.
133 * @note If only one value is needed, the other pointer can be passed
136 * @see elm_spinner_min_max_set() for details.
140 EAPI void elm_spinner_min_max_get(const Evas_Object *obj, double *min, double *max);
143 * Set the step used to increment or decrement the spinner value.
145 * @param obj The spinner object.
146 * @param step The step value.
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.
152 * The interval to increment / decrement can be set with
153 * elm_spinner_interval_set().
155 * By default step value is equal to 1.
157 * @see elm_spinner_step_get()
161 EAPI void elm_spinner_step_set(Evas_Object *obj, double step);
164 * Get the step used to increment or decrement the spinner value.
166 * @param obj The spinner object.
167 * @return The step value.
169 * @see elm_spinner_step_get() for more details.
173 EAPI double elm_spinner_step_get(const Evas_Object *obj);
176 * Set the value the spinner displays.
178 * @param obj The spinner object.
179 * @param val The value to be displayed.
181 * Value will be presented on the label following format specified with
182 * elm_spinner_format_set().
184 * @warning The value must to be between min and max values. This values
185 * are set by elm_spinner_min_max_set().
187 * @see elm_spinner_value_get().
188 * @see elm_spinner_format_set().
189 * @see elm_spinner_min_max_set().
193 EAPI void elm_spinner_value_set(Evas_Object *obj, double val);
196 * Get the value displayed by the spinner.
198 * @param obj The spinner object.
199 * @return The value displayed.
201 * @see elm_spinner_value_set() for details.
205 EAPI double elm_spinner_value_get(const Evas_Object *obj);
208 * Set whether the spinner should wrap when it reaches its
209 * minimum or maximum value.
211 * @param obj The spinner object.
212 * @param wrap @c EINA_TRUE to enable wrap or @c EINA_FALSE to
215 * Disabled by default. If disabled, when the user tries to increment the
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.
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.
232 * @li step value = 20
233 * @li displayed value = 20
235 * When the user decrement value (using left or bottom arrow), it will
238 * @see elm_spinner_wrap_get().
242 EAPI void elm_spinner_wrap_set(Evas_Object *obj, Eina_Bool wrap);
245 * Get whether the spinner should wrap when it reaches its
246 * minimum or maximum value.
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.
252 * @see elm_spinner_wrap_set() for details.
256 EAPI Eina_Bool elm_spinner_wrap_get(const Evas_Object *obj);
259 * Set whether the spinner can be directly edited by the user or not.
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.
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.
270 * when using special values, the user can see real value instead
271 * of special label on edition.
273 * It's enabled by default.
275 * @see elm_spinner_editable_get()
279 EAPI void elm_spinner_editable_set(Evas_Object *obj, Eina_Bool editable);
282 * Get whether the spinner can be directly edited by the user or not.
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.
288 * @see elm_spinner_editable_set() for details.
292 EAPI Eina_Bool elm_spinner_editable_get(const Evas_Object *obj);
295 * Set a special string to display in the place of the numerical value.
297 * @param obj The spinner object.
298 * @param value The value to be replaced.
299 * @param label The label to be used.
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.
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);
314 * @note If another label was previously set to @p value, it will be replaced
317 * @see elm_spinner_special_value_get().
318 * @see elm_spinner_special_value_del().
322 EAPI void elm_spinner_special_value_add(Evas_Object *obj, double value, const char *label);
325 * Delete the special string display in the place of the numerical value.
327 * @param obj The spinner object.
328 * @param value The replaced value.
330 * It will remove a previously added special value. After this, the spinner
331 * will display the value itself instead of a label.
333 * @see elm_spinner_special_value_add() for more details.
338 EAPI void elm_spinner_special_value_del(Evas_Object *obj, double value);
341 * Get the special string display in the place of the numerical value.
343 * @param obj The spinner object.
344 * @param value The replaced value.
345 * @return The used label.
347 * @see elm_spinner_special_value_add() for more details.
352 EAPI const char *elm_spinner_special_value_get(Evas_Object *obj, double value);
355 * Set the interval on time updates for an user mouse button hold
356 * on spinner widgets' arrows.
358 * @param obj The spinner object.
359 * @param interval The (first) interval value in seconds.
361 * This interval value is @b decreased while the user holds the
362 * mouse pointer either incrementing or decrementing spinner's value.
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.
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.
372 * The default starting interval value for automatic changes is
375 * @see elm_spinner_interval_get()
379 EAPI void elm_spinner_interval_set(Evas_Object *obj, double interval);
382 * Get the interval on time updates for an user mouse button hold
383 * on spinner widgets' arrows.
385 * @param obj The spinner object.
386 * @return The (first) interval value, in seconds, set on it.
388 * @see elm_spinner_interval_set() for more details.
392 EAPI double elm_spinner_interval_get(const Evas_Object *obj);
395 * Set the base for rounding
397 * @param obj The spinner object
398 * @param base The base value
400 * Rounding works as follows:
402 * rounded_val = base + (double)(((value - base) / round) * round)
404 * Where rounded_val, value and base are doubles, and round is an integer.
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.
409 * Example: round = 3, base = 2
410 * Values: 3, 6, 9, 12, 15, ...
412 * Example: round = 2, base = 5.5
413 * Values: 5.5, 7.5, 9.5, 11.5, ...
415 * @see elm_spinner_round_get()
416 * @see elm_spinner_base_get() too.
420 EAPI void elm_spinner_base_set(Evas_Object *obj, double base);
423 * Get the base for rounding
425 * @param obj The spinner object
426 * @return The base rounding value
428 * This returns the base for rounding.
430 * @see elm_spinner_round_set() too.
431 * @see elm_spinner_base_set() too.
435 EAPI double elm_spinner_base_get(const Evas_Object *obj);
438 * Set the round value for rounding
440 * @param obj The spinner object
441 * @param rnd The rounding value
443 * Sets the rounding value used for value rounding in the spinner.
445 * @see elm_spinner_round_get()
446 * @see elm_spinner_base_set()
450 EAPI void elm_spinner_round_set(Evas_Object *obj, int rnd);
453 * Get the round value for rounding
455 * @param obj The spinner object
456 * @return The rounding value
458 * This returns the round value for rounding.
460 * @see elm_spinner_round_set() too.
461 * @see elm_spinner_base_set() too.
465 EAPI int elm_spinner_round_get(const Evas_Object *obj);