Gtk.CheckButton¶

Example¶

Subclasses:: None

Methods¶

Inherited:: Gtk.Widget (181), GObject.Object (37), Gtk.Accessible (15), Gtk.Buildable (1), Gtk.Actionable (5)
Structs:: Gtk.WidgetClass (18), GObject.ObjectClass (5)

class	`new` ()
class	`new_with_label` (label)
class	`new_with_mnemonic` (label)
	`get_active` ()
	`get_child` ()
	`get_inconsistent` ()
	`get_label` ()
	`get_use_underline` ()
	`set_active` (setting)
	`set_child` (child)
	`set_group` (group)
	`set_inconsistent` (inconsistent)
	`set_label` (label)
	`set_use_underline` (setting)

Virtual Methods¶

Inherited:: Gtk.Widget (25), GObject.Object (7), Gtk.Accessible (6), Gtk.Buildable (9), Gtk.Actionable (4)

	`do_activate` ()
	`do_toggled` ()

Properties¶

Inherited:: Gtk.Widget (34), Gtk.Accessible (1), Gtk.Actionable (2)

Name	Type	Flags
`active`	`bool`	r/w/en
`child`	`Gtk.Widget`	r/w/en
`group`	`Gtk.CheckButton`	w
`inconsistent`	`bool`	r/w/en
`label`	`str`	r/w/en
`use-underline`	`bool`	r/w/en

Signals¶

Inherited:: Gtk.Widget (13), GObject.Object (1)

Name	Short Description
`activate`	Emitted to when the check button is activated.
`toggled`	Emitted when the buttons’s [property`Gtk`.CheckButton:active] property changes.

Fields¶

Inherited:: Gtk.Widget (13), GObject.Object (1)

Name	Type	Access	Description
parent_instance	`Gtk.Widget`	r

Class Details¶

class Gtk.CheckButton(**kwargs)¶

Bases:: Gtk.Widget, Gtk.Actionable
Abstract:: No
Structure:: Gtk.CheckButtonClass

A GtkCheckButton places a label next to an indicator.

Example GtkCheckButtons

A GtkCheckButton is created by calling either [ctor`Gtk`.CheckButton.new] or [ctor`Gtk`.CheckButton.new_with_label].

The state of a GtkCheckButton can be set specifically using [method`Gtk`.CheckButton.set_active], and retrieved using [method`Gtk`.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 [method`Gtk`.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*.

Example GtkCheckButtons

To add a GtkCheckButton to a group, use [method`Gtk`.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.

CSS nodes

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

A GtkCheckButton has a main node with name checkbutton. If the [property`Gtk`.CheckButton:label] or [property`Gtk`.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 Gtk.AccessibleRole.CHECKBOX role.

classmethod new()[source]¶

Returns:: a new GtkCheckButton
Return type:: Gtk.Widget

Creates a new GtkCheckButton.

classmethod new_with_label(label)[source]¶

Parameters:: label (str or None) – the text for the check button.
Returns:: a new GtkCheckButton
Return type:: Gtk.Widget

Creates a new GtkCheckButton with the given text.

classmethod new_with_mnemonic(label)[source]¶

Parameters:: label (str or None) – The text of the button, with an underscore in front of the mnemonic character
Returns:: a new GtkCheckButton
Return type:: Gtk.Widget

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

get_active()[source]¶

Returns:: whether the check button is active
Return type:: bool

Returns whether the check button is active.

get_child()[source]¶

Returns:: the child widget of self
Return type:: Gtk.Widget or None

Gets the child widget of self or NULL if [property`CheckButton`:py:data::label<Gtk.CheckButton.props.label>] is set.

New in version 4.8.

get_inconsistent()[source]¶

Returns:: True if self is currently in an inconsistent state
Return type:: bool

Returns whether the check button is in an inconsistent state.

get_label()[source]¶

Returns:: The label self shows next to the indicator. If no label is shown, None will be returned.
Return type:: str or None

Returns the label of the check button or NULL if [property`CheckButton`:py:data::child<Gtk.CheckButton.props.child>] is set.

get_use_underline()[source]¶

Returns:: The value of the [property`Gtk`.CheckButton:use-underline] property. See [method`Gtk`.CheckButton.set_use_underline] for details on how to set a new value.
Return type:: bool

Returns whether underlines in the label indicate mnemonics.

set_active(setting)[source]¶

Parameters:: setting (bool) – the new value to set

Changes the check buttons active state.

set_child(child)[source]¶

Parameters:: child (Gtk.Widget or None) – the child widget

Sets the child widget of self.

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

New in version 4.8.

set_group(group)[source]¶

Parameters:: group (Gtk.CheckButton or None) – another GtkCheckButton to form a group with

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 [iface`Gtk`.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.

set_inconsistent(inconsistent)[source]¶

Parameters:: inconsistent (bool) – True if state is inconsistent

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.

set_label(label)[source]¶

Parameters:: label (str or None) – The text shown next to the indicator, or None to show no text

Sets the text of self.

If [property`Gtk`.CheckButton:use-underline] is True, an underscore in label is interpreted as mnemonic indicator, see [method`Gtk`.CheckButton.set_use_underline] for details on this behavior.

set_use_underline(setting)[source]¶

Parameters:: setting (bool) – the new value to set

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 [property`Gtk`.Label:use-underline].

do_activate() virtual¶

do_toggled() virtual¶

Signal Details¶

Gtk.CheckButton.signals.activate(check_button)¶

Signal Name:: activate
Flags:: RUN_FIRST, ACTION
Parameters:: check_button (Gtk.CheckButton) – The object which received the signal

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 [signal`Gtk`.CheckButton::toggled] signal.

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

New in version 4.2.

Gtk.CheckButton.signals.toggled(check_button)¶

Signal Name:: toggled
Flags:: RUN_FIRST
Parameters:: check_button (Gtk.CheckButton) – The object which received the signal

Emitted when the buttons’s [property`Gtk`.CheckButton:active] property changes.

Property Details¶

Gtk.CheckButton.props.active¶

Name:: active
Type:: bool
Default Value:: False
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

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.

Gtk.CheckButton.props.child¶

Name:: child
Type:: Gtk.Widget
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

The child widget.

New in version 4.8.

Gtk.CheckButton.props.group¶

Name:: group
Type:: Gtk.CheckButton
Default Value:: None
Flags:: WRITABLE

The check button whose group this widget belongs to.

Gtk.CheckButton.props.inconsistent¶

Name:: inconsistent
Type:: bool
Default Value:: False
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

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

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

Gtk.CheckButton.props.label¶

Name:: label
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

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

Gtk.CheckButton.props.use_underline¶

Name:: use-underline
Type:: bool
Default Value:: False
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

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