gtk2/docs/reference/gtk/tmpl/gtktogglebutton.sgml

<!-- ##### SECTION Title ##### -->
GtkToggleButton

<!-- ##### SECTION Short_Description ##### -->
create buttons which retain their state.

<!-- ##### SECTION Long_Description ##### -->
<para>
A #GtkToggleButton is a #GtkButton which will remain 'pressed-in' when
clicked. Clicking again will cause the toggle button to return to it's
normal state.
</para>
<para>
A toggle button is created by calling either gtk_toggle_button_new() or
gtk_toggle_button_new_with_label(). If using the former, it is advisable to
pack a widget, (such as a #GtkLabel and/or a #GtkPixmap), into the toggle
button's container. (See #GtkButton for more information).
</para>
<para>
The state of a #GtkToggleButton can be set specifically using
gtk_toggle_button_set_active(), and retrieved using
gtk_toggle_button_get_active().
</para>
<para>
To simply switch the state of a toggle button, use gtk_toggle_button_toggled.
</para>
<example>
<title>Creating two #GtkToggleButton widgets.</title>
<programlisting>

void make_toggles(void) {
   GtkWidget *dialog, *toggle1, *toggle2;

   dialog = gtk_dialog_new();
   toggle1 = gtk_toggle_button_new_with_label("Hi, i'm a toggle button.");

   /* Makes this toggle button invisible */
   gtk_toggle_button_set_mode (GTK_TOGGLE_BUTTON (toggle1), TRUE);
   
   gtk_signal_connect (GTK_OBJECT (toggle1), "toggled",
                       GTK_SIGNAL_FUNC (output_state), NULL);
   gtk_box_pack_start (GTK_BOX (GTK_DIALOG(dialog)->action_area),
                       toggle1, FALSE, FALSE, 2);

   toggle2 = gtk_toggle_button_new_with_label("Hi, i'm another toggle button.");
   gtk_toggle_button_set_mode (GTK_TOGGLE_BUTTON (toggle2), FALSE);
   gtk_signal_connect (GTK_OBJECT (toggle2), "toggled",
                       GTK_SIGNAL_FUNC (output_state), NULL);
   gtk_box_pack_start (GTK_BOX (GTK_DIALOG(dialog)->action_area),
                       toggle2, FALSE, FALSE, 2);

   gtk_widget_show_all (dialog);
}

</programlisting>
</example>

<!-- ##### SECTION See_Also ##### -->
<para>
<variablelist>
<varlistentry>
<term>#GtkButton</term>
<listitem><para>a more general button.</para></listitem>
</varlistentry>
<varlistentry>
<term>#GtkCheckButton</term>
<listitem><para>another way of presenting a toggle option.</para></listitem>
</varlistentry>
<varlistentry>
<term>#GtkCheckMenuItem</term>
<listitem><para>a #GtkToggleButton  as a menu item.</para></listitem>
</varlistentry>
</variablelist>
</para>

<!-- ##### STRUCT GtkToggleButton ##### -->
<para>
The #GtkToggleButton struct contains private data only, and should be manipulated using the functions below.
</para>


<!-- ##### FUNCTION gtk_toggle_button_new ##### -->
<para>
Creates a new toggle button. A widget should be packed into the button, as in gtk_button_new().
</para>

@Returns: a new toggle button.


<!-- ##### FUNCTION gtk_toggle_button_new_with_label ##### -->
<para>
Creates a new toggle button with a text label.
</para>

@label: a string containing the message to be placed in the toggle button.
@Returns: a new toggle button.


<!-- ##### FUNCTION gtk_toggle_button_set_mode ##### -->
<para>
Determines whether or not the toggle button is drawn on screen. The default mode is FALSE, which results in the button being displayed. To make the button invisible, set <structfield>draw_indicator</structfield> to TRUE.
</para>

@toggle_button: a #GtkToggleButton.
@draw_indicator: TRUE or FALSE.


<!-- ##### MACRO gtk_toggle_button_set_state ##### -->
<para>
This is a deprecated macro, and is only maintained for compatability reasons.
</para>



<!-- ##### FUNCTION gtk_toggle_button_toggled ##### -->
<para>
Emits the <link linkend="GtkToggleButton-toggled">toggled</link>
signal on the #GtkToggleButton. There is no good reason for an
application ever to call this function.
</para>

@toggle_button: a #GtkToggleButton.


<!-- ##### FUNCTION gtk_toggle_button_get_active ##### -->
<para>
Queries a #GtkToggleButton and returns it's current state. Returns TRUE if
the toggle button is pressed in and FALSE if it is raised.
</para>

@toggle_button: a #GtkToggleButton.
@Returns: a #gboolean value.


<!-- ##### FUNCTION gtk_toggle_button_set_active ##### -->
<para>
Sets the status of the toggle button. Set to TRUE if you want the
GtkToggleButton to be 'pressed in', and FALSE to raise it.
This action causes the toggled signal to be emitted.
</para>

@toggle_button: a #GtkToggleButton.
@is_active: TRUE or FALSE.


<!-- ##### SIGNAL GtkToggleButton::toggled ##### -->
<para>
Should be connected if you wish to perform an action whenever the
#GtkToggleButton's state is changed.
</para>

@togglebutton: the object which received the signal.

<!-- ##### ARG GtkToggleButton:active ##### -->
<para>
Sets whether the toggle button should be pressed in or not.
</para>

<!-- ##### ARG GtkToggleButton:draw-indicator ##### -->
<para>
A value of TRUE causes the toggle button to be invisible. FALSE displays it
again.
</para>