From 569b78f24326d510894484e9854679cc4f36f419 Mon Sep 17 00:00:00 2001 From: Bruno Dilly Date: Tue, 26 Jul 2011 17:27:05 +0000 Subject: [PATCH] Elementary: Spinner documentation SVN revision: 61766 --- legacy/elementary/doc/Makefile.am | 1 + legacy/elementary/doc/examples.dox | 75 ++++ legacy/elementary/doc/index.doxy | 3 + legacy/elementary/doc/widgets/Makefile.am | 2 + .../doc/widgets/widget_preview_spinner.c | 8 + legacy/elementary/src/examples/Makefile.am | 3 + .../elementary/src/examples/spinner_example.c | 135 +++++++ legacy/elementary/src/lib/Elementary.h.in | 367 ++++++++++++++++-- legacy/elementary/src/lib/elm_spinner.c | 168 +------- 9 files changed, 572 insertions(+), 190 deletions(-) create mode 100644 legacy/elementary/doc/widgets/widget_preview_spinner.c create mode 100644 legacy/elementary/src/examples/spinner_example.c diff --git a/legacy/elementary/doc/Makefile.am b/legacy/elementary/doc/Makefile.am index b8188b2aff..68af786f69 100644 --- a/legacy/elementary/doc/Makefile.am +++ b/legacy/elementary/doc/Makefile.am @@ -20,6 +20,7 @@ WGT_PREVIEW = \ check:preview-00.png:widget_preview_check1:160:50 \ check:preview-01.png:widget_preview_check2:160:50 \ check:preview-02.png:widget_preview_check3:160:50 \ + spinner:preview-00.png:widget_preview_spinner:160:30 \ bubble:preview-00.png:widget_preview_bubble1:160:50 \ bubble:preview-01.png:widget_preview_bubble2:160:50 \ bubble:preview-02.png:widget_preview_bubble3:160:50 \ diff --git a/legacy/elementary/doc/examples.dox b/legacy/elementary/doc/examples.dox index c86d97ef9a..c88385f9e4 100644 --- a/legacy/elementary/doc/examples.dox +++ b/legacy/elementary/doc/examples.dox @@ -31,6 +31,8 @@ * * @ref calendar_example_06 * + * @ref spinner_example + * * @ref clock_example * * @ref diskselector_example_01 @@ -1399,6 +1401,79 @@ * @example calendar_example_06.c */ +/** + * @page spinner_example Spinner widget example + * + * This code places seven Elementary spinner widgets on a window, each of + * them exemplifying a part of the widget's API. + * + * The first of them is the default spinner: + * @dontinclude spinner_example.c + * @skipline elm_spinner_add + * @until evas_object_show + * As you see, the defaults for a spinner are: + * @li no wrap + * @li min value set to 0 + * @li max value set to 100 + * @li step value set to 1 + * @li label format set to "%0.f" + * + * If another format is required, see the second spinner. It will put a text + * before and after the value, and also format value to display two decimals: + * @skipline format_set + * + * The third one will use a customized step, define new minimum and maximum + * values and enable wrap, so when value reaches minimum it jumps to maximum, + * or jumps to minimum after maximum value is reached. Format is set to display + * a decimal: + * @skipline elm_spinner_add + * @until evas_object_show + * + * The fourth uses @c vertical style, so instead of left and right arrows, + * top and bottom are displayed. Also the change interval is reduced, so + * user can change value faster. + * @skipline style + * @skipline interval + * + * In the fifth the user won't be allowed to set value directly, i.e., will + * be obligate change value only using arrows: + * @skipline editable + * + * The sixth widget will receive a lot of special values, so + * instead of reading numeric values, user will see labels for each one. + * Also direct edition is disabled, otherwise users would see the numeric + * value on edition mode. User will be able to select a month in this widget: + * @skipline elm_spinner_add + * @until evas_object_show + * + * Finally the last widget will exemplify how to listen to widget's signals, + * changed and delay,changed . First we need to + * implement callback functions that will simply print spinner's value: + * @dontinclude spinner_example.c + * @skip static + * @skip } + * @skipline static + * @until } + * @until } + * + * The first callback function should be called everytime value changes, + * the second one only after user stops to increment or decrement. Try + * to keep arrows pressed and check the difference. + * @skip smart_callback + * @skipline smart_callback + * @skipline smart_callback + * + * See the full @ref spinner_example.c "example", whose window should + * look like this picture: + * + * @image html screenshots/spinner_example.png + * @image latex screenshots/spinner_example.eps width=\textwidth + * + * See the full @ref spinner_example_c "source code" for this example. + * + * @example spinner_example.c + */ + /** * @page clock_example Clock widget example * diff --git a/legacy/elementary/doc/index.doxy b/legacy/elementary/doc/index.doxy index 83389a3db3..a277149889 100644 --- a/legacy/elementary/doc/index.doxy +++ b/legacy/elementary/doc/index.doxy @@ -162,6 +162,9 @@ * @li @ref Slider * @li @ref Slideshow * @li @ref Spinner + * + * @image html img/widget/spinner/preview-00.png + * @image latex img/widget/spinner/preview-00.eps * @li @ref Thumb * @li @ref Toggle * diff --git a/legacy/elementary/doc/widgets/Makefile.am b/legacy/elementary/doc/widgets/Makefile.am index 1535244412..e67e20b30d 100644 --- a/legacy/elementary/doc/widgets/Makefile.am +++ b/legacy/elementary/doc/widgets/Makefile.am @@ -31,6 +31,7 @@ widget_preview_button3 \ widget_preview_check1 \ widget_preview_check2 \ widget_preview_check3 \ +widget_preview_spinner \ widget_preview_bubble1 \ widget_preview_bubble2 \ widget_preview_bubble3 \ @@ -90,6 +91,7 @@ EXTRA_DIST = \ widget_preview_check1.c \ widget_preview_check2.c \ widget_preview_check3.c \ + widget_preview_spinner.c \ widget_preview_clock.c \ widget_preview_colorselector.c \ widget_preview_conformant.c \ diff --git a/legacy/elementary/doc/widgets/widget_preview_spinner.c b/legacy/elementary/doc/widgets/widget_preview_spinner.c new file mode 100644 index 0000000000..4c6d4afc93 --- /dev/null +++ b/legacy/elementary/doc/widgets/widget_preview_spinner.c @@ -0,0 +1,8 @@ +#include "widget_preview_tmpl_head.c" + +Evas_Object *o = elm_spinner_add(win); +evas_object_size_hint_weight_set(o, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND); +elm_win_resize_object_add(win, o); +evas_object_show(o); + +#include "widget_preview_tmpl_foot.c" diff --git a/legacy/elementary/src/examples/Makefile.am b/legacy/elementary/src/examples/Makefile.am index 63336f8aaf..adfc09450a 100644 --- a/legacy/elementary/src/examples/Makefile.am +++ b/legacy/elementary/src/examples/Makefile.am @@ -58,6 +58,7 @@ SRCS = \ calendar_example_04.c \ calendar_example_05.c \ calendar_example_06.c \ + spinner_example.c \ clock_example.c \ conformant_example_01.c \ conformant_example_02.c \ @@ -134,6 +135,7 @@ pkglib_PROGRAMS += \ calendar_example_04 \ calendar_example_05 \ calendar_example_06 \ + spinner_example \ clock_example \ conformant_example_01 \ conformant_example_02 \ @@ -189,6 +191,7 @@ SCREENSHOTS = \ calendar_example_04:calendar_example_04.png:0.0 \ calendar_example_05:calendar_example_05.png:0.0 \ calendar_example_06:calendar_example_06.png:0.0 \ + spinner_example:spinner_example.png:0.0 \ clock_example:clock_example.png:0.5 \ image_example_01:image_example_01.png:0.0 \ diskselector_example_01:diskselector_example_01.png:0.2 \ diff --git a/legacy/elementary/src/examples/spinner_example.c b/legacy/elementary/src/examples/spinner_example.c new file mode 100644 index 0000000000..10dcf9d5db --- /dev/null +++ b/legacy/elementary/src/examples/spinner_example.c @@ -0,0 +1,135 @@ +/** + * Simple Elementary's spinner widget example, illustrating its + * usage and API. + * + * See stdout/stderr for output. Compile with: + * + * @verbatim + * gcc -g `pkg-config --cflags --libs elementary` spinner_example.c -o spinner_example + * @endverbatim + */ + +#include +#ifdef HAVE_CONFIG_H +# include "elementary_config.h" +#else +# define __UNUSED__ +#endif + +static void +_on_done(void *data __UNUSED__, + Evas_Object *obj __UNUSED__, + void *event_info __UNUSED__) +{ + elm_exit(); +} + +static void +_changed_cb(void *data __UNUSED__, Evas_Object *obj, void *event_info __UNUSED__) +{ + printf("Value changed to %0.f\n", elm_spinner_value_get(obj)); +} + +static void +_delay_changed_cb(void *data __UNUSED__, Evas_Object *obj, void *event_info __UNUSED__) +{ + printf("Value delay changed to %0.f\n", elm_spinner_value_get(obj)); +} + +int +elm_main(int argc __UNUSED__, char **argv __UNUSED__) +{ + Evas_Object *win, *bg, *bx, *sp; + + win = elm_win_add(NULL, "spinner", ELM_WIN_BASIC); + elm_win_title_set(win, "Spinner Example"); + evas_object_smart_callback_add(win, "delete,request", _on_done, NULL); + + bg = elm_bg_add(win); + elm_win_resize_object_add(win, bg); + evas_object_size_hint_weight_set(bg, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND); + evas_object_show(bg); + + bx = elm_box_add(win); + evas_object_size_hint_weight_set(bx, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND); + elm_win_resize_object_add(win, bx); + evas_object_show(bx); + + /* default */ + sp = elm_spinner_add(win); + evas_object_size_hint_align_set(sp, EVAS_HINT_FILL, 0.5); + evas_object_size_hint_weight_set(sp, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND); + elm_box_pack_end(bx, sp); + evas_object_show(sp); + + /* format */ + sp = elm_spinner_add(win); + elm_spinner_label_format_set(sp, "Percentage %%%1.2f something"); + evas_object_size_hint_align_set(sp, EVAS_HINT_FILL, 0.5); + evas_object_size_hint_weight_set(sp, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND); + elm_box_pack_end(bx, sp); + evas_object_show(sp); + + /* min max, step and wrap */ + sp = elm_spinner_add(win); + elm_spinner_label_format_set(sp, "%1.1f units"); + elm_spinner_step_set(sp, 1.5); + elm_spinner_wrap_set(sp, EINA_TRUE); + elm_spinner_min_max_set(sp, -50.0, 250.0); + evas_object_size_hint_align_set(sp, EVAS_HINT_FILL, 0.5); + evas_object_size_hint_weight_set(sp, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND); + elm_box_pack_end(bx, sp); + evas_object_show(sp); + + /* vertical */ + sp = elm_spinner_add(win); + elm_object_style_set(sp, "vertical"); + elm_spinner_interval_set(sp, 0.2); + evas_object_size_hint_align_set(sp, EVAS_HINT_FILL, 0.5); + evas_object_size_hint_weight_set(sp, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND); + elm_box_pack_end(bx, sp); + evas_object_show(sp); + + /* disabled edition */ + sp = elm_spinner_add(win); + elm_spinner_editable_set(sp, EINA_FALSE); + evas_object_size_hint_align_set(sp, EVAS_HINT_FILL, 0.5); + evas_object_size_hint_weight_set(sp, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND); + elm_box_pack_end(bx, sp); + evas_object_show(sp); + + /* special values */ + sp = elm_spinner_add(win); + elm_spinner_editable_set(sp, EINA_FALSE); + elm_spinner_min_max_set(sp, 1, 12); + elm_spinner_special_value_add(sp, 1, "January"); + elm_spinner_special_value_add(sp, 2, "February"); + elm_spinner_special_value_add(sp, 3, "March"); + elm_spinner_special_value_add(sp, 4, "April"); + elm_spinner_special_value_add(sp, 5, "May"); + elm_spinner_special_value_add(sp, 6, "June"); + elm_spinner_special_value_add(sp, 7, "July"); + elm_spinner_special_value_add(sp, 8, "August"); + elm_spinner_special_value_add(sp, 9, "September"); + elm_spinner_special_value_add(sp, 10, "October"); + elm_spinner_special_value_add(sp, 11, "November"); + elm_spinner_special_value_add(sp, 12, "December"); + evas_object_size_hint_align_set(sp, EVAS_HINT_FILL, 0.5); + evas_object_size_hint_weight_set(sp, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND); + elm_box_pack_end(bx, sp); + evas_object_show(sp); + + sp = elm_spinner_add(win); + evas_object_size_hint_align_set(sp, EVAS_HINT_FILL, 0.5); + evas_object_size_hint_weight_set(sp, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND); + elm_box_pack_end(bx, sp); + evas_object_show(sp); + evas_object_smart_callback_add(sp, "changed", _changed_cb, NULL); + evas_object_smart_callback_add(sp, "delay,changed", _delay_changed_cb, NULL); + + evas_object_show(win); + + elm_run(); + return 0; +} +ELM_MAIN() diff --git a/legacy/elementary/src/lib/Elementary.h.in b/legacy/elementary/src/lib/Elementary.h.in index 0036a82b35..0554e0d6eb 100644 --- a/legacy/elementary/src/lib/Elementary.h.in +++ b/legacy/elementary/src/lib/Elementary.h.in @@ -11706,30 +11706,351 @@ extern "C" { * @} */ - /* spinner */ - EAPI Evas_Object *elm_spinner_add(Evas_Object *parent) EINA_ARG_NONNULL(1); - EAPI void elm_spinner_label_format_set(Evas_Object *obj, const char *fmt) EINA_ARG_NONNULL(1); - EAPI const char *elm_spinner_label_format_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); - EAPI void elm_spinner_min_max_set(Evas_Object *obj, double min, double max) EINA_ARG_NONNULL(1); - EAPI void elm_spinner_min_max_get(const Evas_Object *obj, double *min, double *max) EINA_ARG_NONNULL(1); - EAPI void elm_spinner_step_set(Evas_Object *obj, double step) EINA_ARG_NONNULL(1); - EAPI double elm_spinner_step_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); - EAPI void elm_spinner_value_set(Evas_Object *obj, double val) EINA_ARG_NONNULL(1); - EAPI double elm_spinner_value_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); - EAPI void elm_spinner_wrap_set(Evas_Object *obj, Eina_Bool wrap) EINA_ARG_NONNULL(1); - EAPI Eina_Bool elm_spinner_wrap_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); - EAPI void elm_spinner_editable_set(Evas_Object *obj, Eina_Bool editable) EINA_ARG_NONNULL(1); - EAPI Eina_Bool elm_spinner_editable_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); - EAPI void elm_spinner_special_value_add(Evas_Object *obj, double value, const char *label) EINA_ARG_NONNULL(1); - EAPI void elm_spinner_interval_set(Evas_Object *obj, double interval) EINA_ARG_NONNULL(1); - EAPI double elm_spinner_interval_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); - /* smart callbacks called: - * "changed" - when the spinner value changes - * "delay,changed" - when the spinner value changed, but a small time after a change (use this if you only want to respond to a change once the spinner is held still for a short while). + /** + * @defgroup Spinner Spinner + * @ingroup Elementary + * + * @image html img/widget/spinner/preview-00.png + * @image latex img/widget/spinner/preview-00.eps + * + * A spinner is a widget which allows the user to increase or decrease + * numeric values using arrow buttons, or edit values directly, clicking + * over it and typing the new value. + * + * By default the spinner will not wrap and has a label + * of "%.0f" (just showing the integer value of the double). + * + * A spinner has a label that is formatted with floating + * point values and thus accepts a printf-style format string, like + * “%1.2f units”. + * + * It also allows specific values to be replaced by pre-defined labels. + * + * Smart callbacks one can register to: + * + * - "changed" - Whenever the spinner value is changed. + * - "delay,changed" - A short time after the value is changed by the user. + * This will be called only when the user stops dragging for a very short + * period or when they release their finger/mouse, so it avoids possibly + * expensive reactions to the value change. + * + * Available styles for it: + * - @c "default"; + * - @c "vertical": up/down buttons at the right side and text left aligned. + * + * Here is an example on its usage: + * @ref spinner_example */ - /* available item styles: - * default - * vertical (two up/down buttons at the right side and text left aligned) + + /** + * @addtogroup Spinner + * @{ + */ + + /** + * Add a new spinner widget to the given parent Elementary + * (container) object. + * + * @param parent The parent object. + * @return a new spinner widget handle or @c NULL, on errors. + * + * This function inserts a new spinner widget on the canvas. + * + * @ingroup Spinner + * + */ + EAPI Evas_Object *elm_spinner_add(Evas_Object *parent) EINA_ARG_NONNULL(1); + + /** + * Set the format string of the displayed label. + * + * @param obj The spinner object. + * @param fmt The format string for the label display. + * + * If @c NULL, this sets the format to "%.0f". If not it sets the format + * string for the label text. The label text is provided a floating point + * value, so the label text can display up to 1 floating point value. + * Note that this is optional. + * + * Use a format string such as "%1.2f meters" for example, and it will + * display values like: "3.14 meters" for a value equal to 3.14159. + * + * Default is "%0.f". + * + * @see elm_spinner_label_format_get() + * + * @ingroup Spinner + */ + EAPI void elm_spinner_label_format_set(Evas_Object *obj, const char *fmt) EINA_ARG_NONNULL(1); + + /** + * Get the label format of the spinner. + * + * @param obj The spinner object. + * @return The text label format string in UTF-8. + * + * @see elm_spinner_label_format_set() for details. + * + * @ingroup Spinner + */ + EAPI const char *elm_spinner_label_format_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); + + /** + * Set the minimum and maximum values for the spinner. + * + * @param obj The spinner object. + * @param min The minimum value. + * @param max The maximum value. + * + * Define the allowed range of values to be selected by the user. + * + * If actual value is less than @p min, it will be updated to @p min. If it + * is bigger then @p max, will be updated to @p max. Actual value can be + * get with elm_spinner_value_get(). + * + * By default, min is equal to 0, and max is equal to 100. + * + * @warning Maximum must be greater than minimum. + * + * @see elm_spinner_min_max_get() + * + * @ingroup Spinner + */ + EAPI void elm_spinner_min_max_set(Evas_Object *obj, double min, double max) EINA_ARG_NONNULL(1); + + /** + * Get the minimum and maximum values of the spinner. + * + * @param obj The spinner object. + * @param min Pointer where to store the minimum value. + * @param max Pointer where to store the maximum value. + * + * @note If only one value is needed, the other pointer can be passed + * as @c NULL. + * + * @see elm_spinner_min_max_set() for details. + * + * @ingroup Spinner + */ + EAPI void elm_spinner_min_max_get(const Evas_Object *obj, double *min, double *max) EINA_ARG_NONNULL(1); + + /** + * Set the step used to increment or decrement the spinner value. + * + * @param obj The spinner object. + * @param step The step value. + * + * This value will be incremented or decremented to the displayed value. + * It will be incremented while the user keep right or top arrow pressed, + * and will be decremented while the user keep left or bottom arrow pressed. + * + * The interval to increment / decrement can be set with + * elm_spinner_interval_set(). + * + * By default step value is equal to 1. + * + * @see elm_spinner_step_get() + * + * @ingroup Spinner + */ + EAPI void elm_spinner_step_set(Evas_Object *obj, double step) EINA_ARG_NONNULL(1); + + /** + * Get the step used to increment or decrement the spinner value. + * + * @param obj The spinner object. + * @return The step value. + * + * @see elm_spinner_step_get() for more details. + * + * @ingroup Spinner + */ + EAPI double elm_spinner_step_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); + + /** + * Set the value the spinner displays. + * + * @param obj The spinner object. + * @param val The value to be displayed. + * + * Value will be presented on the label following format specified with + * elm_spinner_format_set(). + * + * @warning The value must to be between min and max values. This values + * are set by elm_spinner_min_max_set(). + * + * @see elm_spinner_value_get(). + * @see elm_spinner_format_set(). + * @see elm_spinner_min_max_set(). + * + * @ingroup Spinner + */ + EAPI void elm_spinner_value_set(Evas_Object *obj, double val) EINA_ARG_NONNULL(1); + + /** + * Get the value displayed by the spinner. + * + * @param obj The spinner object. + * @return The value displayed. + * + * @see elm_spinner_value_set() for details. + * + * @ingroup Spinner + */ + EAPI double elm_spinner_value_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); + + /** + * Set whether the spinner should wrap when it reaches its + * minimum or maximum value. + * + * @param obj The spinner object. + * @param wrap @c EINA_TRUE to enable wrap or @c EINA_FALSE to + * disable it. + * + * Disabled by default. If disabled, when the user tries to increment the + * value, + * but displayed value plus step value is bigger than maximum value, + * the spinner + * won't allow it. The same happens when the user tries to decrement it, + * but the value less step is less than minimum value. + * + * When wrap is enabled, in such situations it will allow these changes, + * but will get the value that would be less than minimum and subtracts + * from maximum. Or add the value that would be more than maximum to + * the minimum. + * + * E.g.: + * @li min value = 10 + * @li max value = 50 + * @li step value = 20 + * @li displayed value = 20 + * + * When the user decrement value (using left or bottom arrow), it will + * displays @c 40, because max - (min - (displayed - step)) is + * @c 50 - (@c 10 - (@c 20 - @c 20)) = @c 40. + * + * @see elm_spinner_wrap_get(). + * + * @ingroup Spinner + */ + EAPI void elm_spinner_wrap_set(Evas_Object *obj, Eina_Bool wrap) EINA_ARG_NONNULL(1); + + /** + * Get whether the spinner should wrap when it reaches its + * minimum or maximum value. + * + * @param obj The spinner object + * @return @c EINA_TRUE means wrap is enabled. @c EINA_FALSE indicates + * it's disabled. If @p obj is @c NULL, @c EINA_FALSE is returned. + * + * @see elm_spinner_wrap_set() for details. + * + * @ingroup Spinner + */ + EAPI Eina_Bool elm_spinner_wrap_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); + + /** + * Set whether the spinner can be directly edited by the user or not. + * + * @param obj The spinner object. + * @param editable @c EINA_TRUE to allow users to edit it or @c EINA_FALSE to + * don't allow users to edit it directly. + * + * Spinner objects can have edition @b disabled, in which state they will + * be changed only by arrows. + * Useful for contexts + * where you don't want your users to interact with it writting the value. + * Specially + * when using special values, the user can see real value instead + * of special label on edition. + * + * It's enabled by default. + * + * @see elm_spinner_editable_get() + * + * @ingroup Spinner + */ + EAPI void elm_spinner_editable_set(Evas_Object *obj, Eina_Bool editable) EINA_ARG_NONNULL(1); + + /** + * Get whether the spinner can be directly edited by the user or not. + * + * @param obj The spinner object. + * @return @c EINA_TRUE means edition is enabled. @c EINA_FALSE indicates + * it's disabled. If @p obj is @c NULL, @c EINA_FALSE is returned. + * + * @see elm_spinner_editable_set() for details. + * + * @ingroup Spinner + */ + EAPI Eina_Bool elm_spinner_editable_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); + + /** + * Set a special string to display in the place of the numerical value. + * + * @param obj The spinner object. + * @param value The value to be replaced. + * @param label The label to be used. + * + * It's useful for cases when a user should select an item that is + * better indicated by a label than a value. For example, weekdays or months. + * + * E.g.: + * @code + * sp = elm_spinner_add(win); + * elm_spinner_min_max_set(sp, 1, 3); + * elm_spinner_special_value_add(sp, 1, "January"); + * elm_spinner_special_value_add(sp, 2, "February"); + * elm_spinner_special_value_add(sp, 3, "March"); + * evas_object_show(sp); + * @endcode + * + * @ingroup Spinner + */ + EAPI void elm_spinner_special_value_add(Evas_Object *obj, double value, const char *label) EINA_ARG_NONNULL(1); + + /** + * Set the interval on time updates for an user mouse button hold + * on spinner widgets' arrows. + * + * @param obj The spinner object. + * @param interval The (first) interval value in seconds. + * + * This interval value is @b decreased while the user holds the + * mouse pointer either incrementing or decrementing spinner's value. + * + * This helps the user to get to a given value distant from the + * current one easier/faster, as it will start to change quicker and + * quicker on mouse button holds. + * + * The calculation for the next change interval value, starting from + * the one set with this call, is the previous interval divided by + * @c 1.05, so it decreases a little bit. + * + * The default starting interval value for automatic changes is + * @c 0.85 seconds. + * + * @see elm_spinner_interval_get() + * + * @ingroup Spinner + */ + EAPI void elm_spinner_interval_set(Evas_Object *obj, double interval) EINA_ARG_NONNULL(1); + + /** + * Get the interval on time updates for an user mouse button hold + * on spinner widgets' arrows. + * + * @param obj The spinner object. + * @return The (first) interval value, in seconds, set on it. + * + * @see elm_spinner_interval_set() for more details. + * + * @ingroup Spinner + */ + EAPI double elm_spinner_interval_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); + + /** + * @} */ /** diff --git a/legacy/elementary/src/lib/elm_spinner.c b/legacy/elementary/src/lib/elm_spinner.c index 87d1ceae48..5db909ddf3 100644 --- a/legacy/elementary/src/lib/elm_spinner.c +++ b/legacy/elementary/src/lib/elm_spinner.c @@ -2,25 +2,6 @@ #include "elm_priv.h" #include -/** - * @defgroup Spinner - * - * A spinner is a widget which allows the user to increase or decrease - * numeric values. By default the spinner will not wrap and has a label - * of "%.0f" (just showing the integer value of the double). - * - * A spinner has a label that is formatted with floating - * point values and thus accepts a printf-style format string, like - * “%1.2f units”. - * - * Signals that you can add callbacks for are: - * - * "changed" - Whenever the spinner value is changed by the user. - * "delay,changed" - A short time after the value is changed by the user. - * This will be called only when the user stops dragging for a very short - * period or when they release their finger/mouse, so it avoids possibly - * expensive reactions to the value change. - */ typedef struct _Widget_Data Widget_Data; typedef struct _Elm_Spinner_Special_Value Elm_Spinner_Special_Value; @@ -568,14 +549,6 @@ _event_hook(Evas_Object *obj, Evas_Object *src __UNUSED__, Evas_Callback_Type ty return EINA_FALSE; } -/** - * Add a new spinner to the parent - * - * @param parent The parent object - * @return The new object or NULL if it cannot be created - * - * @ingroup Spinner - */ EAPI Evas_Object * elm_spinner_add(Evas_Object *parent) { @@ -648,19 +621,6 @@ elm_spinner_add(Evas_Object *parent) return obj; } -/** - * Set the format string of the label area - * - * If NULL, this sets the format to "%.0f". If not it sets the format - * string for the label text. The label text is provided a floating point - * value, so the label text can display up to 1 floating point value. Note that - * this is optional. Use a format string such as "%1.2f meters" for example. - * - * @param obj The spinner object - * @param fmt The format string for the label display - * - * @ingroup Spinner - */ EAPI void elm_spinner_label_format_set(Evas_Object *obj, const char *fmt) { @@ -672,14 +632,6 @@ elm_spinner_label_format_set(Evas_Object *obj, const char *fmt) _sizing_eval(obj); } -/** - * Get the label format of the spinner - * - * @param obj The spinner object - * @return The text label format string in UTF-8 - * - * @ingroup Spinner - */ EAPI const char * elm_spinner_label_format_get(const Evas_Object *obj) { @@ -689,17 +641,6 @@ elm_spinner_label_format_get(const Evas_Object *obj) return wd->label; } -/** - * Set the minimum and maximum values for the spinner - * - * Maximum must be greater than minimum. - * - * @param obj The spinner object - * @param min The minimum value - * @param max The maximum value - * - * @ingroup Spinner - */ EAPI void elm_spinner_min_max_set(Evas_Object *obj, double min, double max) { @@ -715,15 +656,6 @@ elm_spinner_min_max_set(Evas_Object *obj, double min, double max) _write_label(obj); } -/** - * Get the minimum and maximum values of the spinner - * - * @param obj The spinner object - * @param min The minimum value - * @param max The maximum value - * - * @ingroup Spinner - */ EAPI void elm_spinner_min_max_get(const Evas_Object *obj, double *min, double *max) { @@ -736,14 +668,6 @@ elm_spinner_min_max_get(const Evas_Object *obj, double *min, double *max) if (max) *max = wd->val_max; } -/** - * Set the step for the spinner - * - * @param obj The spinner object - * @param step The step value - * - * @ingroup Spinner - */ EAPI void elm_spinner_step_set(Evas_Object *obj, double step) { @@ -753,14 +677,6 @@ elm_spinner_step_set(Evas_Object *obj, double step) wd->step = step; } -/** - * Get the step of the spinner - * - * @param obj The spinner object - * @return The step value - * - * @ingroup Spinner - */ EAPI double elm_spinner_step_get(const Evas_Object *obj) { @@ -769,14 +685,7 @@ elm_spinner_step_get(const Evas_Object *obj) if (!wd) return 0.0; return wd->step; } -/** - * Set the value the spinner indicates - * - * @param obj The spinner object - * @param val The value (must be between min and max for the spinner) - * - * @ingroup Spinner - */ + EAPI void elm_spinner_value_set(Evas_Object *obj, double val) { @@ -791,14 +700,6 @@ elm_spinner_value_set(Evas_Object *obj, double val) _write_label(obj); } -/** - * Get the value the spinner has - * - * @param obj The spinner object - * @return The value of the spinner - * - * @ingroup Spinner - */ EAPI double elm_spinner_value_get(const Evas_Object *obj) { @@ -808,15 +709,6 @@ elm_spinner_value_get(const Evas_Object *obj) return wd->val; } -/** - * Sets whether the spinner should wrap when it reaches its - * minimum/maximum value - * - * @param obj The spinner object - * @param wrap True if it should wrap, false otherwise - * - * @ingroup Spinner - */ EAPI void elm_spinner_wrap_set(Evas_Object *obj, Eina_Bool wrap) { @@ -826,16 +718,6 @@ elm_spinner_wrap_set(Evas_Object *obj, Eina_Bool wrap) wd->wrap = wrap; } -/** - * Gets whether the spinner should wrap when it reaches its - * minimum/maximum value - * - * @param obj The spinner object - * @return Bool value of wrap option - * (0 = disabled, 1 = enabled) - * - * @ingroup Spinner - */ EAPI Eina_Bool elm_spinner_wrap_get(const Evas_Object *obj) { @@ -845,15 +727,6 @@ elm_spinner_wrap_get(const Evas_Object *obj) return wd->wrap; } -/** - * Set a special value to display in the place of the numerical one. - * - * @param obj The spinner object - * @param value The value to be replaced - * @param label The label to be used - * - * @ingroup Spinner - */ EAPI void elm_spinner_special_value_add(Evas_Object *obj, double value, const char *label) { @@ -871,14 +744,6 @@ elm_spinner_special_value_add(Evas_Object *obj, double value, const char *label) _write_label(obj); } -/** - * Set whether the spinner can be directly edited by the user or not. - * Default is editable. - * - * @param obj The spinner object - * @param editable Bool value of the edit option - * (EINA_FALSE = not editable, EINA_TRUE = editable) - */ EAPI void elm_spinner_editable_set(Evas_Object *obj, Eina_Bool editable) { @@ -888,13 +753,6 @@ elm_spinner_editable_set(Evas_Object *obj, Eina_Bool editable) wd->editable = editable; } -/** - * Gets whether the spinner is editable. - * - * @param obj The spinner object - * @return Bool value of edit option - * (EINA_FALSE = not editable, EINA_TRUE = editable) - */ EAPI Eina_Bool elm_spinner_editable_get(const Evas_Object *obj) { @@ -904,18 +762,6 @@ elm_spinner_editable_get(const Evas_Object *obj) return wd->editable; } -/** - * Set the interval for the spinner - * - * @param obj The spinner object - * @param interval The interval value in seconds - * - * The interval value is decreased while the user increments or decrements - * the spinner value. The next interval value is the previous interval / 1.05, - * so it speed up a bit. Default value is 0.85 seconds. - * - * @ingroup Spinner - */ EAPI void elm_spinner_interval_set(Evas_Object *obj, double interval) { @@ -925,18 +771,6 @@ elm_spinner_interval_set(Evas_Object *obj, double interval) wd->first_interval = interval; } -/** - * Get the interval of the spinner - * - * @param obj The spinner object - * @return The value of the first interval in seconds - * - * The interval value is decreased while the user increments or decrements - * the spinner value. The next interval value is the previous interval / 1.05, - * so it speed up a bit. Default value is 0.85 seconds. - * - * @ingroup Spinner - */ EAPI double elm_spinner_interval_get(const Evas_Object *obj) {