Gtk.CheckButton¶

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

Places a label next to an indicator.

A GtkCheckButton is created by calling either CheckButton.new or CheckButton.new_with_label.

The state of a GtkCheckButton can be set specifically using CheckButton.set_active, and retrieved using CheckButton.get_active.

Inconsistent state¶

In addition to "on" and "off", check buttons can be an "in between" state that is neither on nor off. This can be used e.g. when the user has selected a range of elements (such as some text or spreadsheet cells) that are affected by a check button, and the current values in that range are inconsistent.

To set a GtkCheckButton to inconsistent state, use CheckButton.set_inconsistent.

Grouping¶

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

Grouped check buttons use a different indicator, and are commonly referred to as radio buttons.

To add a GtkCheckButton to a group, use CheckButton.set_group.

When the code must keep track of the state of a group of radio buttons, it is recommended to keep track of such state through a stateful GAction with a target for each button. Using the toggled signals to keep track of the group changes and state is discouraged.

Shortcuts and Gestures¶

GtkCheckButton supports the following keyboard shortcuts:

<kbd>␣</kbd> or <kbd>Enter</kbd> activates the button.

CSS nodes¶

checkbutton[.text-button][.grouped]
├── check
╰── [label]

A GtkCheckButton has a main node with name checkbutton. If the CheckButton.label or CheckButton.child properties are set, it contains a child widget. The indicator node is named check when no group is set, and radio if the checkbutton is grouped together with other checkbuttons.

Accessibility¶

GtkCheckButton uses the AccessibleRole.checkbox role.

Constructors¶

new¶

@classmethod
def new(cls) -> Widget

Creates a new GtkCheckButton.

new_with_label¶

@classmethod
def new_with_label(cls, label: str | None = ...) -> Widget

Creates a new GtkCheckButton with the given text.

Parameters:

label — the text for the check button.

new_with_mnemonic¶

@classmethod
def new_with_mnemonic(cls, label: str | None = ...) -> Widget

Creates a new GtkCheckButton with the given text and a mnemonic.

Parameters:

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

Methods¶

get_active¶

def get_active(self) -> bool

Returns whether the check button is active.

get_child¶

def get_child(self) -> Widget | None

Gets the child widget of button or NULL if CheckButton.label is set.

get_inconsistent¶

def get_inconsistent(self) -> bool

Returns whether the check button is in an inconsistent state.

get_label¶

def get_label(self) -> str | None

Returns the label of the check button or NULL if CheckButton.child is set.

get_use_underline¶

def get_use_underline(self) -> bool

Returns whether underlines in the label indicate mnemonics.

set_active¶

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

Changes the check buttons active state.

Parameters:

setting — the new value to set

set_child¶

def set_child(self, child: Widget | None = ...) -> None

Sets the child widget of button.

Note that by using this API, you take full responsibility for setting up the proper accessibility label and description information for button. Most likely, you'll either set the accessibility label or description for button explicitly, or you'll set a labelled-by or described-by relations from child to button.

Parameters:

child — the child widget

set_group¶

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

Adds self to the group of group.

In a group of multiple check buttons, only one button can be active at a time. The behavior of a checkbutton in a group is also commonly known as a radio button.

Setting the group of a check button also changes the css name of the indicator widget's CSS node to 'radio'.

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 GtkCheckButton to form a group with

set_inconsistent¶

def set_inconsistent(self, inconsistent: bool) -> None

Sets the GtkCheckButton to inconsistent state.

You should turn off the inconsistent state again if the user checks the check button. This has to be done manually.

Parameters:

inconsistent — True if state is inconsistent

set_label¶

def set_label(self, label: str | None = ...) -> None

Sets the text of self.

If CheckButton.use-underline is True, an underscore in label is interpreted as mnemonic indicator, see CheckButton.set_use_underline for details on this behavior.

Parameters:

label — The text shown next to the indicator, or None to show no text

set_use_underline¶

def set_use_underline(self, setting: bool) -> None

Sets whether underlines in the label indicate mnemonics.

If setting is True, an underscore character in self's label indicates a mnemonic accelerator key. This behavior is similar to Label.use-underline.

Parameters:

setting — the new value to set

Virtual methods¶

do_activate¶

def do_activate(self) -> None

do_toggled¶

def do_toggled(self) -> None

Properties¶

active¶

active: bool  # read/write

If the check button is active.

Setting active to True will add the :checked: state to both the check button and the indicator CSS node.

child¶

child: Widget  # read/write

The child widget.

group¶

group: CheckButton  # read/write

The check button whose group this widget belongs to.

inconsistent¶

inconsistent: bool  # read/write

If the check button is in an “in between” state.

The inconsistent state only affects visual appearance, not the semantics of the button.

label¶

label: str  # read/write

Text of the label inside the check button, if it contains a label widget.

use_underline¶

use_underline: bool  # read/write

If set, an underline in the text indicates that the following character is to be used as mnemonic.

Signals¶

activate¶

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

Emitted to when the check button is activated.

The ::activate signal on GtkCheckButton is an action signal and emitting it causes the button to animate press then release.

Applications should never connect to this signal, but use the CheckButton.toggled signal.

The default bindings for this signal are all forms of the <kbd>␣</kbd> and <kbd>Enter</kbd> keys.

toggled¶

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

Emitted when the buttons's CheckButton.active property changes.