summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorBruno Dilly <bdilly@profusion.mobi>2011-07-26 17:27:05 +0000
committerBruno Dilly <bdilly@profusion.mobi>2011-07-26 17:27:05 +0000
commit80c5c810e8e926bfb9b05c37825cedcbe246a633 (patch)
tree9a46917e604abe64cd59a75b8c9ca1b85952161d
parent86244665aebe12881034b0e517cd4246871e2ef5 (diff)
Elementary: Spinner documentation
SVN revision: 61766
-rw-r--r--doc/Makefile.am1
-rw-r--r--doc/examples.dox75
-rw-r--r--doc/index.doxy3
-rw-r--r--doc/widgets/Makefile.am2
-rw-r--r--doc/widgets/widget_preview_spinner.c8
-rw-r--r--src/examples/Makefile.am3
-rw-r--r--src/examples/spinner_example.c135
-rw-r--r--src/lib/Elementary.h.in337
-rw-r--r--src/lib/elm_spinner.c168
9 files changed, 557 insertions, 175 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am
index b8188b2af..68af786f6 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -20,6 +20,7 @@ WGT_PREVIEW = \
20 check:preview-00.png:widget_preview_check1:160:50 \ 20 check:preview-00.png:widget_preview_check1:160:50 \
21 check:preview-01.png:widget_preview_check2:160:50 \ 21 check:preview-01.png:widget_preview_check2:160:50 \
22 check:preview-02.png:widget_preview_check3:160:50 \ 22 check:preview-02.png:widget_preview_check3:160:50 \
23 spinner:preview-00.png:widget_preview_spinner:160:30 \
23 bubble:preview-00.png:widget_preview_bubble1:160:50 \ 24 bubble:preview-00.png:widget_preview_bubble1:160:50 \
24 bubble:preview-01.png:widget_preview_bubble2:160:50 \ 25 bubble:preview-01.png:widget_preview_bubble2:160:50 \
25 bubble:preview-02.png:widget_preview_bubble3:160:50 \ 26 bubble:preview-02.png:widget_preview_bubble3:160:50 \
diff --git a/doc/examples.dox b/doc/examples.dox
index c86d97ef9..c88385f9e 100644
--- a/doc/examples.dox
+++ b/doc/examples.dox
@@ -31,6 +31,8 @@
31 * 31 *
32 * @ref calendar_example_06 32 * @ref calendar_example_06
33 * 33 *
34 * @ref spinner_example
35 *
34 * @ref clock_example 36 * @ref clock_example
35 * 37 *
36 * @ref diskselector_example_01 38 * @ref diskselector_example_01
@@ -1400,6 +1402,79 @@
1400 */ 1402 */
1401 1403
1402/** 1404/**
1405 * @page spinner_example Spinner widget example
1406 *
1407 * This code places seven Elementary spinner widgets on a window, each of
1408 * them exemplifying a part of the widget's API.
1409 *
1410 * The first of them is the default spinner:
1411 * @dontinclude spinner_example.c
1412 * @skipline elm_spinner_add
1413 * @until evas_object_show
1414 * As you see, the defaults for a spinner are:
1415 * @li no wrap
1416 * @li min value set to 0
1417 * @li max value set to 100
1418 * @li step value set to 1
1419 * @li label format set to "%0.f"
1420 *
1421 * If another format is required, see the second spinner. It will put a text
1422 * before and after the value, and also format value to display two decimals:
1423 * @skipline format_set
1424 *
1425 * The third one will use a customized step, define new minimum and maximum
1426 * values and enable wrap, so when value reaches minimum it jumps to maximum,
1427 * or jumps to minimum after maximum value is reached. Format is set to display
1428 * a decimal:
1429 * @skipline elm_spinner_add
1430 * @until evas_object_show
1431 *
1432 * The fourth uses @c vertical style, so instead of left and right arrows,
1433 * top and bottom are displayed. Also the change interval is reduced, so
1434 * user can change value faster.
1435 * @skipline style
1436 * @skipline interval
1437 *
1438 * In the fifth the user won't be allowed to set value directly, i.e., will
1439 * be obligate change value only using arrows:
1440 * @skipline editable
1441 *
1442 * The sixth widget will receive a lot of special values, so
1443 * instead of reading numeric values, user will see labels for each one.
1444 * Also direct edition is disabled, otherwise users would see the numeric
1445 * value on edition mode. User will be able to select a month in this widget:
1446 * @skipline elm_spinner_add
1447 * @until evas_object_show
1448 *
1449 * Finally the last widget will exemplify how to listen to widget's signals,
1450 * <tt> changed </tt> and <tt> delay,changed </tt>. First we need to
1451 * implement callback functions that will simply print spinner's value:
1452 * @dontinclude spinner_example.c
1453 * @skip static
1454 * @skip }
1455 * @skipline static
1456 * @until }
1457 * @until }
1458 *
1459 * The first callback function should be called everytime value changes,
1460 * the second one only after user stops to increment or decrement. Try
1461 * to keep arrows pressed and check the difference.
1462 * @skip smart_callback
1463 * @skipline smart_callback
1464 * @skipline smart_callback
1465 *
1466 * See the full @ref spinner_example.c "example", whose window should
1467 * look like this picture:
1468 *
1469 * @image html screenshots/spinner_example.png
1470 * @image latex screenshots/spinner_example.eps width=\textwidth
1471 *
1472 * See the full @ref spinner_example_c "source code" for this example.
1473 *
1474 * @example spinner_example.c
1475 */
1476
1477/**
1403 * @page clock_example Clock widget example 1478 * @page clock_example Clock widget example
1404 * 1479 *
1405 * This code places five Elementary clock widgets on a window, each of 1480 * This code places five Elementary clock widgets on a window, each of
diff --git a/doc/index.doxy b/doc/index.doxy
index 83389a3db..a27714988 100644
--- a/doc/index.doxy
+++ b/doc/index.doxy
@@ -162,6 +162,9 @@
162 * @li @ref Slider 162 * @li @ref Slider
163 * @li @ref Slideshow 163 * @li @ref Slideshow
164 * @li @ref Spinner 164 * @li @ref Spinner
165 *
166 * @image html img/widget/spinner/preview-00.png
167 * @image latex img/widget/spinner/preview-00.eps
165 * @li @ref Thumb 168 * @li @ref Thumb
166 * @li @ref Toggle 169 * @li @ref Toggle
167 * 170 *
diff --git a/doc/widgets/Makefile.am b/doc/widgets/Makefile.am
index 153524441..e67e20b30 100644
--- a/doc/widgets/Makefile.am
+++ b/doc/widgets/Makefile.am
@@ -31,6 +31,7 @@ widget_preview_button3 \
31widget_preview_check1 \ 31widget_preview_check1 \
32widget_preview_check2 \ 32widget_preview_check2 \
33widget_preview_check3 \ 33widget_preview_check3 \
34widget_preview_spinner \
34widget_preview_bubble1 \ 35widget_preview_bubble1 \
35widget_preview_bubble2 \ 36widget_preview_bubble2 \
36widget_preview_bubble3 \ 37widget_preview_bubble3 \
@@ -90,6 +91,7 @@ EXTRA_DIST = \
90 widget_preview_check1.c \ 91 widget_preview_check1.c \
91 widget_preview_check2.c \ 92 widget_preview_check2.c \
92 widget_preview_check3.c \ 93 widget_preview_check3.c \
94 widget_preview_spinner.c \
93 widget_preview_clock.c \ 95 widget_preview_clock.c \
94 widget_preview_colorselector.c \ 96 widget_preview_colorselector.c \
95 widget_preview_conformant.c \ 97 widget_preview_conformant.c \
diff --git a/doc/widgets/widget_preview_spinner.c b/doc/widgets/widget_preview_spinner.c
new file mode 100644
index 000000000..4c6d4afc9
--- /dev/null
+++ b/doc/widgets/widget_preview_spinner.c
@@ -0,0 +1,8 @@
1#include "widget_preview_tmpl_head.c"
2
3Evas_Object *o = elm_spinner_add(win);
4evas_object_size_hint_weight_set(o, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
5elm_win_resize_object_add(win, o);
6evas_object_show(o);
7
8#include "widget_preview_tmpl_foot.c"
diff --git a/src/examples/Makefile.am b/src/examples/Makefile.am
index 63336f8aa..adfc09450 100644
--- a/src/examples/Makefile.am
+++ b/src/examples/Makefile.am
@@ -58,6 +58,7 @@ SRCS = \
58 calendar_example_04.c \ 58 calendar_example_04.c \
59 calendar_example_05.c \ 59 calendar_example_05.c \
60 calendar_example_06.c \ 60 calendar_example_06.c \
61 spinner_example.c \
61 clock_example.c \ 62 clock_example.c \
62 conformant_example_01.c \ 63 conformant_example_01.c \
63 conformant_example_02.c \ 64 conformant_example_02.c \
@@ -134,6 +135,7 @@ pkglib_PROGRAMS += \
134 calendar_example_04 \ 135 calendar_example_04 \
135 calendar_example_05 \ 136 calendar_example_05 \
136 calendar_example_06 \ 137 calendar_example_06 \
138 spinner_example \
137 clock_example \ 139 clock_example \
138 conformant_example_01 \ 140 conformant_example_01 \
139 conformant_example_02 \ 141 conformant_example_02 \
@@ -189,6 +191,7 @@ SCREENSHOTS = \
189 calendar_example_04:calendar_example_04.png:0.0 \ 191 calendar_example_04:calendar_example_04.png:0.0 \
190 calendar_example_05:calendar_example_05.png:0.0 \ 192 calendar_example_05:calendar_example_05.png:0.0 \
191 calendar_example_06:calendar_example_06.png:0.0 \ 193 calendar_example_06:calendar_example_06.png:0.0 \
194 spinner_example:spinner_example.png:0.0 \
192 clock_example:clock_example.png:0.5 \ 195 clock_example:clock_example.png:0.5 \
193 image_example_01:image_example_01.png:0.0 \ 196 image_example_01:image_example_01.png:0.0 \
194 diskselector_example_01:diskselector_example_01.png:0.2 \ 197 diskselector_example_01:diskselector_example_01.png:0.2 \
diff --git a/src/examples/spinner_example.c b/src/examples/spinner_example.c
new file mode 100644
index 000000000..10dcf9d5d
--- /dev/null
+++ b/src/examples/spinner_example.c
@@ -0,0 +1,135 @@
1/**
2 * Simple Elementary's <b>spinner widget</b> example, illustrating its
3 * usage and API.
4 *
5 * See stdout/stderr for output. Compile with:
6 *
7 * @verbatim
8 * gcc -g `pkg-config --cflags --libs elementary` spinner_example.c -o spinner_example
9 * @endverbatim
10 */
11
12#include <Elementary.h>
13#ifdef HAVE_CONFIG_H
14# include "elementary_config.h"
15#else
16# define __UNUSED__
17#endif
18
19static void
20_on_done(void *data __UNUSED__,
21 Evas_Object *obj __UNUSED__,
22 void *event_info __UNUSED__)
23{
24 elm_exit();
25}
26
27static void
28_changed_cb(void *data __UNUSED__, Evas_Object *obj, void *event_info __UNUSED__)
29{
30 printf("Value changed to %0.f\n", elm_spinner_value_get(obj));
31}
32
33static void
34_delay_changed_cb(void *data __UNUSED__, Evas_Object *obj, void *event_info __UNUSED__)
35{
36 printf("Value delay changed to %0.f\n", elm_spinner_value_get(obj));
37}
38
39int
40elm_main(int argc __UNUSED__, char **argv __UNUSED__)
41{
42 Evas_Object *win, *bg, *bx, *sp;
43
44 win = elm_win_add(NULL, "spinner", ELM_WIN_BASIC);
45 elm_win_title_set(win, "Spinner Example");
46 evas_object_smart_callback_add(win, "delete,request", _on_done, NULL);
47
48 bg = elm_bg_add(win);
49 elm_win_resize_object_add(win, bg);
50 evas_object_size_hint_weight_set(bg, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
51 evas_object_show(bg);
52
53 bx = elm_box_add(win);
54 evas_object_size_hint_weight_set(bx, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
55 elm_win_resize_object_add(win, bx);
56 evas_object_show(bx);
57
58 /* default */
59 sp = elm_spinner_add(win);
60 evas_object_size_hint_align_set(sp, EVAS_HINT_FILL, 0.5);
61 evas_object_size_hint_weight_set(sp, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
62 elm_box_pack_end(bx, sp);
63 evas_object_show(sp);
64
65 /* format */
66 sp = elm_spinner_add(win);
67 elm_spinner_label_format_set(sp, "Percentage %%%1.2f something");
68 evas_object_size_hint_align_set(sp, EVAS_HINT_FILL, 0.5);
69 evas_object_size_hint_weight_set(sp, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
70 elm_box_pack_end(bx, sp);
71 evas_object_show(sp);
72
73 /* min max, step and wrap */
74 sp = elm_spinner_add(win);
75 elm_spinner_label_format_set(sp, "%1.1f units");
76 elm_spinner_step_set(sp, 1.5);
77 elm_spinner_wrap_set(sp, EINA_TRUE);
78 elm_spinner_min_max_set(sp, -50.0, 250.0);
79 evas_object_size_hint_align_set(sp, EVAS_HINT_FILL, 0.5);
80 evas_object_size_hint_weight_set(sp, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
81 elm_box_pack_end(bx, sp);
82 evas_object_show(sp);
83
84 /* vertical */
85 sp = elm_spinner_add(win);
86 elm_object_style_set(sp, "vertical");
87 elm_spinner_interval_set(sp, 0.2);
88 evas_object_size_hint_align_set(sp, EVAS_HINT_FILL, 0.5);
89 evas_object_size_hint_weight_set(sp, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
90 elm_box_pack_end(bx, sp);
91 evas_object_show(sp);
92
93 /* disabled edition */
94 sp = elm_spinner_add(win);
95 elm_spinner_editable_set(sp, EINA_FALSE);
96 evas_object_size_hint_align_set(sp, EVAS_HINT_FILL, 0.5);
97 evas_object_size_hint_weight_set(sp, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
98 elm_box_pack_end(bx, sp);
99 evas_object_show(sp);
100
101 /* special values */
102 sp = elm_spinner_add(win);
103 elm_spinner_editable_set(sp, EINA_FALSE);
104 elm_spinner_min_max_set(sp, 1, 12);
105 elm_spinner_special_value_add(sp, 1, "January");
106 elm_spinner_special_value_add(sp, 2, "February");
107 elm_spinner_special_value_add(sp, 3, "March");
108 elm_spinner_special_value_add(sp, 4, "April");
109 elm_spinner_special_value_add(sp, 5, "May");
110 elm_spinner_special_value_add(sp, 6, "June");
111 elm_spinner_special_value_add(sp, 7, "July");
112 elm_spinner_special_value_add(sp, 8, "August");
113 elm_spinner_special_value_add(sp, 9, "September");
114 elm_spinner_special_value_add(sp, 10, "October");
115 elm_spinner_special_value_add(sp, 11, "November");
116 elm_spinner_special_value_add(sp, 12, "December");
117 evas_object_size_hint_align_set(sp, EVAS_HINT_FILL, 0.5);
118 evas_object_size_hint_weight_set(sp, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
119 elm_box_pack_end(bx, sp);
120 evas_object_show(sp);
121
122 sp = elm_spinner_add(win);
123 evas_object_size_hint_align_set(sp, EVAS_HINT_FILL, 0.5);
124 evas_object_size_hint_weight_set(sp, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
125 elm_box_pack_end(bx, sp);
126 evas_object_show(sp);
127 evas_object_smart_callback_add(sp, "changed", _changed_cb, NULL);
128 evas_object_smart_callback_add(sp, "delay,changed", _delay_changed_cb, NULL);
129
130 evas_object_show(win);
131
132 elm_run();
133 return 0;
134}
135ELM_MAIN()
diff --git a/src/lib/Elementary.h.in b/src/lib/Elementary.h.in
index 0036a82b3..0554e0d6e 100644
--- a/src/lib/Elementary.h.in
+++ b/src/lib/Elementary.h.in
@@ -11706,30 +11706,351 @@ extern "C" {
11706 * @} 11706 * @}
11707 */ 11707 */
11708 11708
11709 /* spinner */ 11709 /**
11710 * @defgroup Spinner Spinner
11711 * @ingroup Elementary
11712 *
11713 * @image html img/widget/spinner/preview-00.png
11714 * @image latex img/widget/spinner/preview-00.eps
11715 *
11716 * A spinner is a widget which allows the user to increase or decrease
11717 * numeric values using arrow buttons, or edit values directly, clicking
11718 * over it and typing the new value.
11719 *
11720 * By default the spinner will not wrap and has a label
11721 * of "%.0f" (just showing the integer value of the double).
11722 *
11723 * A spinner has a label that is formatted with floating
11724 * point values and thus accepts a printf-style format string, like
11725 * “%1.2f units”.
11726 *
11727 * It also allows specific values to be replaced by pre-defined labels.
11728 *
11729 * Smart callbacks one can register to:
11730 *
11731 * - "changed" - Whenever the spinner value is changed.
11732 * - "delay,changed" - A short time after the value is changed by the user.
11733 * This will be called only when the user stops dragging for a very short
11734 * period or when they release their finger/mouse, so it avoids possibly
11735 * expensive reactions to the value change.
11736 *
11737 * Available styles for it:
11738 * - @c "default";
11739 * - @c "vertical": up/down buttons at the right side and text left aligned.
11740 *
11741 * Here is an example on its usage:
11742 * @ref spinner_example
11743 */
11744
11745 /**
11746 * @addtogroup Spinner
11747 * @{
11748 */
11749
11750 /**
11751 * Add a new spinner widget to the given parent Elementary
11752 * (container) object.
11753 *
11754 * @param parent The parent object.
11755 * @return a new spinner widget handle or @c NULL, on errors.
11756 *
11757 * This function inserts a new spinner widget on the canvas.
11758 *
11759 * @ingroup Spinner
11760 *
11761 */
11710 EAPI Evas_Object *elm_spinner_add(Evas_Object *parent) EINA_ARG_NONNULL(1); 11762 EAPI Evas_Object *elm_spinner_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
11763
11764 /**
11765 * Set the format string of the displayed label.
11766 *
11767 * @param obj The spinner object.
11768 * @param fmt The format string for the label display.
11769 *
11770 * If @c NULL, this sets the format to "%.0f". If not it sets the format
11771 * string for the label text. The label text is provided a floating point
11772 * value, so the label text can display up to 1 floating point value.
11773 * Note that this is optional.
11774 *
11775 * Use a format string such as "%1.2f meters" for example, and it will
11776 * display values like: "3.14 meters" for a value equal to 3.14159.
11777 *
11778 * Default is "%0.f".
11779 *
11780 * @see elm_spinner_label_format_get()
11781 *
11782 * @ingroup Spinner
11783 */
11711 EAPI void elm_spinner_label_format_set(Evas_Object *obj, const char *fmt) EINA_ARG_NONNULL(1); 11784 EAPI void elm_spinner_label_format_set(Evas_Object *obj, const char *fmt) EINA_ARG_NONNULL(1);
11785
11786 /**
11787 * Get the label format of the spinner.
11788 *
11789 * @param obj The spinner object.
11790 * @return The text label format string in UTF-8.
11791 *
11792 * @see elm_spinner_label_format_set() for details.
11793 *
11794 * @ingroup Spinner
11795 */
11712 EAPI const char *elm_spinner_label_format_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); 11796 EAPI const char *elm_spinner_label_format_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
11797
11798 /**
11799 * Set the minimum and maximum values for the spinner.
11800 *
11801 * @param obj The spinner object.
11802 * @param min The minimum value.
11803 * @param max The maximum value.
11804 *
11805 * Define the allowed range of values to be selected by the user.
11806 *
11807 * If actual value is less than @p min, it will be updated to @p min. If it
11808 * is bigger then @p max, will be updated to @p max. Actual value can be
11809 * get with elm_spinner_value_get().
11810 *
11811 * By default, min is equal to 0, and max is equal to 100.
11812 *
11813 * @warning Maximum must be greater than minimum.
11814 *
11815 * @see elm_spinner_min_max_get()
11816 *
11817 * @ingroup Spinner
11818 */
11713 EAPI void elm_spinner_min_max_set(Evas_Object *obj, double min, double max) EINA_ARG_NONNULL(1); 11819 EAPI void elm_spinner_min_max_set(Evas_Object *obj, double min, double max) EINA_ARG_NONNULL(1);
11820
11821 /**
11822 * Get the minimum and maximum values of the spinner.
11823 *
11824 * @param obj The spinner object.
11825 * @param min Pointer where to store the minimum value.
11826 * @param max Pointer where to store the maximum value.
11827 *
11828 * @note If only one value is needed, the other pointer can be passed
11829 * as @c NULL.
11830 *
11831 * @see elm_spinner_min_max_set() for details.
11832 *
11833 * @ingroup Spinner
11834 */
11714 EAPI void elm_spinner_min_max_get(const Evas_Object *obj, double *min, double *max) EINA_ARG_NONNULL(1); 11835 EAPI void elm_spinner_min_max_get(const Evas_Object *obj, double *min, double *max) EINA_ARG_NONNULL(1);
11836
11837 /**
11838 * Set the step used to increment or decrement the spinner value.
11839 *
11840 * @param obj The spinner object.
11841 * @param step The step value.
11842 *
11843 * This value will be incremented or decremented to the displayed value.
11844 * It will be incremented while the user keep right or top arrow pressed,
11845 * and will be decremented while the user keep left or bottom arrow pressed.
11846 *
11847 * The interval to increment / decrement can be set with
11848 * elm_spinner_interval_set().
11849 *
11850 * By default step value is equal to 1.
11851 *
11852 * @see elm_spinner_step_get()
11853 *
11854 * @ingroup Spinner
11855 */
11715 EAPI void elm_spinner_step_set(Evas_Object *obj, double step) EINA_ARG_NONNULL(1); 11856 EAPI void elm_spinner_step_set(Evas_Object *obj, double step) EINA_ARG_NONNULL(1);
11857
11858 /**
11859 * Get the step used to increment or decrement the spinner value.
11860 *
11861 * @param obj The spinner object.
11862 * @return The step value.
11863 *
11864 * @see elm_spinner_step_get() for more details.
11865 *
11866 * @ingroup Spinner
11867 */
11716 EAPI double elm_spinner_step_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); 11868 EAPI double elm_spinner_step_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
11869
11870 /**
11871 * Set the value the spinner displays.
11872 *
11873 * @param obj The spinner object.
11874 * @param val The value to be displayed.
11875 *
11876 * Value will be presented on the label following format specified with
11877 * elm_spinner_format_set().
11878 *
11879 * @warning The value must to be between min and max values. This values
11880 * are set by elm_spinner_min_max_set().
11881 *
11882 * @see elm_spinner_value_get().
11883 * @see elm_spinner_format_set().
11884 * @see elm_spinner_min_max_set().
11885 *
11886 * @ingroup Spinner
11887 */
11717 EAPI void elm_spinner_value_set(Evas_Object *obj, double val) EINA_ARG_NONNULL(1); 11888 EAPI void elm_spinner_value_set(Evas_Object *obj, double val) EINA_ARG_NONNULL(1);
11889
11890 /**
11891 * Get the value displayed by the spinner.
11892 *
11893 * @param obj The spinner object.
11894 * @return The value displayed.
11895 *
11896 * @see elm_spinner_value_set() for details.
11897 *
11898 * @ingroup Spinner
11899 */
11718 EAPI double elm_spinner_value_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); 11900 EAPI double elm_spinner_value_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
11901
11902 /**
11903 * Set whether the spinner should wrap when it reaches its
11904 * minimum or maximum value.
11905 *
11906 * @param obj The spinner object.
11907 * @param wrap @c EINA_TRUE to enable wrap or @c EINA_FALSE to
11908 * disable it.
11909 *
11910 * Disabled by default. If disabled, when the user tries to increment the
11911 * value,
11912 * but displayed value plus step value is bigger than maximum value,
11913 * the spinner
11914 * won't allow it. The same happens when the user tries to decrement it,
11915 * but the value less step is less than minimum value.
11916 *
11917 * When wrap is enabled, in such situations it will allow these changes,
11918 * but will get the value that would be less than minimum and subtracts
11919 * from maximum. Or add the value that would be more than maximum to
11920 * the minimum.
11921 *
11922 * E.g.:
11923 * @li min value = 10
11924 * @li max value = 50
11925 * @li step value = 20
11926 * @li displayed value = 20
11927 *
11928 * When the user decrement value (using left or bottom arrow), it will
11929 * displays @c 40, because max - (min - (displayed - step)) is
11930 * @c 50 - (@c 10 - (@c 20 - @c 20)) = @c 40.
11931 *
11932 * @see elm_spinner_wrap_get().
11933 *
11934 * @ingroup Spinner
11935 */
11719 EAPI void elm_spinner_wrap_set(Evas_Object *obj, Eina_Bool wrap) EINA_ARG_NONNULL(1); 11936 EAPI void elm_spinner_wrap_set(Evas_Object *obj, Eina_Bool wrap) EINA_ARG_NONNULL(1);
11937
11938 /**
11939 * Get whether the spinner should wrap when it reaches its
11940 * minimum or maximum value.
11941 *
11942 * @param obj The spinner object
11943 * @return @c EINA_TRUE means wrap is enabled. @c EINA_FALSE indicates
11944 * it's disabled. If @p obj is @c NULL, @c EINA_FALSE is returned.
11945 *
11946 * @see elm_spinner_wrap_set() for details.
11947 *
11948 * @ingroup Spinner
11949 */
11720 EAPI Eina_Bool elm_spinner_wrap_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); 11950 EAPI Eina_Bool elm_spinner_wrap_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
11951
11952 /**
11953 * Set whether the spinner can be directly edited by the user or not.
11954 *
11955 * @param obj The spinner object.
11956 * @param editable @c EINA_TRUE to allow users to edit it or @c EINA_FALSE to
11957 * don't allow users to edit it directly.
11958 *
11959 * Spinner objects can have edition @b disabled, in which state they will
11960 * be changed only by arrows.
11961 * Useful for contexts
11962 * where you don't want your users to interact with it writting the value.
11963 * Specially
11964 * when using special values, the user can see real value instead
11965 * of special label on edition.
11966 *
11967 * It's enabled by default.
11968 *
11969 * @see elm_spinner_editable_get()
11970 *
11971 * @ingroup Spinner
11972 */
11721 EAPI void elm_spinner_editable_set(Evas_Object *obj, Eina_Bool editable) EINA_ARG_NONNULL(1); 11973 EAPI void elm_spinner_editable_set(Evas_Object *obj, Eina_Bool editable) EINA_ARG_NONNULL(1);
11974
11975 /**
11976 * Get whether the spinner can be directly edited by the user or not.
11977 *
11978 * @param obj The spinner object.
11979 * @return @c EINA_TRUE means edition is enabled. @c EINA_FALSE indicates
11980 * it's disabled. If @p obj is @c NULL, @c EINA_FALSE is returned.
11981 *
11982 * @see elm_spinner_editable_set() for details.
11983 *
11984 * @ingroup Spinner
11985 */
11722 EAPI Eina_Bool elm_spinner_editable_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); 11986 EAPI Eina_Bool elm_spinner_editable_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
11987
11988 /**
11989 * Set a special string to display in the place of the numerical value.
11990 *
11991 * @param obj The spinner object.
11992 * @param value The value to be replaced.
11993 * @param label The label to be used.
11994 *
11995 * It's useful for cases when a user should select an item that is
11996 * better indicated by a label than a value. For example, weekdays or months.
11997 *
11998 * E.g.:
11999 * @code
12000 * sp = elm_spinner_add(win);
12001 * elm_spinner_min_max_set(sp, 1, 3);
12002 * elm_spinner_special_value_add(sp, 1, "January");
12003 * elm_spinner_special_value_add(sp, 2, "February");
12004 * elm_spinner_special_value_add(sp, 3, "March");
12005 * evas_object_show(sp);
12006 * @endcode
12007 *
12008 * @ingroup Spinner
12009 */
11723 EAPI void elm_spinner_special_value_add(Evas_Object *obj, double value, const char *label) EINA_ARG_NONNULL(1); 12010 EAPI void elm_spinner_special_value_add(Evas_Object *obj, double value, const char *label) EINA_ARG_NONNULL(1);
12011
12012 /**
12013 * Set the interval on time updates for an user mouse button hold
12014 * on spinner widgets' arrows.
12015 *
12016 * @param obj The spinner object.
12017 * @param interval The (first) interval value in seconds.
12018 *
12019 * This interval value is @b decreased while the user holds the
12020 * mouse pointer either incrementing or decrementing spinner's value.
12021 *
12022 * This helps the user to get to a given value distant from the
12023 * current one easier/faster, as it will start to change quicker and
12024 * quicker on mouse button holds.
12025 *
12026 * The calculation for the next change interval value, starting from
12027 * the one set with this call, is the previous interval divided by
12028 * @c 1.05, so it decreases a little bit.
12029 *
12030 * The default starting interval value for automatic changes is
12031 * @c 0.85 seconds.
12032 *
12033 * @see elm_spinner_interval_get()
12034 *
12035 * @ingroup Spinner
12036 */
11724 EAPI void elm_spinner_interval_set(Evas_Object *obj, double interval) EINA_ARG_NONNULL(1); 12037 EAPI void elm_spinner_interval_set(Evas_Object *obj, double interval) EINA_ARG_NONNULL(1);
11725 EAPI double elm_spinner_interval_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); 12038
11726 /* smart callbacks called: 12039 /**
11727 * "changed" - when the spinner value changes 12040 * Get the interval on time updates for an user mouse button hold
11728 * "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). 12041 * on spinner widgets' arrows.
12042 *
12043 * @param obj The spinner object.
12044 * @return The (first) interval value, in seconds, set on it.
12045 *
12046 * @see elm_spinner_interval_set() for more details.
12047 *
12048 * @ingroup Spinner
11729 */ 12049 */
11730 /* available item styles: 12050 EAPI double elm_spinner_interval_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
11731 * default 12051
11732 * vertical (two up/down buttons at the right side and text left aligned) 12052 /**
12053 * @}
11733 */ 12054 */
11734 12055
11735 /** 12056 /**
diff --git a/src/lib/elm_spinner.c b/src/lib/elm_spinner.c
index 87d1ceae4..5db909ddf 100644
--- a/src/lib/elm_spinner.c
+++ b/src/lib/elm_spinner.c
@@ -2,25 +2,6 @@
2#include "elm_priv.h" 2#include "elm_priv.h"
3#include <ctype.h> 3#include <ctype.h>
4 4
5/**
6 * @defgroup Spinner
7 *
8 * A spinner is a widget which allows the user to increase or decrease
9 * numeric values. By default the spinner will not wrap and has a label
10 * of "%.0f" (just showing the integer value of the double).
11 *
12 * A spinner has a label that is formatted with floating
13 * point values and thus accepts a printf-style format string, like
14 * “%1.2f units”.
15 *
16 * Signals that you can add callbacks for are:
17 *
18 * "changed" - Whenever the spinner value is changed by the user.
19 * "delay,changed" - A short time after the value is changed by the user.
20 * This will be called only when the user stops dragging for a very short
21 * period or when they release their finger/mouse, so it avoids possibly
22 * expensive reactions to the value change.
23 */
24typedef struct _Widget_Data Widget_Data; 5typedef struct _Widget_Data Widget_Data;
25typedef struct _Elm_Spinner_Special_Value Elm_Spinner_Special_Value; 6typedef struct _Elm_Spinner_Special_Value Elm_Spinner_Special_Value;
26 7
@@ -568,14 +549,6 @@ _event_hook(Evas_Object *obj, Evas_Object *src __UNUSED__, Evas_Callback_Type ty
568 return EINA_FALSE; 549 return EINA_FALSE;
569} 550}
570 551
571/**
572 * Add a new spinner to the parent
573 *
574 * @param parent The parent object
575 * @return The new object or NULL if it cannot be created
576 *
577 * @ingroup Spinner
578 */
579EAPI Evas_Object * 552EAPI Evas_Object *
580elm_spinner_add(Evas_Object *parent) 553elm_spinner_add(Evas_Object *parent)
581{ 554{
@@ -648,19 +621,6 @@ elm_spinner_add(Evas_Object *parent)
648 return obj; 621 return obj;
649} 622}
650 623
651/**
652 * Set the format string of the label area
653 *
654 * If NULL, this sets the format to "%.0f". If not it sets the format
655 * string for the label text. The label text is provided a floating point
656 * value, so the label text can display up to 1 floating point value. Note that
657 * this is optional. Use a format string such as "%1.2f meters" for example.
658 *
659 * @param obj The spinner object
660 * @param fmt The format string for the label display
661 *
662 * @ingroup Spinner
663 */
664EAPI void 624EAPI void
665elm_spinner_label_format_set(Evas_Object *obj, const char *fmt) 625elm_spinner_label_format_set(Evas_Object *obj, const char *fmt)
666{ 626{
@@ -672,14 +632,6 @@ elm_spinner_label_format_set(Evas_Object *obj, const char *fmt)
672 _sizing_eval(obj); 632 _sizing_eval(obj);
673} 633}
674 634
675/**
676 * Get the label format of the spinner
677 *
678 * @param obj The spinner object
679 * @return The text label format string in UTF-8
680 *
681 * @ingroup Spinner
682 */
683EAPI const char * 635EAPI const char *
684elm_spinner_label_format_get(const Evas_Object *obj) 636elm_spinner_label_format_get(const Evas_Object *obj)
685{ 637{
@@ -689,17 +641,6 @@ elm_spinner_label_format_get(const Evas_Object *obj)
689 return wd->label; 641 return wd->label;
690} 642}
691 643
692/**
693 * Set the minimum and maximum values for the spinner
694 *
695 * Maximum must be greater than minimum.
696 *
697 * @param obj The spinner object
698 * @param min The minimum value
699 * @param max The maximum value
700 *
701 * @ingroup Spinner
702 */
703EAPI void 644EAPI void
704elm_spinner_min_max_set(Evas_Object *obj, double min, double max) 645elm_spinner_min_max_set(Evas_Object *obj, double min, double max)
705{ 646{
@@ -715,15 +656,6 @@ elm_spinner_min_max_set(Evas_Object *obj, double min, double max)
715 _write_label(obj); 656 _write_label(obj);
716} 657}
717 658
718/**
719 * Get the minimum and maximum values of the spinner
720 *
721 * @param obj The spinner object
722 * @param min The minimum value
723 * @param max The maximum value
724 *
725 * @ingroup Spinner
726 */
727EAPI void 659EAPI void
728elm_spinner_min_max_get(const Evas_Object *obj, double *min, double *max) 660elm_spinner_min_max_get(const Evas_Object *obj, double *min, double *max)
729{ 661{
@@ -736,14 +668,6 @@ elm_spinner_min_max_get(const Evas_Object *obj, double *min, double *max)
736 if (max) *max = wd->val_max; 668 if (max) *max = wd->val_max;
737} 669}
738 670
739/**
740 * Set the step for the spinner
741 *
742 * @param obj The spinner object
743 * @param step The step value
744 *
745 * @ingroup Spinner
746 */
747EAPI void 671EAPI void
748elm_spinner_step_set(Evas_Object *obj, double step) 672elm_spinner_step_set(Evas_Object *obj, double step)
749{ 673{
@@ -753,14 +677,6 @@ elm_spinner_step_set(Evas_Object *obj, double step)
753 wd->step = step; 677 wd->step = step;
754} 678}
755 679
756/**
757 * Get the step of the spinner
758 *
759 * @param obj The spinner object
760 * @return The step value
761 *
762 * @ingroup Spinner
763 */
764EAPI double 680EAPI double
765elm_spinner_step_get(const Evas_Object *obj) 681elm_spinner_step_get(const Evas_Object *obj)
766{ 682{
@@ -769,14 +685,7 @@ elm_spinner_step_get(const Evas_Object *obj)
769 if (!wd) return 0.0; 685 if (!wd) return 0.0;
770 return wd->step; 686 return wd->step;
771} 687}
772/** 688
773 * Set the value the spinner indicates
774 *
775 * @param obj The spinner object
776 * @param val The value (must be between min and max for the spinner)
777 *
778 * @ingroup Spinner
779 */
780EAPI void 689EAPI void
781elm_spinner_value_set(Evas_Object *obj, double val) 690elm_spinner_value_set(Evas_Object *obj, double val)
782{ 691{
@@ -791,14 +700,6 @@ elm_spinner_value_set(Evas_Object *obj, double val)
791 _write_label(obj); 700 _write_label(obj);
792} 701}
793 702
794/**
795 * Get the value the spinner has
796 *
797 * @param obj The spinner object
798 * @return The value of the spinner
799 *
800 * @ingroup Spinner
801 */
802EAPI double 703EAPI double
803elm_spinner_value_get(const Evas_Object *obj) 704elm_spinner_value_get(const Evas_Object *obj)
804{ 705{
@@ -808,15 +709,6 @@ elm_spinner_value_get(const Evas_Object *obj)
808 return wd->val; 709 return wd->val;
809} 710}
810 711
811/**
812 * Sets whether the spinner should wrap when it reaches its
813 * minimum/maximum value
814 *
815 * @param obj The spinner object
816 * @param wrap True if it should wrap, false otherwise
817 *
818 * @ingroup Spinner
819 */
820EAPI void 712EAPI void
821elm_spinner_wrap_set(Evas_Object *obj, Eina_Bool wrap) 713elm_spinner_wrap_set(Evas_Object *obj, Eina_Bool wrap)
822{ 714{
@@ -826,16 +718,6 @@ elm_spinner_wrap_set(Evas_Object *obj, Eina_Bool wrap)
826 wd->wrap = wrap; 718 wd->wrap = wrap;
827} 719}
828 720
829/**
830 * Gets whether the spinner should wrap when it reaches its
831 * minimum/maximum value
832 *
833 * @param obj The spinner object
834 * @return Bool value of wrap option
835 * (0 = disabled, 1 = enabled)
836 *
837 * @ingroup Spinner
838 */
839EAPI Eina_Bool 721EAPI Eina_Bool
840elm_spinner_wrap_get(const Evas_Object *obj) 722elm_spinner_wrap_get(const Evas_Object *obj)
841{ 723{
@@ -845,15 +727,6 @@ elm_spinner_wrap_get(const Evas_Object *obj)
845 return wd->wrap; 727 return wd->wrap;
846} 728}
847 729
848/**
849 * Set a special value to display in the place of the numerical one.
850 *
851 * @param obj The spinner object
852 * @param value The value to be replaced
853 * @param label The label to be used
854 *
855 * @ingroup Spinner
856 */
857EAPI void 730EAPI void
858elm_spinner_special_value_add(Evas_Object *obj, double value, const char *label) 731elm_spinner_special_value_add(Evas_Object *obj, double value, const char *label)
859{ 732{
@@ -871,14 +744,6 @@ elm_spinner_special_value_add(Evas_Object *obj, double value, const char *label)
871 _write_label(obj); 744 _write_label(obj);
872} 745}
873 746
874/**
875 * Set whether the spinner can be directly edited by the user or not.
876 * Default is editable.
877 *
878 * @param obj The spinner object
879 * @param editable Bool value of the edit option
880 * (EINA_FALSE = not editable, EINA_TRUE = editable)
881 */
882EAPI void 747EAPI void
883elm_spinner_editable_set(Evas_Object *obj, Eina_Bool editable) 748elm_spinner_editable_set(Evas_Object *obj, Eina_Bool editable)
884{ 749{
@@ -888,13 +753,6 @@ elm_spinner_editable_set(Evas_Object *obj, Eina_Bool editable)
888 wd->editable = editable; 753 wd->editable = editable;
889} 754}
890 755
891/**
892 * Gets whether the spinner is editable.
893 *
894 * @param obj The spinner object
895 * @return Bool value of edit option
896 * (EINA_FALSE = not editable, EINA_TRUE = editable)
897 */
898EAPI Eina_Bool 756EAPI Eina_Bool
899elm_spinner_editable_get(const Evas_Object *obj) 757elm_spinner_editable_get(const Evas_Object *obj)
900{ 758{
@@ -904,18 +762,6 @@ elm_spinner_editable_get(const Evas_Object *obj)
904 return wd->editable; 762 return wd->editable;
905} 763}
906 764
907/**
908 * Set the interval for the spinner
909 *
910 * @param obj The spinner object
911 * @param interval The interval value in seconds
912 *
913 * The interval value is decreased while the user increments or decrements
914 * the spinner value. The next interval value is the previous interval / 1.05,
915 * so it speed up a bit. Default value is 0.85 seconds.
916 *
917 * @ingroup Spinner
918 */
919EAPI void 765EAPI void
920elm_spinner_interval_set(Evas_Object *obj, double interval) 766elm_spinner_interval_set(Evas_Object *obj, double interval)
921{ 767{
@@ -925,18 +771,6 @@ elm_spinner_interval_set(Evas_Object *obj, double interval)
925 wd->first_interval = interval; 771 wd->first_interval = interval;
926} 772}
927 773
928/**
929 * Get the interval of the spinner
930 *
931 * @param obj The spinner object
932 * @return The value of the first interval in seconds
933 *
934 * The interval value is decreased while the user increments or decrements
935 * the spinner value. The next interval value is the previous interval / 1.05,
936 * so it speed up a bit. Default value is 0.85 seconds.
937 *
938 * @ingroup Spinner
939 */
940EAPI double 774EAPI double
941elm_spinner_interval_get(const Evas_Object *obj) 775elm_spinner_interval_get(const Evas_Object *obj)
942{ 776{