:right-sidebar: True ToggleButton =================================================================== .. currentmodule:: gi.repository.Gtk .. class:: ToggleButton(**properties: ~typing.Any) :no-contents-entry: Superclasses: :class:`~gi.repository.Gtk.Button`, :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 ``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 :obj:`~gi.repository.Gtk.ToggleButton.new` or :obj:`~gi.repository.Gtk.ToggleButton.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 :obj:`~gi.repository.Gtk.Button` for more information). The state of a ``GtkToggleButton`` can be set specifically using :obj:`~gi.repository.Gtk.ToggleButton.set_active`, and retrieved using :obj:`~gi.repository.Gtk.ToggleButton.get_active`. To simply switch the state of a toggle button, use :obj:`~gi.repository.Gtk.ToggleButton.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 :obj:`~gi.repository.Gtk.ToggleButton.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 :const:`~gi.repository.Gtk.AccessibleRole.TOGGLE_BUTTON` role. Creating two ``GtkToggleButton`` widgets. ----------------------------------------- .. code-block:: :dedent: 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 ------------ .. rst-class:: interim-class .. class:: ToggleButton :no-index: .. classmethod:: new() -> ~gi.repository.Gtk.Widget Creates a new toggle button. A widget should be packed into the button, as in :obj:`~gi.repository.Gtk.Button.new`. .. classmethod:: new_with_label(label: str) -> ~gi.repository.Gtk.Widget Creates a new toggle button with a text label. :param label: a string containing the message to be placed in the toggle button. .. classmethod:: new_with_mnemonic(label: str) -> ~gi.repository.Gtk.Widget Creates a new ``GtkToggleButton`` containing a label. The label will be created using :obj:`~gi.repository.Gtk.Label.new_with_mnemonic`, so underscores in ``label`` indicate the mnemonic for the button. :param label: the text of the button, with an underscore in front of the mnemonic character Methods ------- .. rst-class:: interim-class .. class:: ToggleButton :no-index: .. method:: get_active() -> bool Queries a ``GtkToggleButton`` and returns its current state. Returns :const:`True` if the toggle button is pressed in and :const:`False` if it is raised. .. method:: set_active(is_active: bool) -> None Sets the status of the toggle button. Set to :const:`True` if you want the ``GtkToggleButton`` to be “pressed in”, and :const:`False` to raise it. If the status of the button changes, this action causes the :obj:`~gi.repository.Gtk.ToggleButton.signals.toggled` signal to be emitted. :param is_active: :const:`True` or :const:`False`. .. method:: set_group(group: ~gi.repository.Gtk.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 :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 ``GtkToggleButton`` to form a group with .. method:: toggled() -> None Emits the ::toggled signal on the ``GtkToggleButton``. .. deprecated:: 4.10 There is no good reason for an application ever to call this function. Properties ---------- .. rst-class:: interim-class .. class:: ToggleButton :no-index: .. attribute:: props.active :type: bool If the toggle button should be pressed in. .. attribute:: props.group :type: ~gi.repository.Gtk.ToggleButton The toggle button whose group this widget belongs to. Signals ------- .. rst-class:: interim-class .. class:: ToggleButton.signals :no-index: .. method:: toggled() -> None Emitted whenever the ``GtkToggleButton``'s state is changed. Virtual Methods --------------- .. rst-class:: interim-class .. class:: ToggleButton :no-index: .. method:: do_toggled() -> None Emits the ::toggled signal on the ``GtkToggleButton``. .. deprecated:: 4.10 There is no good reason for an application ever to call this function. Fields ------ .. rst-class:: interim-class .. class:: ToggleButton :no-index: .. attribute:: button