2 * @defgroup Spinner Spinner
5 * @image html img/widget/spinner/preview-00.png
6 * @image latex img/widget/spinner/preview-00.eps
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.
12 * By default the spinner will not wrap and has a label
13 * of "%.0f" (just showing the integer value of the double).
15 * A spinner has a label that is formatted with floating
16 * point values and thus accepts a printf-style format string, like
19 * It also allows specific values to be replaced by pre-defined labels.
21 * Smart callbacks one can register to:
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.
29 * Available styles for it:
31 * - @c "vertical": up/down buttons at the right side and text left aligned.
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
40 * Here is an example on its usage:
41 * @ref spinner_example
50 * Add a new spinner widget to the given parent Elementary
53 * @param parent The parent object.
54 * @return a new spinner widget handle or @c NULL, on errors.
56 * This function inserts a new spinner widget on the canvas.
61 EAPI Evas_Object *elm_spinner_add(Evas_Object *parent);
64 * Set the format string of the displayed label.
66 * @param obj The spinner object.
67 * @param fmt The format string for the label display.
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.
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.
79 * @see elm_spinner_label_format_get()
83 EAPI void elm_spinner_label_format_set(Evas_Object *obj, const char *fmt);
86 * Get the label format of the spinner.
88 * @param obj The spinner object.
89 * @return The text label format string in UTF-8.
91 * @see elm_spinner_label_format_set() for details.
95 EAPI const char *elm_spinner_label_format_get(const Evas_Object *obj);
98 * Set the minimum and maximum values for the spinner.
100 * @param obj The spinner object.
101 * @param min The minimum value.
102 * @param max The maximum value.
104 * Define the allowed range of values to be selected by the user.
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().
110 * By default, min is equal to 0, and max is equal to 100.
112 * @warning Maximum must be greater than minimum.
114 * @see elm_spinner_min_max_get()
118 EAPI void elm_spinner_min_max_set(Evas_Object *obj, double min, double max);
121 * Get the minimum and maximum values of the spinner.
123 * @param obj The spinner object.
125 * @param min Pointer where to store the minimum value.
126 * @param max Pointer where to store the maximum value.
128 * @param min Pointer to store the minimum value.
129 * @param max Pointer to store the maximum value.
130 >>>>>>> remotes/origin/upstream
132 * @note If only one value is needed, the other pointer can be passed
135 * @see elm_spinner_min_max_set() for details.
139 EAPI void elm_spinner_min_max_get(const Evas_Object *obj, double *min, double *max);
142 * Set the step used to increment or decrement the spinner value.
144 * @param obj The spinner object.
145 * @param step The step value.
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.
151 * The interval to increment / decrement can be set with
152 * elm_spinner_interval_set().
154 * By default step value is equal to 1.
156 * @see elm_spinner_step_get()
160 EAPI void elm_spinner_step_set(Evas_Object *obj, double step);
163 * Get the step used to increment or decrement the spinner value.
165 * @param obj The spinner object.
166 * @return The step value.
168 * @see elm_spinner_step_get() for more details.
172 EAPI double elm_spinner_step_get(const Evas_Object *obj);
175 * Set the value the spinner displays.
177 * @param obj The spinner object.
178 * @param val The value to be displayed.
180 * Value will be presented on the label following format specified with
181 * elm_spinner_format_set().
183 * @warning The value must to be between min and max values. This values
184 * are set by elm_spinner_min_max_set().
186 * @see elm_spinner_value_get().
187 * @see elm_spinner_format_set().
188 * @see elm_spinner_min_max_set().
192 EAPI void elm_spinner_value_set(Evas_Object *obj, double val);
195 * Get the value displayed by the spinner.
197 * @param obj The spinner object.
198 * @return The value displayed.
200 * @see elm_spinner_value_set() for details.
204 EAPI double elm_spinner_value_get(const Evas_Object *obj);
207 * Set whether the spinner should wrap when it reaches its
208 * minimum or maximum value.
210 * @param obj The spinner object.
211 * @param wrap @c EINA_TRUE to enable wrap or @c EINA_FALSE to
214 * Disabled by default. If disabled, when the user tries to increment the
216 * but displayed value plus step value is bigger than maximum value,
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.
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
229 * @li step value = 20
230 * @li displayed value = 20
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.
236 * @see elm_spinner_wrap_get().
240 EAPI void elm_spinner_wrap_set(Evas_Object *obj, Eina_Bool wrap);
243 * Get whether the spinner should wrap when it reaches its
244 * minimum or maximum value.
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.
250 * @see elm_spinner_wrap_set() for details.
254 EAPI Eina_Bool elm_spinner_wrap_get(const Evas_Object *obj);
257 * Set whether the spinner can be directly edited by the user or not.
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.
263 * Spinner objects can have edition @b disabled, in which state they will
264 * be changed only by arrows.
265 * Useful for contexts
267 * where you don't want your users to interact with it writting the value.
269 * where you don't want your users to interact with it writing the value.
270 >>>>>>> remotes/origin/upstream
272 * when using special values, the user can see real value instead
273 * of special label on edition.
275 * It's enabled by default.
277 * @see elm_spinner_editable_get()
281 EAPI void elm_spinner_editable_set(Evas_Object *obj, Eina_Bool editable);
284 * Get whether the spinner can be directly edited by the user or not.
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.
290 * @see elm_spinner_editable_set() for details.
294 EAPI Eina_Bool elm_spinner_editable_get(const Evas_Object *obj);
297 * Set a special string to display in the place of the numerical value.
299 * @param obj The spinner object.
300 * @param value The value to be replaced.
301 * @param label The label to be used.
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.
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);
318 EAPI void elm_spinner_special_value_add(Evas_Object *obj, double value, const char *label);
321 * Set the interval on time updates for an user mouse button hold
322 * on spinner widgets' arrows.
324 * @param obj The spinner object.
325 * @param interval The (first) interval value in seconds.
327 * This interval value is @b decreased while the user holds the
328 * mouse pointer either incrementing or decrementing spinner's value.
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.
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.
338 * The default starting interval value for automatic changes is
341 * @see elm_spinner_interval_get()
345 EAPI void elm_spinner_interval_set(Evas_Object *obj, double interval);
348 * Get the interval on time updates for an user mouse button hold
349 * on spinner widgets' arrows.
351 * @param obj The spinner object.
352 * @return The (first) interval value, in seconds, set on it.
354 * @see elm_spinner_interval_set() for more details.
358 EAPI double elm_spinner_interval_get(const Evas_Object *obj);
363 * Set the base for rounding
365 * @param obj The spinner object
366 * @param base The base value
368 * Rounding works as follows:
370 * rounded_val = base + (double)(((value - base) / round) * round)
372 * Where rounded_val, value and base are doubles, and round is an integer.
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.
377 * Example: round = 3, base = 2
378 * Values: 3, 6, 9, 12, 15, ...
380 * Example: round = 2, base = 5.5
381 * Values: 5.5, 7.5, 9.5, 11.5, ...
383 * @see elm_spinner_round_get()
384 * @see elm_spinner_base_get() too.
388 EAPI void elm_spinner_base_set(Evas_Object *obj, double base);
391 * Get the base for rounding
393 * @param obj The spinner object
394 * @return The base rounding value
396 * This returns the base for rounding.
398 * @see elm_spinner_round_set() too.
399 * @see elm_spinner_base_set() too.
403 EAPI double elm_spinner_base_get(const Evas_Object *obj);
406 * Set the round value for rounding
408 * @param obj The spinner object
409 * @param rnd The rounding value
411 * Sets the rounding value used for value rounding in the spinner.
413 * @see elm_spinner_round_get()
414 * @see elm_spinner_base_set()
418 EAPI void elm_spinner_round_set(Evas_Object *obj, int rnd);
421 * Get the round value for rounding
423 * @param obj The spinner object
424 * @return The rounding value
426 * This returns the round value for rounding.
428 * @see elm_spinner_round_set() too.
429 * @see elm_spinner_base_set() too.
433 EAPI int elm_spinner_round_get(const Evas_Object *obj);
436 >>>>>>> remotes/origin/upstream