forked from AuroraMiddleware/gtk
167 lines
4.7 KiB
Plaintext
167 lines
4.7 KiB
Plaintext
<!-- ##### 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>
|
|
|
|
@button:
|
|
@active:
|
|
@draw_indicator:
|
|
@event_window:
|
|
|
|
<!-- ##### 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>
|
|
Changes the state of the toggle button.
|
|
</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>
|
|
|