Efl.Ui.Radio: Update docs

Ref T7867

Reviewed-by: Marcel Hollerbach <mail@marcel-hollerbach.de>
Differential Revision: https://phab.enlightenment.org/D9061

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 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.
 
-          if the button was selected before, no object will be selected afterwards.
+          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;