: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. CSS nodes --------- .. code-block:: :dedent: checkbutton[.text-button] ├── 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:: 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 If the check button is active. Setting ``active`` to :const:`True` will add the ``:checked:`` state to both the check button and the indicator CSS node. .. attribute:: props.child :type: ~gi.repository.Gtk.Widget The child widget. .. versionadded:: 4.8 .. attribute:: props.group :type: ~gi.repository.Gtk.CheckButton The check button whose group this widget belongs to. .. attribute:: props.inconsistent :type: bool If the check button is in an “in between” state. The inconsistent state only affects visual appearance, not the semantics of the button. .. attribute:: props.label :type: str Text of the label inside the check button, if it contains a label widget. .. attribute:: props.use_underline :type: bool If set, an underline in the text indicates that the following character is to be used as mnemonic. 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 Emitted when the buttons's :obj:`~gi.repository.Gtk.CheckButton.props.active` property changes. Virtual Methods --------------- .. rst-class:: interim-class .. class:: CheckButton :no-index: .. method:: do_activate() -> None .. method:: do_toggled() -> None Fields ------ .. rst-class:: interim-class .. class:: CheckButton :no-index: .. attribute:: parent_instance