[gtk+] radio-menu-item: Add join_group()

[Matthias Clasen <matthiasc src gnome org>]

commit 5c5464a469c57cbc95096bd15d83b021c0cf73a3
Author: Matthias Clasen <mclasen redhat com>
Date:   Sun Mar 22 01:57:57 2015 -0400

    radio-menu-item: Add join_group()
    
    The other Radio* widgets have this convenience method that removes the
    memory management of the opaque GSList used to handle the group from the
    API usable from language bindings (especially the ones not based on
    introspection).
    
    This commit adds gtk_radio_menu_item_join_group().
    
    https://bugzilla.gnome.org/show_bug.cgi?id=671362

 demos/gtk-demo/menus.c               |   21 +++++++-----
 docs/reference/gtk/gtk3-sections.txt |    1 +
 gtk/gtkradiomenuitem.c               |   56 ++++++++++++++++++++++++++++++++++
 gtk/gtkradiomenuitem.h               |    4 ++
 4 files changed, 73 insertions(+), 9 deletions(-)
---
diff --git a/demos/gtk-demo/menus.c b/demos/gtk-demo/menus.c
index 7fd9553..44b352f 100644
--- a/demos/gtk-demo/menus.c
+++ b/demos/gtk-demo/menus.c
@@ -33,8 +33,7 @@ static GtkWidget *
 create_menu (gint     depth)
 {
   GtkWidget *menu;
-  GtkWidget *menuitem;
-  GSList *group;
+  GtkRadioMenuItem *last_item;
   char buf[32];
   int i, j;
 
@@ -42,20 +41,24 @@ create_menu (gint     depth)
     return NULL;
 
   menu = gtk_menu_new ();
-  group = NULL;
+  last_item = NULL;
 
   for (i = 0, j = 1; i < 5; i++, j++)
     {
+      GtkWidget *menu_item;
+
       sprintf (buf, "item %2d - %d", depth, j);
-      menuitem = gtk_radio_menu_item_new_with_label (group, buf);
-      group = gtk_radio_menu_item_get_group (GTK_RADIO_MENU_ITEM (menuitem));
 
-      gtk_menu_shell_append (GTK_MENU_SHELL (menu), menuitem);
-      gtk_widget_show (menuitem);
+      menu_item = gtk_radio_menu_item_new_with_label_from_widget (NULL, buf);
+      gtk_radio_menu_item_join_group (GTK_RADIO_MENU_ITEM (menu_item), last_item);
+      last_item = GTK_RADIO_MENU_ITEM (menu_item);
+
+      gtk_menu_shell_append (GTK_MENU_SHELL (menu), menu_item);
+      gtk_widget_show (menu_item);
       if (i == 3)
-        gtk_widget_set_sensitive (menuitem, FALSE);
+        gtk_widget_set_sensitive (menu_item, FALSE);
 
-      gtk_menu_item_set_submenu (GTK_MENU_ITEM (menuitem), create_menu (depth - 1));
+      gtk_menu_item_set_submenu (GTK_MENU_ITEM (menu_item), create_menu (depth - 1));
     }
 
   return menu;
diff --git a/docs/reference/gtk/gtk3-sections.txt b/docs/reference/gtk/gtk3-sections.txt
index e2d0435..fb6ffd7 100644
--- a/docs/reference/gtk/gtk3-sections.txt
+++ b/docs/reference/gtk/gtk3-sections.txt
@@ -2771,6 +2771,7 @@ gtk_radio_menu_item_new_with_label_from_widget
 gtk_radio_menu_item_new_with_mnemonic_from_widget
 gtk_radio_menu_item_set_group
 gtk_radio_menu_item_get_group
+gtk_radio_menu_item_join_group
 <SUBSECTION Standard>
 GTK_RADIO_MENU_ITEM
 GTK_IS_RADIO_MENU_ITEM
diff --git a/gtk/gtkradiomenuitem.c b/gtk/gtkradiomenuitem.c
index da37120..27320f0 100644
--- a/gtk/gtkradiomenuitem.c
+++ b/gtk/gtkradiomenuitem.c
@@ -558,3 +558,59 @@ gtk_radio_menu_item_activate (GtkMenuItem *menu_item)
 
   gtk_widget_queue_draw (GTK_WIDGET (radio_menu_item));
 }
+
+/**
+ * gtk_radio_menu_item_join_group:
+ * @radio_menu_item: a #GtkRadioMenuItem
+ * @group_source: (allow-none): a #GtkRadioMenuItem whose group we are
+ *   joining, or %NULL to remove the @radio_menu_item from its current
+ *   group
+ *
+ * Joins a #GtkRadioMenuItem object to the group of another #GtkRadioMenuItem
+ * object.
+ *
+ * This function should be used by language bindings to avoid the memory
+ * manangement of the opaque #GSList of gtk_radio_menu_item_get_group()
+ * and gtk_radio_menu_item_set_group().
+ *
+ * A common way to set up a group of #GtkRadioMenuItem instances is:
+ *
+ * |[
+ *   GtkRadioMenuItem *last_item = NULL;
+ *
+ *   while ( ...more items to add... )
+ *     {
+ *       GtkRadioMenuItem *radio_item;
+ *
+ *       radio_item = gtk_radio_menu_item_new (...);
+ *
+ *       gtk_radio_menu_item_join_group (radio_item, last_item);
+ *       last_item = radio_item;
+ *     }
+ * ]|
+ *
+ * Since: 3.18
+ */
+void
+gtk_radio_menu_item_join_group (GtkRadioMenuItem *radio_menu_item,
+                                GtkRadioMenuItem *group_source)
+{
+  g_return_if_fail (GTK_IS_RADIO_MENU_ITEM (radio_menu_item));
+  g_return_if_fail (group_source == NULL || GTK_IS_RADIO_MENU_ITEM (group_source));
+
+  if (group_source != NULL)
+    {
+      GSList *group = gtk_radio_menu_item_get_group (group_source);
+
+      if (group == NULL)
+        {
+          /* if the group source does not have a group, we force one */
+          gtk_radio_menu_item_set_group (group_source, NULL);
+          group = gtk_radio_menu_item_get_group (group_source);
+        }
+
+      gtk_radio_menu_item_set_group (radio_menu_item, group);
+    }
+  else
+    gtk_radio_menu_item_set_group (radio_menu_item, NULL);
+}
diff --git a/gtk/gtkradiomenuitem.h b/gtk/gtkradiomenuitem.h
index fc29be8..b3fe990 100644
--- a/gtk/gtkradiomenuitem.h
+++ b/gtk/gtkradiomenuitem.h
@@ -95,6 +95,10 @@ GDK_AVAILABLE_IN_ALL
 void       gtk_radio_menu_item_set_group                     (GtkRadioMenuItem *radio_menu_item,
                                                              GSList           *group);
 
+GDK_AVAILABLE_IN_3_18
+void       gtk_radio_menu_item_join_group                    (GtkRadioMenuItem *radio_menu_item,
+                                                              GtkRadioMenuItem *group_source);
+
 G_END_DECLS
 
 #endif /* __GTK_RADIO_MENU_ITEM_H__ */