Gtk.ToggleButton

g Atk.ImplementorIface Atk.ImplementorIface Gtk.Widget Gtk.Widget Atk.ImplementorIface->Gtk.Widget GObject.GInterface GObject.GInterface GObject.GInterface->Atk.ImplementorIface Gtk.Actionable Gtk.Actionable GObject.GInterface->Gtk.Actionable Gtk.Activatable Gtk.Activatable GObject.GInterface->Gtk.Activatable Gtk.Buildable Gtk.Buildable GObject.GInterface->Gtk.Buildable GObject.InitiallyUnowned GObject.InitiallyUnowned GObject.InitiallyUnowned->Gtk.Widget GObject.Object GObject.Object GObject.Object->GObject.InitiallyUnowned Gtk.Button Gtk.Button Gtk.Actionable->Gtk.Button Gtk.Activatable->Gtk.Button Gtk.Bin Gtk.Bin Gtk.Bin->Gtk.Button Gtk.Buildable->Gtk.Widget Gtk.ToggleButton Gtk.ToggleButton Gtk.Button->Gtk.ToggleButton Gtk.Container Gtk.Container Gtk.Container->Gtk.Bin Gtk.Widget->Gtk.Container

Example

../_images/ToggleButton.png
Subclasses:Gtk.CheckButton, Gtk.MenuButton

Properties

Inherited:Gtk.Button (9), Gtk.Container (3), Gtk.Widget (39), Gtk.Actionable (2), Gtk.Activatable (2)
Name Type Flags Short Description
active bool r/w/en If the toggle button should be pressed in
draw-indicator bool r/w If the toggle part of the button is displayed
inconsistent bool r/w/en If the toggle button is in an “in between” state

Style Properties

Inherited:Gtk.Button (7), Gtk.Widget (17)

Signals

Inherited:Gtk.Button (6), Gtk.Container (4), Gtk.Widget (69), GObject.Object (1)
Name Short Description
toggled Should be connected if you wish to perform an action whenever the Gtk.ToggleButton’s state is changed.

Fields

Inherited:Gtk.Button (6), Gtk.Container (4), Gtk.Widget (69), GObject.Object (1)
Name Type Access Description
button Gtk.Button r  

Class Details

class Gtk.ToggleButton(*args, **kwargs)
Bases:Gtk.Button
Abstract:No
Structure:Gtk.ToggleButtonClass

A Gtk.ToggleButton 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.ToggleButton.new() or Gtk.ToggleButton.new_with_label(). If using the former, it is advisable to pack a widget, (such as a Gtk.Label and/or a Gtk.Image), into the toggle button’s container. (See Gtk.Button for more information).

The state of a Gtk.ToggleButton can be set specifically using Gtk.ToggleButton.set_active(), and retrieved using Gtk.ToggleButton.get_active().

To simply switch the state of a toggle button, use Gtk.ToggleButton.toggled().

CSS nodes

Gtk.ToggleButton has a single CSS node with name button. To differentiate it from a plain Gtk.Button, it gets the .toggle style class.

Creating two Gtk.ToggleButton widgets.
static void output_state (GtkToggleButton *source, gpointer user_data) {
  printf ("Active: %d\n", gtk_toggle_button_get_active (source));
}

void make_toggles (void) {
  GtkWidget *window, *toggle1, *toggle2;
  GtkWidget *box;
  const char *text;

  window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
  box = gtk_box_new (GTK_ORIENTATION_VERTICAL, 12);

  text = "Hi, I’m a toggle button.";
  toggle1 = gtk_toggle_button_new_with_label (text);

  // 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_container_add (GTK_CONTAINER (box), toggle1);

  text = "Hi, I’m a toggle button.";
  toggle2 = gtk_toggle_button_new_with_label (text);
  gtk_toggle_button_set_mode (GTK_TOGGLE_BUTTON (toggle2),
                              FALSE);
  g_signal_connect (toggle2, "toggled",
                    G_CALLBACK (output_state),
                    NULL);
  gtk_container_add (GTK_CONTAINER (box), toggle2);

  gtk_container_add (GTK_CONTAINER (window), box);
  gtk_widget_show_all (window);
}
classmethod new()[source]
Returns:a new toggle button.
Return type:Gtk.Widget

Creates a new toggle button. A widget should be packed into the button, as in Gtk.Button.new().

classmethod new_with_label(label)[source]
Parameters:label (str) – a string containing the message to be placed in the toggle button.
Returns:a new toggle button.
Return type:Gtk.Widget

Creates a new toggle button with a text label.

classmethod new_with_mnemonic(label)[source]
Parameters:label (str) – the text of the button, with an underscore in front of the mnemonic character
Returns:a new Gtk.ToggleButton
Return type:Gtk.Widget

Creates a new Gtk.ToggleButton containing a label. The label will be created using Gtk.Label.new_with_mnemonic(), so underscores in label indicate the mnemonic for the button.

get_active()[source]
Returns:a bool value.
Return type:bool

Queries a Gtk.ToggleButton and returns its current state. Returns True if the toggle button is pressed in and False if it is raised.

get_inconsistent()[source]
Returns:True if the button is displayed as inconsistent, False otherwise
Return type:bool

Gets the value set by Gtk.ToggleButton.set_inconsistent().

get_mode()[source]
Returns:True if the togglebutton is drawn as a separate indicator and label.
Return type:bool

Retrieves whether the button is displayed as a separate indicator and label. See Gtk.ToggleButton.set_mode().

set_active(is_active)[source]
Parameters:is_active (bool) – True or False.

Sets the status of the toggle button. Set to True if you want the Gtk.ToggleButton to be “pressed in”, and False to raise it. This action causes the Gtk.ToggleButton ::toggled signal and the Gtk.Button ::clicked signal to be emitted.

set_inconsistent(setting)[source]
Parameters:setting (bool) – True if state is 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.ToggleButton.set_inconsistent() only affects visual appearance, it doesn’t affect the semantics of the button.

set_mode(draw_indicator)[source]
Parameters:draw_indicator (bool) – if True, draw the button as a separate indicator and label; if False, draw the button like a normal button

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 = False to make the button look like a normal button.

This can be used to create linked strip of buttons that work like a Gtk.StackSwitcher.

This function only affects instances of classes like Gtk.CheckButton and Gtk.RadioButton that derive from Gtk.ToggleButton, not instances of Gtk.ToggleButton itself.

toggled()[source]

Emits the Gtk.ToggleButton ::toggled signal on the Gtk.ToggleButton. There is no good reason for an application ever to call this function.

do_toggled() virtual

Emits the Gtk.ToggleButton ::toggled signal on the Gtk.ToggleButton. There is no good reason for an application ever to call this function.

Signal Details

Gtk.ToggleButton.signals.toggled(toggle_button)
Signal Name:toggled
Flags:RUN_FIRST
Parameters:toggle_button (Gtk.ToggleButton) – The object which received the signal

Should be connected if you wish to perform an action whenever the Gtk.ToggleButton’s state is changed.

Property Details

Gtk.ToggleButton.props.active
Name:active
Type:bool
Default Value:False
Flags:READABLE, WRITABLE, EXPLICIT_NOTIFY

If the toggle button should be pressed in

Gtk.ToggleButton.props.draw_indicator
Name:draw-indicator
Type:bool
Default Value:False
Flags:READABLE, WRITABLE

If the toggle part of the button is displayed

Gtk.ToggleButton.props.inconsistent
Name:inconsistent
Type:bool
Default Value:False
Flags:READABLE, WRITABLE, EXPLICIT_NOTIFY

If the toggle button is in an “in between” state