ToggleButton

class ToggleButton(**properties: Any)

Superclasses: Button, Widget, InitiallyUnowned, Object

Implemented Interfaces: Accessible, Actionable, Buildable, ConstraintTarget

A GtkToggleButton is a button which remains “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 new or 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 set_active, and retrieved using get_active.

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

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 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 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

class ToggleButton
classmethod new() → Widget

Creates a new toggle button.

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

classmethod new_with_label(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.

classmethod new_with_mnemonic(label: str) → Widget

Creates a new GtkToggleButton containing a label.

The label will be created using 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

class ToggleButton
get_active() → 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(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 toggled signal to be emitted.

Parameters:

is_active – True or False.

set_group(group: ToggleButton | None = 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() → None

Emits the ::toggled signal on the GtkToggleButton.

Deprecated since version 4.10: There is no good reason for an application ever to call this function.

Properties

class ToggleButton
props.active: bool

If the toggle button should be pressed in.

props.group: ToggleButton

The toggle button whose group this widget belongs to.

Signals

class ToggleButton.signals
toggled() → None

Emitted whenever the GtkToggleButton’s state is changed.

Virtual Methods

class ToggleButton
do_toggled() → None

Emits the ::toggled signal on the GtkToggleButton.

Deprecated since version 4.10: There is no good reason for an application ever to call this function.

Fields

class ToggleButton
button