:right-sidebar: True
CheckButton
===================================================================
.. currentmodule:: gi.repository.Gtk
.. class:: CheckButton(**properties: ~typing.Any)
:no-contents-entry:
Superclasses: :class:`~gi.repository.Gtk.Widget`, :class:`~gi.repository.GObject.InitiallyUnowned`, :class:`~gi.repository.GObject.Object`
Implemented Interfaces: :class:`~gi.repository.Gtk.Accessible`, :class:`~gi.repository.Gtk.Actionable`, :class:`~gi.repository.Gtk.Buildable`, :class:`~gi.repository.Gtk.ConstraintTarget`
A ``GtkCheckButton`` places a label next to an indicator.
.. image:: https://docs.gtk.org/gtk4/check-button.png
A ``GtkCheckButton`` is created by calling either :obj:`~gi.repository.Gtk.CheckButton.new`
or :obj:`~gi.repository.Gtk.CheckButton.new_with_label`\.
The state of a ``GtkCheckButton`` can be set specifically using
:obj:`~gi.repository.Gtk.CheckButton.set_active`\, and retrieved using
:obj:`~gi.repository.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
:obj:`~gi.repository.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*\.
.. image:: https://docs.gtk.org/gtk4/radio-button.png
To add a ``GtkCheckButton`` to a group, use :obj:`~gi.repository.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.
Shortcuts and Gestures
--------------------------------------------------------------------------------
``GtkCheckButton`` supports the following keyboard shortcuts:
- ␣ or :kbd:`Enter` activates the button.
CSS nodes
--------------------------------------------------------------------------------
.. code-block::
:dedent:
checkbutton[.text-button][.grouped]
├── check
╰── [label]
A ``GtkCheckButton`` has a main node with name checkbutton. If the
:obj:`~gi.repository.Gtk.CheckButton.props.label` or :obj:`~gi.repository.Gtk.CheckButton.props.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 :const:`~gi.repository.Gtk.AccessibleRole.CHECKBOX` role.
Constructors
------------
.. rst-class:: interim-class
.. class:: CheckButton
:no-index:
.. classmethod:: new() -> ~gi.repository.Gtk.Widget
Creates a new ``GtkCheckButton``\.
.. classmethod:: new_with_label(label: str | None = None) -> ~gi.repository.Gtk.Widget
Creates a new ``GtkCheckButton`` with the given text.
:param label: the text for the check button.
.. classmethod:: new_with_mnemonic(label: str | None = None) -> ~gi.repository.Gtk.Widget
Creates a new ``GtkCheckButton`` with the given text and a mnemonic.
:param label: The text of the button, with an underscore
in front of the mnemonic character
Methods
-------
.. rst-class:: interim-class
.. class:: CheckButton
:no-index:
.. method:: do_activate(self) -> None
.. method:: do_toggled(self) -> None
.. method:: get_active() -> bool
Returns whether the check button is active.
.. method:: get_child() -> ~gi.repository.Gtk.Widget | None
Gets the child widget of ``button`` or ``NULL`` if :obj:`~gi.repository.Gtk.CheckButton.props.label` is set.
.. versionadded:: 4.8
.. method:: get_inconsistent() -> bool
Returns whether the check button is in an inconsistent state.
.. method:: get_label() -> str | None
Returns the label of the check button or ``NULL`` if :obj:`~gi.repository.Gtk.CheckButton.props.child` is set.
.. method:: get_use_underline() -> bool
Returns whether underlines in the label indicate mnemonics.
.. method:: set_active(setting: bool) -> None
Changes the check buttons active state.
:param setting: the new value to set
.. method:: set_child(child: ~gi.repository.Gtk.Widget | None = 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``\.
.. versionadded:: 4.8
:param child: the child widget
.. method:: set_group(group: ~gi.repository.Gtk.CheckButton | None = 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 :obj:`~gi.repository.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.
:param group: another ``GtkCheckButton`` to
form a group with
.. method:: set_inconsistent(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.
:param inconsistent: :const:`True` if state is inconsistent
.. method:: set_label(label: str | None = None) -> None
Sets the text of ``self``\.
If :obj:`~gi.repository.Gtk.CheckButton.props.use_underline` is :const:`True`, an underscore
in ``label`` is interpreted as mnemonic indicator, see
:obj:`~gi.repository.Gtk.CheckButton.set_use_underline` for details on this behavior.
:param label: The text shown next to the indicator, or :const:`None`
to show no text
.. method:: set_use_underline(setting: bool) -> None
Sets whether underlines in the label indicate mnemonics.
If ``setting`` is :const:`True`, an underscore character in ``self``\'s label
indicates a mnemonic accelerator key. This behavior is similar
to :obj:`~gi.repository.Gtk.Label.props.use_underline`\.
:param setting: the new value to set
Properties
----------
.. rst-class:: interim-class
.. class:: CheckButton
:no-index:
.. attribute:: props.active
:type: bool
The type of the None singleton.
.. attribute:: props.child
:type: ~gi.repository.Gtk.Widget
The type of the None singleton.
.. versionadded:: 4.8
.. attribute:: props.group
:type: ~gi.repository.Gtk.CheckButton
The type of the None singleton.
.. attribute:: props.inconsistent
:type: bool
The type of the None singleton.
.. attribute:: props.label
:type: str
The type of the None singleton.
.. attribute:: props.use_underline
:type: bool
The type of the None singleton.
Signals
-------
.. rst-class:: interim-class
.. class:: CheckButton.signals
:no-index:
.. method:: activate() -> 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
:obj:`~gi.repository.Gtk.CheckButton.signals.toggled` signal.
The default bindings for this signal are all forms of the
␣ and :kbd:`Enter` keys.
.. versionadded:: 4.2
.. method:: toggled() -> None
The type of the None singleton.
Virtual Methods
---------------
.. rst-class:: interim-class
.. class:: CheckButton
:no-index:
.. method:: do_activate() -> None
.. method:: do_toggled() -> None
The type of the None singleton.
Fields
------
.. rst-class:: interim-class
.. class:: CheckButton
:no-index:
.. attribute:: parent_instance