[gtkmm-documentation/wip/dboles/radiobutton-group: 2/2] Redo odd wording @ RadioBut.set_group(get_group())



commit 3d1ea6bbce97d78d5673cc552516a5a4cff1f58d
Author: Daniel Boles <dboles src gmail com>
Date:   Fri Jun 28 18:39:29 2019 +0100

    Redo odd wording @ RadioBut.set_group(get_group())
    
    constness isn't the issue here; rather it is the value class of the
    argument of set_group(). That method needs an lvalue reference as it
    modifies the Group by adding the RadioButton to it. That's why we can't
    `rb2.set_group( rb1.get_group() )`. But we can store the Group returned
    by get_group() in a variable and then pass that to set_group() calls.
    Not that there is much reason to, given join_group(), but it works fine.
    
    Then I got carried away and added a program listing showing it
    working... which, while mostly superfluous, does provide a nice
    opportunity to explain briefly that RadioButtonGroup is a handle type,
    meaning that it can be declared automatically and discarded by RAII
    without worrying about thusly releasing the RadioButtons from itself.
    That then informs readers for the next example that creates a new Group.
    
    This is the first use of either "lvalue" or "rvalue" in the docbook!
    That's either a good thing or a slippery, slippery slope to start on...

 docs/tutorial/C/index-in.docbook | 25 ++++++++++++++++++++++++-
 1 file changed, 24 insertions(+), 1 deletion(-)
---
diff --git a/docs/tutorial/C/index-in.docbook b/docs/tutorial/C/index-in.docbook
index 244903e..2d9fd59 100644
--- a/docs/tutorial/C/index-in.docbook
+++ b/docs/tutorial/C/index-in.docbook
@@ -1008,10 +1008,33 @@ same group by using <methodname>join_group()</methodname> to tell the other
 </para>
 
 <para>
+The purpose of <methodname>join_group()</methodname> is to make it easier to
+express that you want a given button to use a group established by another.
+There is another way to do this, using <methodname>get_group()</methodname>
+and <methodname>get_group()</methodname>. However, this has a pitfall:
 Note that you can't do
 <programlisting>rb2.set_group(rb1.get_group());</programlisting>
 because <methodname>get_group()</methodname> returns a <classname>RadioButton::Group</classname>
-which is modified by <methodname>set_group()</methodname> and therefore is non-const.
+by value, and an unnamed rvalue cannot be passed as the lvalue reference needed
+by <methodname>set_group()</methodname>. Instead, you must assign the result of
+<methodname>get_group()</methodname> to a variable and pass that to
+<methodname>set_group()</methodname> as an lvalue:
+</para>
+
+<programlisting>
+Gtk::RadioButton rb1("button1");
+Gtk::RadioButton rb2("button2");
+Gtk::RadioButton rb3("button3");
+auto group = rb1.get_group();
+rb2.set_group(group);
+rb3.set_group(group);
+</programlisting>
+
+<para>
+This works because the group is really a handle and therefore can be discarded
+once it has been used to tell the radio buttons to group with each other. Still,
+as <methodname>join_group()</methodname> does the same thing in one less line,
+you might not find much use for this pattern, but it is shown for completeness.
 </para>
 
 <para>


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]