:right-sidebar: True

Switch
===================================================================

.. currentmodule:: gi.repository.Gtk





.. class:: Switch(**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`



``GtkSwitch`` is a "light switch" that has two states: on or off.


.. image:: https://docs.gtk.org/gtk4/switch.png


The user can control which state should be active by clicking the
empty area, or by dragging the handle.

``GtkSwitch`` can also handle situations where the underlying state
changes with a delay. In this case, the slider position indicates
the user's recent change (as indicated by the :obj:`~gi.repository.Gtk.Switch.props.active`
property), and the color indicates whether the underlying state (represented
by the :obj:`~gi.repository.Gtk.Switch.props.state` property) has been updated yet.


.. image:: https://docs.gtk.org/gtk4/switch-state.png


See :obj:`~gi.repository.Gtk.Switch.signals.state_set` for details.

CSS nodes
---------


.. code-block::
   :dedent:

   switch
   ├── image
   ├── image
   ╰── slider


``GtkSwitch`` has four css nodes, the main node with the name switch and
subnodes for the slider and the on and off images. Neither of them is
using any style classes.

Accessibility
-------------

``GtkSwitch`` uses the :const:`~gi.repository.Gtk.AccessibleRole.SWITCH` role.



Constructors
------------

.. rst-class:: interim-class

.. class:: Switch
   :no-index:


   .. classmethod:: new() -> ~gi.repository.Gtk.Widget

      Creates a new ``GtkSwitch`` widget.














Methods
-------

.. rst-class:: interim-class

.. class:: Switch
   :no-index:


   .. method:: get_active() -> bool

      Gets whether the ``GtkSwitch`` is in its “on” or “off” state.










   .. method:: get_state() -> bool

      Gets the underlying state of the ``GtkSwitch``.










   .. method:: set_active(is_active: bool) -> None

      Changes the state of ``self`` to the desired one.







      :param is_active: :const:`True` if ``self`` should be active, and :const:`False` otherwise





   .. method:: set_state(state: bool) -> None

      Sets the underlying state of the ``GtkSwitch``.

      This function is typically called from a :obj:`~gi.repository.Gtk.Switch.signals.state_set`
      signal handler in order to set up delayed state changes.

      See :obj:`~gi.repository.Gtk.Switch.signals.state_set` for details.







      :param state: the new state









Properties
----------

.. rst-class:: interim-class

.. class:: Switch
   :no-index:
   

   .. attribute:: props.active
      :type: bool

      Whether the ``GtkSwitch`` widget is in its on or off state.







   .. attribute:: props.state
      :type: bool

      The backend state that is controlled by the switch.

      See :obj:`~gi.repository.Gtk.Switch.signals.state_set` for details.











Signals
-------

.. rst-class:: interim-class

.. class:: Switch.signals
   :no-index:
   

   .. method:: activate() -> None

      Emitted to animate the switch.

      Applications should never connect to this signal,
      but use the :obj:`~gi.repository.Gtk.Switch.props.active` property.










   .. method:: state_set(state: bool) -> bool

      Emitted to change the underlying state.

      The ::state-set signal is emitted when the user changes the switch
      position. The default handler keeps the state in sync with the
      :obj:`~gi.repository.Gtk.Switch.props.active` property.

      To implement delayed state change, applications can connect to this
      signal, initiate the change of the underlying state, and call
      :obj:`~gi.repository.Gtk.Switch.set_state` when the underlying state change is
      complete. The signal handler should return :const:`True` to prevent the
      default handler from running.

      Visually, the underlying state is represented by the trough color of
      the switch, while the :obj:`~gi.repository.Gtk.Switch.props.active` property is
      represented by the position of the switch.







      :param state: the new state of the switch