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 its
  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
  62 <varlistentry>
  63   <term>#GtkButton</term>
  64   <listitem><para>a more general button.</para></listitem>
  65 </varlistentry>
  66
  67 <varlistentry>
  68   <term>#GtkCheckButton</term>
  69   <listitem><para>another way of presenting a toggle option.</para></listitem>
  70 </varlistentry>
  71
  72 <varlistentry>
  73   <term>#GtkCheckMenuItem</term>
  74   <listitem><para>a #GtkToggleButton  as a menu item.</para></listitem>
  75 </varlistentry>
  76
  77 </variablelist>
  78 </para>
  79
  80 <!-- ##### STRUCT GtkToggleButton ##### -->
  81 <para>
  82 The #GtkToggleButton struct contains private data only, and should be manipulated using the functions below.
  83 </para>
  84
  85
  86 <!-- ##### FUNCTION gtk_toggle_button_new ##### -->
  87 <para>
  88 Creates a new toggle button. A widget should be packed into the button, as in gtk_button_new().
  89 </para>
  90
  91 @Returns: a new toggle button.
  92
  93
  94 <!-- ##### FUNCTION gtk_toggle_button_new_with_label ##### -->
  95 <para>
  96 Creates a new toggle button with a text label.
  97 </para>
  98
  99 @label: a string containing the message to be placed in the toggle button.
 100 @Returns: a new toggle button.
 101
 102
 103 <!-- ##### FUNCTION gtk_toggle_button_new_with_mnemonic ##### -->
 104 <para>
 105
 106 </para>
 107
 108 @label:
 109 @Returns:
 110
 111
 112 <!-- ##### FUNCTION gtk_toggle_button_set_mode ##### -->
 113 <para>
 114 </para>
 115
 116 @toggle_button:
 117 @draw_indicator:
 118
 119
 120 <!-- ##### FUNCTION gtk_toggle_button_get_mode ##### -->
 121 <para>
 122
 123 </para>
 124
 125 @toggle_button:
 126 @Returns:
 127
 128
 129 <!-- ##### MACRO gtk_toggle_button_set_state ##### -->
 130 <para>
 131 This is a deprecated macro, and is only maintained for compatibility reasons.
 132 </para>
 133
 134
 135
 136 <!-- ##### FUNCTION gtk_toggle_button_toggled ##### -->
 137 <para>
 138 Emits the <link linkend="GtkToggleButton-toggled">toggled</link>
 139 signal on the #GtkToggleButton. There is no good reason for an
 140 application ever to call this function.
 141 </para>
 142
 143 @toggle_button: a #GtkToggleButton.
 144
 145
 146 <!-- ##### FUNCTION gtk_toggle_button_get_active ##### -->
 147 <para>
 148 Queries a #GtkToggleButton and returns its current state. Returns %TRUE if
 149 the toggle button is pressed in and %FALSE if it is raised.
 150 </para>
 151
 152 @toggle_button: a #GtkToggleButton.
 153 @Returns: a #gboolean value.
 154
 155
 156 <!-- ##### FUNCTION gtk_toggle_button_set_active ##### -->
 157 <para>
 158 Sets the status of the toggle button. Set to %TRUE if you want the
 159 GtkToggleButton to be 'pressed in', and %FALSE to raise it.
 160 This action causes the toggled signal to be emitted.
 161 </para>
 162
 163 @toggle_button: a #GtkToggleButton.
 164 @is_active: %TRUE or %FALSE.
 165
 166
 167 <!-- ##### FUNCTION gtk_toggle_button_get_inconsistent ##### -->
 168 <para>
 169
 170 </para>
 171
 172 @toggle_button:
 173 @Returns:
 174
 175
 176 <!-- ##### FUNCTION gtk_toggle_button_set_inconsistent ##### -->
 177 <para>
 178
 179 </para>
 180
 181 @toggle_button:
 182 @setting:
 183
 184
 185 <!-- ##### SIGNAL GtkToggleButton::toggled ##### -->
 186 <para>
 187 Should be connected if you wish to perform an action whenever the
 188 #GtkToggleButton's state is changed.
 189 </para>
 190
 191 @togglebutton: the object which received the signal.
 192
 193 <!-- ##### ARG GtkToggleButton:active ##### -->
 194 <para>
 195
 196 </para>
 197
 198 <!-- ##### ARG GtkToggleButton:draw-indicator ##### -->
 199 <para>
 200
 201 </para>
 202
 203 <!-- ##### ARG GtkToggleButton:inconsistent ##### -->
 204 <para>
 205
 206 </para>
 207