<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>Toggle Buttons</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
REL="HOME"
TITLE="GTK+ 2.0 Tutorial"
HREF="book1.html"><LINK
REL="UP"
TITLE="The Button Widget"
HREF="c489.html"><LINK
REL="PREVIOUS"
TITLE="The Button Widget"
HREF="c489.html"><LINK
REL="NEXT"
TITLE="Check Buttons"
HREF="x535.html"></HEAD
><BODY
CLASS="SECT1"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>GTK+ 2.0 Tutorial</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="c489.html"
ACCESSKEY="P"
><<< Previous</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
>The Button Widget</TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="x535.html"
ACCESSKEY="N"
>Next >>></A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="SEC-TOGGLEBUTTONS"
>Toggle Buttons</A
></H1
><P
>Toggle buttons are derived from normal buttons and are very similar,
except they will always be in one of two states, alternated by a
click. They may be depressed, and when you click again, they will pop
back up. Click again, and they will pop back down.</P
><P
>Toggle buttons are the basis for check buttons and radio buttons, as
such, many of the calls used for toggle buttons are inherited by radio
and check buttons. I will point these out when we come to them.</P
><P
>Creating a new toggle button:</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>GtkWidget *gtk_toggle_button_new( void );
GtkWidget *gtk_toggle_button_new_with_label( const gchar *label );
GtkWidget *gtk_toggle_button_new_with_mnemonic( const gchar *label );</PRE
></TD
></TR
></TABLE
><P
>As you can imagine, these work identically to the normal button widget
calls. The first creates a blank toggle button, and the last two, a
button with a label widget already packed into it. The _mnemonic() variant
additionally parses the label for '_'-prefixed mnemonic characters.</P
><P
>To retrieve the state of the toggle widget, including radio and check
buttons, we use a construct as shown in our example below. This tests
the state of the toggle button, by accessing the <TT
CLASS="LITERAL"
>active</TT
> field of the
toggle widget's structure, after first using the
<TT
CLASS="LITERAL"
>GTK_TOGGLE_BUTTON</TT
> macro to cast the widget pointer into a toggle
widget pointer. The signal of interest to us emitted by toggle
buttons (the toggle button, check button, and radio button widgets) is
the "toggled" signal. To check the state of these buttons, set up a
signal handler to catch the toggled signal, and access the structure
to determine its state. The callback will look something like:</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>void toggle_button_callback (GtkWidget *widget, gpointer data)
{
if (gtk_toggle_button_get_active (GTK_TOGGLE_BUTTON (widget)))
{
/* If control reaches here, the toggle button is down */
} else {
/* If control reaches here, the toggle button is up */
}
}</PRE
></TD
></TR
></TABLE
><P
>To force the state of a toggle button, and its children, the radio and
check buttons, use this function:</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>void gtk_toggle_button_set_active( GtkToggleButton *toggle_button,
gboolean is_active );</PRE
></TD
></TR
></TABLE
><P
>The above call can be used to set the state of the toggle button, and
its children the radio and check buttons. Passing in your created
button as the first argument, and a TRUE or FALSE for the second state
argument to specify whether it should be down (depressed) or up
(released). Default is up, or FALSE.</P
><P
>Note that when you use the gtk_toggle_button_set_active() function, and
the state is actually changed, it causes the "clicked" and "toggled"
signals to be emitted from the button.</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>gboolean gtk_toggle_button_get_active (GtkToggleButton *toggle_button);</PRE
></TD
></TR
></TABLE
><P
>This returns the current state of the toggle button as a boolean
TRUE/FALSE value.</P
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="c489.html"
ACCESSKEY="P"
><<< Previous</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="book1.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="x535.html"
ACCESSKEY="N"
>Next >>></A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>The Button Widget</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="c489.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Check Buttons</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>