GtkRadioButton
**************

A choice from multiple check buttons

Overview
========

A single radio button performs the same basic function as a <gtk-check-button>, as its position in the object hierarchy reflects. It is only when multiple radio buttons are grouped together that they become a different user interface component in their own right.

Every radio button is a member of some group of radio buttons. When one is selected, all other radio buttons in the same group are deselected. A <gtk-radio-button> is one way of giving the user a choice from many options.

Radio button widgets are created with gtk-radio-button-new, passing NULL as the argument if this is the first radio button in a group. In subsequent calls, the group you wish to add this button to should be passed as an argument. Optionally, gtk-radio-button-new-with-label can be used if you want a text label on the radio button.

Alternatively, when adding widgets to an existing group of radio buttons, use gtk-radio-button-new-from-widget with a <gtk-radio-button> that already has a group assigned to it. The convenience function gtk-radio-button-new-with-label-from-widget is also provided.

To retrieve the group a <gtk-radio-button> is assigned to, use gtk-radio-button-get-group.

To remove a <gtk-radio-button> from one group and make it part of a new one, use gtk-radio-button-set-group.

The group list does not need to be freed, as each <gtk-radio-button> will remove itself and its list item when it is destroyed.

     void create_radio_buttons (void) {

        GtkWidget *window, *radio1, *radio2, *box, *entry;
        window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
        box = gtk_vbox_new (TRUE, 2);

        /* Create a radio button with a GtkEntry widget */
        radio1 = gtk_radio_button_new (NULL);
        entry = gtk_entry_new ();
        gtk_container_add (GTK_CONTAINER (radio1), entry);

        /* Create a radio button with a label */
        radio2 = gtk_radio_button_new_with_label_from_widget (GTK_RADIO_BUTTON (radio1),
     							"I'm the second radio button.");

        /* Pack them into a box, then show all the widgets */
        gtk_box_pack_start (GTK_BOX (box), radio1, TRUE, TRUE, 2);
        gtk_box_pack_start (GTK_BOX (box), radio2, TRUE, TRUE, 2);
        gtk_container_add (GTK_CONTAINER (window), box);
        gtk_widget_show_all (window);
        return;
     }

When an unselected button in the group is clicked the clicked button receives the "toggled" signal, as does the previously selected button. Inside the "toggled" handler, gtk-toggle-button-get-active can be used to determine if the button has been selected or deselected.

Usage
=====

     [file defuns-gtkradiobutton.xml.texi not included]