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 <structname>GtkToggleButton</structname> 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);
   
   g_signal_connect (GTK_OBJECT (toggle1), "toggled",
                     G_CALLBACK (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);
   g_signal_connect (GTK_OBJECT (toggle2), "toggled",
                     G_CALLBACK (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_new_with_mnemonic ##### -->
<para>

</para>

@label: 
@Returns: 


<!-- ##### 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.


<!-- ##### FUNCTION gtk_toggle_button_get_mode ##### -->
<para>

</para>

@toggle_button: 
@Returns: 


<!-- ##### MACRO gtk_toggle_button_set_state ##### -->
<para>
This is a deprecated macro, and is only maintained for compatibility 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.


<!-- ##### FUNCTION gtk_toggle_button_get_inconsistent ##### -->
<para>

</para>

@toggle_button: 
@Returns: 


<!-- ##### FUNCTION gtk_toggle_button_set_inconsistent ##### -->
<para>

</para>

@toggle_button: 
@setting: 


<!-- ##### 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:inconsistent ##### -->
<para>

</para>

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