Pileus Git - ~andy/gtk/blob - docs/reference/gtk/tmpl/gtktogglebutton.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 GtkToggleButton
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 create buttons which retain their state.
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 A #GtkToggleButton is a #GtkButton which will remain 'pressed-in' when
  10 clicked. Clicking again will cause the toggle button to return to it's
  11 normal state.
  12 </para>
  13 <para>
  14 A toggle button is created by calling either gtk_toggle_button_new() or
  15 gtk_toggle_button_new_with_label(). If using the former, it is advisable to
  16 pack a widget, (such as a #GtkLabel and/or a #GtkPixmap), into the toggle
  17 button's container. (See #GtkButton for more information).
  18 </para>
  19 <para>
  20 The state of a #GtkToggleButton can be set specifically using
  21 gtk_toggle_button_set_active(), and retrieved using
  22 gtk_toggle_button_get_active().
  23 </para>
  24 <para>
  25 To simply switch the state of a toggle button, use gtk_toggle_button_toggled.
  26 </para>
  27 <example>
  28 <title>Creating two <structname>GtkToggleButton</structname> widgets.</title>
  29 <programlisting>
  30
  31 void make_toggles (void) {
  32    GtkWidget *dialog, *toggle1, *toggle2;
  33
  34    dialog = gtk_dialog_new (<!-- -->);
  35    toggle1 = gtk_toggle_button_new_with_label ("Hi, i'm a toggle button.");
  36
  37    /* Makes this toggle button invisible */
  38    gtk_toggle_button_set_mode (GTK_TOGGLE_BUTTON (toggle1), TRUE);
  39
  40    g_signal_connect (GTK_OBJECT (toggle1), "toggled",
  41                      G_CALLBACK (output_state), NULL);
  42    gtk_box_pack_start (GTK_BOX (GTK_DIALOG (dialog)->action_area),
  43                        toggle1, FALSE, FALSE, 2);
  44
  45    toggle2 = gtk_toggle_button_new_with_label ("Hi, i'm another toggle button.");
  46    gtk_toggle_button_set_mode (GTK_TOGGLE_BUTTON (toggle2), FALSE);
  47    g_signal_connect (GTK_OBJECT (toggle2), "toggled",
  48                      G_CALLBACK (output_state), NULL);
  49    gtk_box_pack_start (GTK_BOX (GTK_DIALOG (dialog)->action_area),
  50                        toggle2, FALSE, FALSE, 2);
  51
  52    gtk_widget_show_all (dialog);
  53 }
  54
  55 </programlisting>
  56 </example>
  57
  58 <!-- ##### SECTION See_Also ##### -->
  59 <para>
  60 <variablelist>
  61 <varlistentry>
  62 <term>#GtkButton</term>
  63 <listitem><para>a more general button.</para></listitem>
  64 </varlistentry>
  65 <varlistentry>
  66 <term>#GtkCheckButton</term>
  67 <listitem><para>another way of presenting a toggle option.</para></listitem>
  68 </varlistentry>
  69 <varlistentry>
  70 <term>#GtkCheckMenuItem</term>
  71 <listitem><para>a #GtkToggleButton  as a menu item.</para></listitem>
  72 </varlistentry>
  73 </variablelist>
  74 </para>
  75
  76 <!-- ##### STRUCT GtkToggleButton ##### -->
  77 <para>
  78 The #GtkToggleButton struct contains private data only, and should be manipulated using the functions below.
  79 </para>
  80
  81
  82 <!-- ##### FUNCTION gtk_toggle_button_new ##### -->
  83 <para>
  84 Creates a new toggle button. A widget should be packed into the button, as in gtk_button_new().
  85 </para>
  86
  87 @Returns: a new toggle button.
  88
  89
  90 <!-- ##### FUNCTION gtk_toggle_button_new_with_label ##### -->
  91 <para>
  92 Creates a new toggle button with a text label.
  93 </para>
  94
  95 @label: a string containing the message to be placed in the toggle button.
  96 @Returns: a new toggle button.
  97
  98
  99 <!-- ##### FUNCTION gtk_toggle_button_new_with_mnemonic ##### -->
 100 <para>
 101
 102 </para>
 103
 104 @label:
 105 @Returns:
 106
 107
 108 <!-- ##### FUNCTION gtk_toggle_button_set_mode ##### -->
 109 <para>
 110 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.
 111 </para>
 112
 113 @toggle_button: a #GtkToggleButton.
 114 @draw_indicator: %TRUE or %FALSE.
 115
 116
 117 <!-- ##### FUNCTION gtk_toggle_button_get_mode ##### -->
 118 <para>
 119
 120 </para>
 121
 122 @toggle_button:
 123 @Returns:
 124
 125
 126 <!-- ##### MACRO gtk_toggle_button_set_state ##### -->
 127 <para>
 128 This is a deprecated macro, and is only maintained for compatibility reasons.
 129 </para>
 130
 131
 132
 133 <!-- ##### FUNCTION gtk_toggle_button_toggled ##### -->
 134 <para>
 135 Emits the <link linkend="GtkToggleButton-toggled">toggled</link>
 136 signal on the #GtkToggleButton. There is no good reason for an
 137 application ever to call this function.
 138 </para>
 139
 140 @toggle_button: a #GtkToggleButton.
 141
 142
 143 <!-- ##### FUNCTION gtk_toggle_button_get_active ##### -->
 144 <para>
 145 Queries a #GtkToggleButton and returns it's current state. Returns %TRUE if
 146 the toggle button is pressed in and %FALSE if it is raised.
 147 </para>
 148
 149 @toggle_button: a #GtkToggleButton.
 150 @Returns: a #gboolean value.
 151
 152
 153 <!-- ##### FUNCTION gtk_toggle_button_set_active ##### -->
 154 <para>
 155 Sets the status of the toggle button. Set to %TRUE if you want the
 156 GtkToggleButton to be 'pressed in', and %FALSE to raise it.
 157 This action causes the toggled signal to be emitted.
 158 </para>
 159
 160 @toggle_button: a #GtkToggleButton.
 161 @is_active: %TRUE or %FALSE.
 162
 163
 164 <!-- ##### FUNCTION gtk_toggle_button_get_inconsistent ##### -->
 165 <para>
 166
 167 </para>
 168
 169 @toggle_button:
 170 @Returns:
 171
 172
 173 <!-- ##### FUNCTION gtk_toggle_button_set_inconsistent ##### -->
 174 <para>
 175
 176 </para>
 177
 178 @toggle_button:
 179 @setting:
 180
 181
 182 <!-- ##### SIGNAL GtkToggleButton::toggled ##### -->
 183 <para>
 184 Should be connected if you wish to perform an action whenever the
 185 #GtkToggleButton's state is changed.
 186 </para>
 187
 188 @togglebutton: the object which received the signal.
 189
 190 <!-- ##### ARG GtkToggleButton:active ##### -->
 191 <para>
 192 Sets whether the toggle button should be pressed in or not.
 193 </para>
 194
 195 <!-- ##### ARG GtkToggleButton:inconsistent ##### -->
 196 <para>
 197
 198 </para>
 199
 200 <!-- ##### ARG GtkToggleButton:draw-indicator ##### -->
 201 <para>
 202 A value of %TRUE causes the toggle button to be invisible. %FALSE displays it.
 203 again.
 204 </para>
 205