Next: , Previous: GtkRadioButton, Up: Top

18 GtkToggleButton

Create buttons which retain their state

18.1 Overview

A <gtk-toggle-button> is a <gtk-button> which will remain 'pressed-in' when clicked. Clicking again will cause the toggle button to return to its normal state.

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 <gtk-label> and/or a <gtk-pixmap>), into the toggle button's container. (See <gtk-button> for more information).

The state of a <gtk-toggle-button> can be set specifically using gtk-toggle-button-set-active, and retrieved using gtk-toggle-button-get-active.

To simply switch the state of a toggle button, use gtk_toggle_button_toggled. 

     
     
     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 (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 (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);
     }

18.2 Usage

— Class: <gtk-toggle-button>

Derives from <gtk-button>.

This class defines the following slots:

active
If the toggle button should be pressed in or not
inconsistent
If the toggle button is in an "in between" state
draw-indicator
If the toggle part of the button is displayed
— Signal on <gtk-toggle-button>: toggled

Should be connected if you wish to perform an action whenever the <gtk-toggle-button>'s state is changed.

— Function: gtk-toggle-button-new ⇒  (ret <gtk-widget>)

Creates a new toggle button. A widget should be packed into the button, as in gtk-button-new.

ret
a new toggle button.
— Function: gtk-toggle-button-new-with-label (label mchars) ⇒  (ret <gtk-widget>)

Creates a new toggle button with a text label.

label
a string containing the message to be placed in the toggle button.
ret
a new toggle button.
— Function: gtk-toggle-button-new-with-mnemonic (label mchars) ⇒  (ret <gtk-widget>)

Creates a new <gtk-toggle-button> containing a label. The label will be created using gtk-label-new-with-mnemonic, so underscores in label indicate the mnemonic for the button.

label
the text of the button, with an underscore in front of the mnemonic character
ret
a new <gtk-toggle-button>
— Function: gtk-toggle-button-set-mode (self <gtk-toggle-button>) (draw_indicator bool)
— Method: set-mode

Sets whether the button is displayed as a separate indicator and label. You can call this function on a checkbutton or a radiobutton with draw-indicator = ‘#f’ to make the button look like a normal button

This function only affects instances of classes like <gtk-check-button> and <gtk-radio-button> that derive from <gtk-toggle-button>, not instances of <gtk-toggle-button> itself.

toggle-button
a <gtk-toggle-button>
draw-indicator
if ‘#t’, draw the button as a separate indicator and label; if ‘#f’, draw the button like a normal button
— Function: gtk-toggle-button-get-mode (self <gtk-toggle-button>) ⇒  (ret bool)
— Method: get-mode

Retrieves whether the button is displayed as a separate indicator and label. See gtk-toggle-button-set-mode.

toggle-button
a <gtk-toggle-button>
ret
‘#t’ if the togglebutton is drawn as a separate indicator and label.
— Function: gtk-toggle-button-toggled (self <gtk-toggle-button>)
— Method: toggled

Emits the toggled signal on the <gtk-toggle-button>. There is no good reason for an application ever to call this function.

toggle-button
a <gtk-toggle-button>.
— Function: gtk-toggle-button-get-active (self <gtk-toggle-button>) ⇒  (ret bool)
— Method: get-active

Queries a <gtk-toggle-button> and returns its current state. Returns ‘#t’ if the toggle button is pressed in and ‘#f’ if it is raised.

toggle-button
a <gtk-toggle-button>.
ret
a <gboolean> value.
— Function: gtk-toggle-button-set-active (self <gtk-toggle-button>) (is_active bool)
— Method: set-active

Sets the status of the toggle button. Set to ‘#t’ if you want the GtkToggleButton to be 'pressed in', and ‘#f’ to raise it. This action causes the toggled signal to be emitted.

toggle-button
a <gtk-toggle-button>.
is-active
‘#t’ or ‘#f’.
— Function: gtk-toggle-button-get-inconsistent (self <gtk-toggle-button>) ⇒  (ret bool)
— Method: get-inconsistent

Gets the value set by gtk-toggle-button-set-inconsistent.

toggle-button
a <gtk-toggle-button>
ret
‘#t’ if the button is displayed as inconsistent, ‘#f’ otherwise
— Function: gtk-toggle-button-set-inconsistent (self <gtk-toggle-button>) (setting bool)
— Method: set-inconsistent

If the user has selected a range of elements (such as some text or spreadsheet cells) that are affected by a toggle button, and the current values in that range are inconsistent, you may want to display the toggle in an "in between" state. This function turns on "in between" display. Normally you would turn off the inconsistent state again if the user toggles the toggle button. This has to be done manually, gtk-toggle-button-set-inconsistent only affects visual appearance, it doesn't affect the semantics of the button.

toggle-button
a <gtk-toggle-button>
setting
‘#t’ if state is inconsistent