From ff97b0ed3dec3e156c9400dba745660643557fd2 Mon Sep 17 00:00:00 2001 From: Xavi Artigas Date: Fri, 31 May 2019 11:18:24 +0000 Subject: [PATCH] Efl.Ui.Radio: Update docs Ref T7867 Reviewed-by: Marcel Hollerbach Differential Revision: https://phab.enlightenment.org/D9061 --- src/lib/elementary/efl_ui_radio.eo | 38 ++++++++++----- src/lib/elementary/efl_ui_radio_box.eo | 8 +++- src/lib/elementary/efl_ui_radio_group.eo | 46 ++++++++++++------- src/lib/elementary/efl_ui_radio_group_impl.eo | 2 + 4 files changed, 63 insertions(+), 31 deletions(-) diff --git a/src/lib/elementary/efl_ui_radio.eo b/src/lib/elementary/efl_ui_radio.eo index bd7475775c..790d2237f6 100644 --- a/src/lib/elementary/efl_ui_radio.eo +++ b/src/lib/elementary/efl_ui_radio.eo @@ -1,22 +1,36 @@ class @beta Efl.Ui.Radio extends Efl.Ui.Check implements Efl.Access.Widget.Action { - [[Elementary radio class]] + [[Elementary radio button class. + + Radio buttons are like check boxes in that they can be either checked or unchecked. + However, radio buttons are always bunched together in groups, and only one button in + each group can be checked at any given time. Pressing a different button in the group + will automatically uncheck any previously checked button. + + They are a common way to allow a user to select one option among a list. + + To handle button grouping, you can either use an @Efl.Ui.Radio_Group object (obtained + through @.group_create) or use more convenient widgets like @Efl.Ui.Radio_Box. + ]] methods { @property state_value { - set { - [[Set the integer value that this radio object represents. + [[Integer value that this radio button represents. - This sets the value of the radio. - ]] - } - get { - [[Get the integer value that this radio object represents. + Each radio button in a group must have a unique value. The selected button in a group + can then be set or retrieved through the @Efl.Ui.Radio_Group.selected_value property. + This value is also informed through the @[Efl.Ui.Radio_Group.value,changed] event. - This gets the value of the radio. - ]] - } + All non-negative values are legal but keep in mind that 0 is the starting value for all new groups: + If no button in the group has this value, then no button in the group is initially + selected. -1 is the value that @Efl.Ui.Radio_Group.selected_value returns when no button + is selected and therefore cannot be used. + ]] + set {} + get {} values { - value: int; [[The value to use if this radio object is selected.]] + value: int; [[The value to use when this radio button is selected. + Any value can be used but 0 and -1 have special meanings as described + above.]] } } } diff --git a/src/lib/elementary/efl_ui_radio_box.eo b/src/lib/elementary/efl_ui_radio_box.eo index 07cfb81bbc..aa2d91c835 100644 --- a/src/lib/elementary/efl_ui_radio_box.eo +++ b/src/lib/elementary/efl_ui_radio_box.eo @@ -1,7 +1,11 @@ class @beta Efl.Ui.Radio_Box extends Efl.Ui.Box implements Efl.Ui.Radio_Group { - methods { - } + [[A standard @Efl.Ui.Box container which automatically handles grouping of any @Efl.Ui.Radio + widget added to it. + + All @Efl.Ui.Radio widgets are added to the same internal group which you only indirectly + access through this object. + ]] implements { Efl.Pack.pack_clear; Efl.Pack.unpack_all; diff --git a/src/lib/elementary/efl_ui_radio_group.eo b/src/lib/elementary/efl_ui_radio_group.eo index c19636308c..34f0d7b907 100644 --- a/src/lib/elementary/efl_ui_radio_group.eo +++ b/src/lib/elementary/efl_ui_radio_group.eo @@ -1,50 +1,62 @@ interface @beta Efl.Ui.Radio_Group { - [[A object for organising a group of radio buttons + [[Interface for manually handling a group of @Efl.Ui.Radio buttons. - A group of radio buttons is a set of pair-wise different values. (Where values are the assosiated values of each radio button) - At any point of time only 1 or 0 buttons can be selected. If a new button is selected, the previous selected button will be unselected. + See the documentation of @Efl.Ui.Radio for an explanation of radio button grouping. ]] methods { @property selected_object { - [[Which object is currently selected in the group + [[Currently selected button in a radio button group, or $NULL if no button is selected. - $NULL if no object is selected. + See also @.selected_value. ]] values { - selected_object : Efl.Ui.Radio; [[The selected radio button in the group, $NULL for no object]] + selected_object : Efl.Ui.Radio; [[The currently selected radio button in the group, or $NULL.]] } } @property selected_value { - [[Each group has a selected value, representing which radio group is selected. + [[The value associated with the currently selected button in the group. + Give each radio button in the group a different value using @Efl.Ui.Radio.state_value. - A value of -1 here does represent that no button is selected. - Possible values here are only those that are assisiated with a registered radio button. + A value of -1 means that no button is selected. + Only values associated with the buttons in the group (and -1) can be used. ]] values { - selected_value : int; [[The value of the selection state]] + selected_value : int; [[The value of the currently selected radio button, or -1.]] } } register { - [[Register a new radio button to this group. + [[Register a new @Efl.Ui.Radio button to this group. + Keep in mind that registering to a group will only handle button grouping, you still + need to add the button to a layout for it to be rendered. - The assosiated value of the radio button must not collide with any other assosiated value of registered buttons. + If the @Efl.Ui.Radio.state_value of the new button is already used by a previous + button in the group, the button will not be added. + + See also @.unregister. ]] params { - radio : Efl.Ui.Radio; [[The radio button to regsiter]] + radio : Efl.Ui.Radio; [[The radio button to add to the group.]] } } unregister { - [[Unregsiter a before registered button from this group. + [[Unregister an @Efl.Ui.Radio button from this group. + This will unlink the behavior of this button from the other buttons in the group, + but if it still belongs to a layout, it will still be rendered. - if the button was selected before, no object will be selected afterwards. + If the button was not registered in the group the call is ignored. + If the button was selected, no button will be selected in the group after this call. + + See also @.register. ]] params { - radio : Efl.Ui.Radio; [[The radio button to unregister]] + radio : Efl.Ui.Radio; [[The radio button to remove from the group.]] } } } events { - value,changed : int; [[Emitted each time the $selected_value has changed.]] + value,changed : int; [[Emitted each time the $selected_value changes. The event information + contains the @Efl.Ui.Radio.state_value of the newly selected button or + -1 if no button is now selected.]] } } diff --git a/src/lib/elementary/efl_ui_radio_group_impl.eo b/src/lib/elementary/efl_ui_radio_group_impl.eo index 82204cf386..bc41093526 100644 --- a/src/lib/elementary/efl_ui_radio_group_impl.eo +++ b/src/lib/elementary/efl_ui_radio_group_impl.eo @@ -1,5 +1,7 @@ class @beta Efl.Ui.Radio_Group_Impl extends Efl.Object implements Efl.Ui.Radio_Group { + [[Object with the default implementation for @Efl.Ui.Radio_Group. + ]] implements { class.constructor; Efl.Object.destructor;