Skip to content

Gtk.ToggleButton

class — extends Button, Accessible, Actionable, Buildable, ConstraintTarget

Shows a button which remains “pressed-in” when clicked.

<picture> <source srcset="toggle-button-dark.png" media="(prefers-color-scheme: dark)"> <img alt="Example GtkToggleButtons" src="toggle-button.png"> </picture>

Clicking again will cause the toggle button to return to its normal state.

A toggle button is created by calling either ToggleButton.new or ToggleButton.new_with_label. If using the former, it is advisable to pack a widget, (such as a GtkLabel and/or a GtkImage), into the toggle button’s container. (See Button for more information).

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

Grouping

Toggle buttons can be grouped together, to form mutually exclusive groups - only one of the buttons can be toggled at a time, and toggling another one will switch the currently toggled one off.

To add a GtkToggleButton to a group, use ToggleButton.set_group.

CSS nodes

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

Accessibility

GtkToggleButton uses the AccessibleRole.toggle_button role.

Creating two GtkToggleButton widgets.

static void
output_state (GtkToggleButton *source,
              gpointer         user_data)
{
  g_print ("Toggle button "%s" is active: %s",
           gtk_button_get_label (GTK_BUTTON (source)),
           gtk_toggle_button_get_active (source) ? "Yes" : "No");
}

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

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

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

  g_signal_connect (toggle1, "toggled",
                    G_CALLBACK (output_state),
                    NULL);
  gtk_box_append (GTK_BOX (box), toggle1);

  text = "Hi, I’m toggle button two";
  toggle2 = gtk_toggle_button_new_with_label (text);
  g_signal_connect (toggle2, "toggled",
                    G_CALLBACK (output_state),
                    NULL);
  gtk_box_append (GTK_BOX (box), toggle2);

  gtk_window_set_child (GTK_WINDOW (window), box);
  gtk_window_present (GTK_WINDOW (window));
}

Constructors

new

@classmethod
def new(cls) -> Widget

Creates a new toggle button.

A widget should be packed into the button, as in Button.new.

new_with_label

@classmethod
def new_with_label(cls, label: str) -> Widget

Creates a new toggle button with a text label.

Parameters:

  • label — a string containing the message to be placed in the toggle button.

new_with_mnemonic

@classmethod
def new_with_mnemonic(cls, label: str) -> Widget

Creates a new GtkToggleButton containing a label.

The label will be created using Label.new_with_mnemonic, so underscores in label indicate the mnemonic for the button.

Parameters:

  • label — the text of the button, with an underscore in front of the mnemonic character

Methods

get_active

def get_active(self) -> bool

Queries a GtkToggleButton and returns its current state.

Returns True if the toggle button is pressed in and False if it is raised.

set_active

def set_active(self, is_active: bool) -> None

Sets the status of the toggle button.

Set to True if you want the GtkToggleButton to be “pressed in”, and False to raise it.

If the status of the button changes, this action causes the ToggleButton.toggled signal to be emitted.

Parameters:

  • is_active — True or False.

set_group

def set_group(self, group: ToggleButton | None = ...) -> None

Adds self to the group of group.

In a group of multiple toggle buttons, only one button can be active at a time.

Setting up groups in a cycle leads to undefined behavior.

Note that the same effect can be achieved via the Actionable API, by using the same action with parameter type and state type 's' for all buttons in the group, and giving each button its own target value.

Parameters:

  • group — another GtkToggleButton to form a group with

toggled

def toggled(self) -> None

:::warning Deprecated since 4.10 This API is deprecated. :::

Emits the ::toggled signal on the GtkToggleButton.

Virtual methods

do_toggled

def do_toggled(self) -> None

:::warning Deprecated since 4.10 This API is deprecated. :::

Emits the ::toggled signal on the GtkToggleButton.

Properties

active

active: bool  # read/write

If the toggle button should be pressed in.

group

group: ToggleButton  # read/write

The toggle button whose group this widget belongs to.

Signals

toggled

def on_toggled(self) -> None: ...

Emitted whenever the GtkToggleButton's state is changed.