diff --git a/legacy/elementary/doc/Makefile.am b/legacy/elementary/doc/Makefile.am index 5efb433808..f6aeb68b62 100644 --- a/legacy/elementary/doc/Makefile.am +++ b/legacy/elementary/doc/Makefile.am @@ -49,7 +49,8 @@ WGT_PREVIEW = \ anchorview:preview-00.png:widget_preview_anchorview:100:30 \ anchorblock:preview-00.png:widget_preview_anchorblock:100:30 \ pager:preview-00.png:widget_preview_pager:100:100 \ - separator:preview-00.png:widget_preview_separator:10:80 + separator:preview-00.png:widget_preview_separator:10:80 \ + radio:preview-00.png:widget_preview_radio:60:20 widget-build: @$(MAKE) -C widgets diff --git a/legacy/elementary/doc/examples.dox b/legacy/elementary/doc/examples.dox index 692d2db6f7..963fd2b844 100644 --- a/legacy/elementary/doc/examples.dox +++ b/legacy/elementary/doc/examples.dox @@ -2903,6 +2903,66 @@ * @example separator_example_01.c */ +/** + * @page tutorial_radio Radio example + * @dontinclude radio_example_01.c + * + * In this example we will create 4 radio buttons, three of them in a group and + * another one not in the group. We will also have the radios in the group + * change the value of a variable directly and have then print it when the value + * changes. The fourth button is in the example just to make clear that radios + * outside the group don't affect the group. + * + * We'll start with the usual includes: + * @until #endif + * + * And move right to declaring a static variable(the one whose value the radios + * will change): + * @until static + * + * We now need to have a window and all that good stuff to be able to place our + * radios in: + * @until show(bx) + * + * And now we create a radio button, since this is the first button in our group + * we set the group to be the radio(so we can set the other radios in the same + * group). We also set the state value of this radio to 1 and the value pointer + * to @p val, since val is @p 1 this has the additional effect of setting the + * radio value to @p 1. For this radio we choose the default home icon: + * @until show + * + * To check that our radio buttons are working we'll add a callback to the + * "changed" signal of the radio: + * @until smart_callback + * + * The creation of our second radio button is almost identical, the 2 + * differences worth noting are, the value of this radio 2 and that we add this + * radio to the group of the first radio: + * @until smart_callback + * + * For our third callback we'll omit the icon and set the value to 3, we'll also + * add it to the group of the first radio: + * @until smart_callback + * + * Our fourth callback has a value of 4, no icon and most relevantly is not a + * member of the same group as the other radios: + * @until show + * + * We finally run the main loop: + * @until ELM_MAIN + * + * And the last detail in our example is the callback that prints @p val so that + * we can see that the radios are indeed changing its value: + * @until } + * + * The example will look like this: + * + * @image html screenshots/radio_example_01.png + * @image latex screenshots/radio_example_01.epx width=\textwidth + * + * @example radio_example_01.c + */ + /** * @page bg_example_01_c bg_example_01.c * @include bg_example_01.c diff --git a/legacy/elementary/doc/index.doxy b/legacy/elementary/doc/index.doxy index d3a33d4f44..313c13b141 100644 --- a/legacy/elementary/doc/index.doxy +++ b/legacy/elementary/doc/index.doxy @@ -146,6 +146,9 @@ * @li @ref Photocam * @li @ref Progressbar * @li @ref Radio + * + * @image html img/widget/radio/preview-00.png + * @image latex img/widget/radio/preview-00.eps * @li @ref Route * @li @ref Scroller * @li @ref SegmentControl diff --git a/legacy/elementary/doc/widgets/Makefile.am b/legacy/elementary/doc/widgets/Makefile.am index 676d58ee5c..4b07797251 100644 --- a/legacy/elementary/doc/widgets/Makefile.am +++ b/legacy/elementary/doc/widgets/Makefile.am @@ -64,7 +64,8 @@ widget_preview_anchorview \ widget_preview_anchorblock \ widget_preview_flip \ widget_preview_pager \ -widget_preview_separator +widget_preview_separator \ +widget_preview_radio LDADD = $(top_builddir)/src/lib/libelementary.la @ELEMENTARY_EWEATHER_LIBS@ @ELEMENTARY_EDBUS_LIBS@ @ELEMENTARY_EFREET_LIBS@ @ELEMENTARY_LIBS@ @EIO_LIBS@ @my_libs@ @@ -111,5 +112,6 @@ EXTRA_DIST = \ widget_preview_layout.c \ widget_preview_pager.c \ widget_preview_separator.c \ + widget_preview_radio.c \ widget_preview_tmpl_foot.c \ widget_preview_tmpl_head.c diff --git a/legacy/elementary/doc/widgets/widget_preview_radio.c b/legacy/elementary/doc/widgets/widget_preview_radio.c new file mode 100644 index 0000000000..d40667fd0a --- /dev/null +++ b/legacy/elementary/doc/widgets/widget_preview_radio.c @@ -0,0 +1,10 @@ +#include "widget_preview_tmpl_head.c" + +Evas_Object *o = elm_radio_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); + +elm_object_text_set(o, "radio"); + +#include "widget_preview_tmpl_foot.c" diff --git a/legacy/elementary/src/examples/Makefile.am b/legacy/elementary/src/examples/Makefile.am index 83dd5b60b8..9c1f429dd0 100644 --- a/legacy/elementary/src/examples/Makefile.am +++ b/legacy/elementary/src/examples/Makefile.am @@ -78,7 +78,8 @@ SRCS = \ layout_example.edc \ ctxpopup_example_01.c \ pager_example_01.c \ - separator_example_01.c + separator_example_01.c \ + radio_example_01.c pkglib_PROGRAMS = @@ -146,7 +147,8 @@ pkglib_PROGRAMS += \ index_example_01 \ index_example_02 \ pager_example_01 \ - separator_example_01 + separator_example_01 \ + radio_example_01 # This variable will hold the list of screenshots that will be made # by "make screenshots". Each item in the list is of the form: @@ -189,7 +191,8 @@ SCREENSHOTS = \ index_example_02:index_example_03.png:0.3 \ ctxpopup_example_01:ctxpopup_example_01.png:0.0 \ pager_example_01:pager_example_01.png:0.0 \ - separator_example_01:separator_example_01.png:0.0 + separator_example_01:separator_example_01.png:0.0 \ + radio_example_01:radio_example_01.png:0.0 HTML_SS_DIR=$(top_builddir)/doc/html/screenshots LATEX_SS_DIR=$(top_builddir)/doc/latex/screenshots diff --git a/legacy/elementary/src/examples/radio_example_01.c b/legacy/elementary/src/examples/radio_example_01.c new file mode 100644 index 0000000000..40ae042e61 --- /dev/null +++ b/legacy/elementary/src/examples/radio_example_01.c @@ -0,0 +1,92 @@ +//Compile with: +//gcc -g `pkg-config --cflags --libs elementary` radio_example_01.c -o radio_example_01 + +#include +#ifdef HAVE_CONFIG_H +# include "elementary_config.h" +#endif + +static int val = 1; + +static void _cb(void *data, Evas_Object *obj, void *event_info); + +EAPI int +elm_main(int argc, char **argv) +{ + Evas_Object *win, *bg, *bx, *radio, *group, *ic; + + win = elm_win_add(NULL, "radio", ELM_WIN_BASIC); + elm_win_title_set(win, "Radio"); + elm_win_autodel_set(win, EINA_TRUE); + elm_policy_set(ELM_POLICY_QUIT, ELM_POLICY_QUIT_LAST_WINDOW_CLOSED); + + bg = elm_bg_add(win); + elm_win_resize_object_add(win, bg); + evas_object_show(bg); + + bx = elm_box_add(win); + elm_box_horizontal_set(bx, EINA_TRUE); + evas_object_size_hint_weight_set(bx, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND); + evas_object_size_hint_align_set(bx, EVAS_HINT_FILL, EVAS_HINT_FILL); + elm_win_resize_object_add(win, bx); + evas_object_show(bx); + + group = radio = elm_radio_add(win); + elm_object_text_set(radio, "Radio 1"); + elm_radio_state_value_set(radio, 1); + elm_radio_value_pointer_set(radio, &val); + ic = elm_icon_add(win); + elm_icon_standard_set(ic, "home"); + elm_radio_icon_set(radio, ic); + elm_box_pack_end(bx, radio); + evas_object_size_hint_weight_set(radio, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND); + evas_object_size_hint_align_set(radio, EVAS_HINT_FILL, EVAS_HINT_FILL); + evas_object_show(radio); + evas_object_smart_callback_add(radio, "changed", _cb, NULL); + + radio = elm_radio_add(win); + elm_object_text_set(radio, "Radio 2"); + elm_radio_state_value_set(radio, 2); + elm_radio_value_pointer_set(radio, &val); + elm_radio_group_add(radio, group); + ic = elm_icon_add(win); + elm_icon_standard_set(ic, "file"); + elm_radio_icon_set(radio, ic); + elm_box_pack_end(bx, radio); + evas_object_size_hint_weight_set(radio, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND); + evas_object_size_hint_align_set(radio, EVAS_HINT_FILL, EVAS_HINT_FILL); + evas_object_show(radio); + evas_object_smart_callback_add(radio, "changed", _cb, NULL); + + radio = elm_radio_add(win); + elm_object_text_set(radio, "Radio 3"); + elm_radio_state_value_set(radio, 3); + elm_radio_value_pointer_set(radio, &val); + elm_radio_group_add(radio, group); + elm_box_pack_end(bx, radio); + evas_object_size_hint_weight_set(radio, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND); + evas_object_size_hint_align_set(radio, EVAS_HINT_FILL, EVAS_HINT_FILL); + evas_object_show(radio); + evas_object_smart_callback_add(radio, "changed", _cb, NULL); + + radio = elm_radio_add(win); + elm_object_text_set(radio, "Radio 4"); + elm_radio_state_value_set(radio, 4); + elm_box_pack_end(bx, radio); + evas_object_size_hint_weight_set(radio, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND); + evas_object_size_hint_align_set(radio, EVAS_HINT_FILL, EVAS_HINT_FILL); + evas_object_show(radio); + + evas_object_show(win); + + elm_run(); + + return 0; +} +ELM_MAIN() + +static void +_cb(void *data, Evas_Object *obj, void *event_info) +{ + printf("val is now: %d\n", val); +} diff --git a/legacy/elementary/src/lib/Elementary.h.in b/legacy/elementary/src/lib/Elementary.h.in index bba2f31df6..ac1d6f6ffb 100644 --- a/legacy/elementary/src/lib/Elementary.h.in +++ b/legacy/elementary/src/lib/Elementary.h.in @@ -8617,21 +8617,158 @@ extern "C" { * @} */ - /* radio */ + /** + * @defgroup Radio Radio + * + * @image html img/widget/radio/preview-00.png + * @image latex img/widget/radio/preview-00.eps + * + * @brief Radio is a widget that allows for 1 or more options to be displayed + * and have the user choose only 1 of them. + * + * A radio object contains an indicator, an optional Label and an optional + * icon object. While it's possible to have a group of only one radio they, + * are normally used in groups of 2 or more. To add a radio to a group use + * elm_radio_group_add(). The radio object(s) will select from one of a set + * of integer values, so any value they are configuring needs to be mapped to + * a set of integers. To configure what value that radio object represents, + * use elm_radio_state_value_set() to set the integer it represents. To set + * the value the whole group(which one is currently selected) is to indicate + * use elm_radio_value_set() on any group member, and to get the groups value + * use elm_radio_value_get(). For convenience the radio objects are also able + * to directly set an integer(int) to the value that is selected. To specify + * the pointer to this integer to modify, use elm_radio_value_pointer_set(). + * The radio objects will modify this directly. That implies the pointer must + * point to valid memory for as long as the radio objects exist. + * + * Signals that you can add callbacks for are: + * @li changed - This is called whenever the user changes the state of one of + * the radio objects within the group of radio objects that work together. + * + * @ref tutorial_radio show most of this API in action. + * @{ + */ + /** + * @brief Add a new radio to the parent + * + * @param parent The parent object + * @return The new object or NULL if it cannot be created + */ EAPI Evas_Object *elm_radio_add(Evas_Object *parent) EINA_ARG_NONNULL(1); + /** + * @brief Set the text label of the radio object + * + * @param obj The radio object + * @param label The text label string in UTF-8 + * + * @deprecated use elm_object_text_set() instead. + */ EINA_DEPRECATED EAPI void elm_radio_label_set(Evas_Object *obj, const char *label) EINA_ARG_NONNULL(1); + /** + * @brief Get the text label of the radio object + * + * @param obj The radio object + * @return The text label string in UTF-8 + * + * @deprecated use elm_object_text_set() instead. + */ EINA_DEPRECATED EAPI const char *elm_radio_label_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); + /** + * @brief Set the icon object of the radio object + * + * @param obj The radio object + * @param icon The icon object + * + * Once the icon object is set, a previously set one will be deleted. If you + * want to keep that old content object, use the elm_radio_icon_unset() + * function. + */ EAPI void elm_radio_icon_set(Evas_Object *obj, Evas_Object *icon) EINA_ARG_NONNULL(1); + /** + * @brief Get the icon object of the radio object + * + * @param obj The radio object + * @return The icon object + * + * @see elm_radio_icon_set() + */ EAPI Evas_Object *elm_radio_icon_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); + /** + * @brief Unset the icon used for the radio object + * + * @param obj The radio object + * @return The icon object that was being used + * + * Unparent and return the icon object which was set for this widget. + * + * @see elm_radio_icon_set() + */ EAPI Evas_Object *elm_radio_icon_unset(Evas_Object *obj) EINA_ARG_NONNULL(1); + /** + * @brief Add this radio to a group of other radio objects + * + * @param obj The radio object + * @param group Any object whose group the @p obj is to join. + * + * Radio objects work in groups. Each member should have a different integer + * value assigned. In order to have them work as a group, they need to know + * about each other. This adds the given radio object to the group of which + * the group object indicated is a member. + */ EAPI void elm_radio_group_add(Evas_Object *obj, Evas_Object *group) EINA_ARG_NONNULL(1); + /** + * @brief Set the integer value that this radio object represents + * + * @param obj The radio object + * @param value The value to use if this radio object is selected + * + * This sets the value of the radio. + */ EAPI void elm_radio_state_value_set(Evas_Object *obj, int value) EINA_ARG_NONNULL(1); + /** + * @brief Get the integer value that this radio object represents + * + * @param obj The radio object + * @return The value used if this radio object is selected + * + * This gets the value of the radio. + * + * @see elm_radio_value_set() + */ EAPI int elm_radio_state_value_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); + /** + * @brief Set the value of the radio. + * + * @param obj The radio object + * @param value The value to use for the group + * + * This sets the value of the radio group and will also set the value if + * pointed to, to the value supplied, but will not call any callbacks. + */ EAPI void elm_radio_value_set(Evas_Object *obj, int value) EINA_ARG_NONNULL(1); + /** + * @brief Get the state of the radio object + * + * @param obj The radio object + * @return The integer state + */ EAPI int elm_radio_value_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); + /** + * @brief Set a convenience pointer to a integer to change + * + * @param obj The radio object + * @param valuep Pointer to the integer to modify + * + * This sets a pointer to a integer, that, in addition to the radio objects + * state will also be modified directly. To stop setting the object pointed + * to simply use NULL as the @p valuep argument. If valuep is not NULL, then + * when this is called, the radio objects state will also be modified to + * reflect the value of the integer valuep points to, just like calling + * elm_radio_value_set(). + */ EAPI void elm_radio_value_pointer_set(Evas_Object *obj, int *valuep) EINA_ARG_NONNULL(1); - /* smart callbacks called: - * "changed" - when the radio status is changed + /** + * @} */ /** diff --git a/legacy/elementary/src/lib/elm_radio.c b/legacy/elementary/src/lib/elm_radio.c index 2087fb5609..b22837ea44 100644 --- a/legacy/elementary/src/lib/elm_radio.c +++ b/legacy/elementary/src/lib/elm_radio.c @@ -1,40 +1,6 @@ #include #include "elm_priv.h" -/** - * @defgroup Radio Radio - * - * The radio button allows for 1 or more selectors to be created to select 1 - * of a set of options. - * - * Signals that you can add callbacks for are: - * - * changed - This is called whenever the user changes the state of one of the - * radio objects within the group of radio objects that work together. - * - * A radio object contains an indicator, an optional Label and an optional - * icon object. They work normally in groups of 2 or more. When you create a - * radio (if it is not the first member of the group), simply add it to the - * group by adding it to any other member of the group that already exists - * (or the first member) with elm_radio_group_add() with the second parameter - * being the existing group member. The radio object(s) will select from one - * of a set of integer values, so any value they are configuring needs to be - * mapped to a set of integers. To configure what value that radio object - * represents, use elm_radio_state_value_set() to set the integer it - * represents. To set the value the whole group is to indicate use - * elm_radio_value_set() on any group member, and to get the groups value use - * elm_radio_value_get(). For convenience the radio objects are also able to - * directly set an integer (int) to the value that is selected. To specify - * the pointer to this integer to modify, use elm_radio_value_pointer_set(). - * The radio objects will modify this directly. That implies the pointer must - * point to valid memory for as long as the radio objects exist. - * - * Signals that you can add callbacks for are: - * - * "changed" - when the radio status is changed - * - */ - typedef struct _Widget_Data Widget_Data; typedef struct _Group Group; @@ -305,14 +271,6 @@ _elm_radio_label_get(const Evas_Object *obj, const char *item) return wd->label; } -/** - * Add a new radio to the parent - * - * @param parent The parent object - * @return The new object or NULL if it cannot be created - * - * @ingroup Radio - */ EAPI Evas_Object * elm_radio_add(Evas_Object *parent) { @@ -357,48 +315,18 @@ elm_radio_add(Evas_Object *parent) return obj; } -/** - * Set the text label of the radio object - * - * @param obj The radio object - * @param label The text label string in UTF-8 - * - * @ingroup Radio - * @deprecated use elm_object_text_set() instead. - */ EAPI void elm_radio_label_set(Evas_Object *obj, const char *label) { _elm_radio_label_set(obj, NULL, label); } -/** - * Get the text label of the radio object - * - * @param obj The radio object - * @return The text label string in UTF-8 - * - * @ingroup Radio - * @deprecated use elm_object_text_set() instead. - */ EAPI const char * elm_radio_label_get(const Evas_Object *obj) { return _elm_radio_label_get(obj, NULL); } -/** - * Set the icon object of the radio object - * - * Once the icon object is set, a previously set one will be deleted. - * If you want to keep that old content object, use the - * elm_radio_icon_unset() function. - * - * @param obj The radio object - * @param icon The icon object - * - * @ingroup Radio - */ EAPI void elm_radio_icon_set(Evas_Object *obj, Evas_Object *icon) { @@ -420,14 +348,6 @@ elm_radio_icon_set(Evas_Object *obj, Evas_Object *icon) _sizing_eval(obj); } -/** - * Get the icon object of the radio object - * - * @param obj The radio object - * @return The icon object - * - * @ingroup Radio - */ EAPI Evas_Object * elm_radio_icon_get(const Evas_Object *obj) { @@ -437,16 +357,6 @@ elm_radio_icon_get(const Evas_Object *obj) return wd->icon; } -/** - * Unset the icon used for the radio object - * - * Unparent and return the icon object which was set for this widget. - * - * @param obj The radio object - * @return The icon object that was being used - * - * @ingroup Radio - */ EAPI Evas_Object * elm_radio_icon_unset(Evas_Object *obj) { @@ -461,19 +371,6 @@ elm_radio_icon_unset(Evas_Object *obj) return icon; } -/** - * Add this radio to a group of other radio objects - * - * Radio objects work in groups. Each member should have a different integer - * value assigned. In order ro have them work as a group, they need to know - * about eacthother. This adds the given radio object to the group of which - * the group object indicated is a member. - * - * @param obj The radio object - * @param group The object whose group the object is to join - * - * @ingroup Radio - */ EAPI void elm_radio_group_add(Evas_Object *obj, Evas_Object *group) { @@ -501,16 +398,6 @@ elm_radio_group_add(Evas_Object *obj, Evas_Object *group) else _state_set(obj, 0); } -/** - * Set the integer value that this radio object represents - * - * This sets the value of the radio. - * - * @param obj The radio object - * @param value The value to use if this radio object is selected - * - * @ingroup Radio - */ EAPI void elm_radio_state_value_set(Evas_Object *obj, int value) { @@ -522,16 +409,6 @@ elm_radio_state_value_set(Evas_Object *obj, int value) else _state_set(obj, 0); } -/** - * Get the integer value that this radio object represents - * - * This gets the value of the radio. - * - * @param obj The radio object - * @return The value used if this radio object is selected - * - * @ingroup Radio - */ EAPI int elm_radio_state_value_get(const Evas_Object *obj) { @@ -541,17 +418,6 @@ elm_radio_state_value_get(const Evas_Object *obj) return wd->value; } -/** - * Set the value of the radio. - * - * This sets the value of the radio group and will also set the value if - * pointed to, to the value supplied, but will not call any callbacks. - * - * @param obj The radio object - * @param value The value to use for the group - * - * @ingroup Radio - */ EAPI void elm_radio_value_set(Evas_Object *obj, int value) { @@ -564,14 +430,6 @@ elm_radio_value_set(Evas_Object *obj, int value) _state_set_all(wd); } -/** - * Get the state of the radio object - * - * @param obj The radio object - * @return The integer state - * - * @ingroup Radio - */ EAPI int elm_radio_value_get(const Evas_Object *obj) { @@ -581,21 +439,6 @@ elm_radio_value_get(const Evas_Object *obj) return wd->group->value; } -/** - * Set a convenience pointer to a integer to change - * - * This sets a pointer to a integer, that, in addition to the radio objects - * state will also be modified directly. To stop setting the object pointed - * to simply use NULL as the valuep parameter. If valuep is not NULL, then - * when this is called, the radio objects state will also be modified to - * reflect the value of the integer valuep points to, just like calling - * elm_radio_value_set(). - * - * @param obj The radio object - * @param valuep Pointer to the integer to modify - * - * @ingroup Radio - */ EAPI void elm_radio_value_pointer_set(Evas_Object *obj, int *valuep) {