:right-sidebar: True

ToggleGroup
===================================================================

.. currentmodule:: gi.repository.Adw


.. versionadded:: 1.7




.. class:: ToggleGroup(**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.Buildable`, :class:`~gi.repository.Gtk.ConstraintTarget`, :class:`~gi.repository.Gtk.Orientable`



A group of exclusive toggles.

.. image:: https://gnome.pages.gitlab.gnome.org/libadwaita/doc/1-latest/toggle-group.png

``AdwToggleGroup`` presents a set of exclusive toggles, represented as
:obj:`~gi.repository.Adw.Toggle` objects. Each toggle can display an icon, a label, an icon
and a label, or a custom child.

Toggles are indexed by their position, with the first toggle being equivalent
to 0, and so on. Use the :obj:`~gi.repository.Adw.ToggleGroup.props.active` to get that position.

Toggles can also have optional names, set via the :obj:`~gi.repository.Adw.Toggle.props.name`
property. The name of the active toggle can be accessed via the
:obj:`~gi.repository.Adw.ToggleGroup.props.active_name` property.

``AdwToggle`` objects can be retrieved via their index or name, using
:obj:`~gi.repository.ToggleGroup.get_toggle` or :obj:`~gi.repository.ToggleGroup.get_toggle_by_name`
respectively. ``AdwToggleGroup`` also provides a :obj:`~gi.repository.Gtk.SelectionModel` of
its toggles via the :obj:`~gi.repository.Adw.ToggleGroup.props.toggles` property.

``AdwToggleGroup`` is orientable, and the toggles can be displayed horizontally
or vertically. This is mostly useful for icon-only toggles.

Use the :obj:`~gi.repository.Adw.ToggleGroup.props.homogeneous` property to make the toggles take
the same size, and the :obj:`~gi.repository.Adw.ToggleGroup.props.can_shrink` to control whether
the toggles can ellipsize.

Example of an ``AdwToggleGroup`` UI definition:


.. code-block:: xml
    :dedent:

     <object class="AdwToggleGroup">
       <property name="active-name">picture</property>
       <child>
         <object class="AdwToggle">
           <property name="icon-name">camera-photo-symbolic</property>
           <property name="tooltip" translatable="yes">Picture Mode</property>
           <property name="name">picture</property>
         </object>
       </child>
       <child>
         <object class="AdwToggle">
           <property name="icon-name">camera-video-symbolic</property>
           <property name="tooltip" translatable="yes">Recording Mode</property>
           <property name="name">recording</property>
         </object>
       </child>
     </object>

See also: :obj:`~gi.repository.Adw.InlineViewSwitcher`\.

CSS nodes
--------------------------------------------------------------------------------

``AdwToggleGroup`` has a main CSS node with the name ``toggle-group``\.

Its toggles have CSS nodes with the name ``toggle``\, and its separators have nodes
with the name ``separator``\.

Toggle nodes will have a different style classes depending on their content:
``.text-button`` for labels, ``.image-button`` for icons, ``.image-text-button``
for both or no style class for custom children.

The hidden separators use the ``.hidden`` style class.

Style classes
--------------------------------------------------------------------------------

``AdwToggleGroup`` can use the ```.flat`` <style-classes.html#flat_1>`__ style class
to remove its background and make it look like a group of buttons.

.. image:: https://gnome.pages.gitlab.gnome.org/libadwaita/doc/1-latest/toggle-group-flat.png

It can also use the ```.round`` <style-classes.html#round>`__ style class to make
its toggles and the group itself rounded.

.. image:: https://gnome.pages.gitlab.gnome.org/libadwaita/doc/1-latest/toggle-group-round.png

They can also be combined with each other.

.. image:: https://gnome.pages.gitlab.gnome.org/libadwaita/doc/1-latest/toggle-group-flat-round.png

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

``AdwToggleGroup`` uses the :obj:`~gi.repository.Gtk.AccessibleRole.radio-group` role. Its
toggles use the :obj:`~gi.repository.Gtk.AccessibleRole.radio` role.


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

.. rst-class:: interim-class

.. class:: ToggleGroup
   :no-index:


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

      Creates a new ``AdwToggleGroup``\.


      .. versionadded:: 1.7












Methods
-------

.. rst-class:: interim-class

.. class:: ToggleGroup
   :no-index:


   .. method:: add(toggle: ~gi.repository.Adw.Toggle) -> None

      Adds a toggle to ``self``\.



      .. versionadded:: 1.7





      :param toggle: the toggle to add




   .. method:: get_active() -> int

      Gets the index of the active toggle in ``self``\.

      Returns :obj:`~gi.repository.Gtk.INVALID_LIST_POSITION` if no toggle is active.



      .. versionadded:: 1.7








   .. method:: get_active_name() -> str | None

      Gets the name of the active toggle in ``self``\.

      Can be ``NULL`` if the currently active toggle doesn't have a name.

      See :obj:`~gi.repository.Adw.Toggle.props.name`\.



      .. versionadded:: 1.7








   .. method:: get_can_shrink() -> bool

      Gets whether the toggles can be smaller than the natural size of their
      contents.



      .. versionadded:: 1.7








   .. method:: get_homogeneous() -> bool

      Gets whether all toggles take the same size.



      .. versionadded:: 1.7








   .. method:: get_n_toggles() -> int

      Gets the number of toggles within ``self``\.



      .. versionadded:: 1.7








   .. method:: get_toggle(index: int) -> ~gi.repository.Adw.Toggle | None

      Gets the toggle with ``index`` from ``self``\.



      .. versionadded:: 1.7





      :param index: toggle's index




   .. method:: get_toggle_by_name(name: str) -> ~gi.repository.Adw.Toggle | None

      Gets the toggle with the name ``name`` from ``self``\.



      .. versionadded:: 1.7





      :param name: toggle name




   .. method:: get_toggles() -> ~gi.repository.Gtk.SelectionModel

      Returns a :obj:`~gi.repository.Gio.ListModel` that contains the toggles of the group.

      This can be used to keep an up-to-date view. The model also implements
      :obj:`~gi.repository.Gtk.SelectionModel` and can be used to track and change the active
      toggle.










   .. method:: remove(toggle: ~gi.repository.Adw.Toggle) -> None

      Removes ``toggle`` from ``self``\.



      .. versionadded:: 1.7





      :param toggle: a toggle to remove




   .. method:: remove_all() -> None

      Removes all toggles from ``self``\.



      .. versionadded:: 1.7








   .. method:: set_active(active: int) -> None

      Sets the active toggle for ``self``\.

      If the index is larger than the number of toggles in ``self``\, unsets the
      current active toggle.



      .. versionadded:: 1.7





      :param active: toggle index




   .. method:: set_active_name(name: str | None = None) -> None

      Sets the active toggle for ``self``\.

      The name can be set via :obj:`~gi.repository.Adw.Toggle.props.name`\.

      If ``name`` is ``NULL``\, unset the current active toggle instead.



      .. versionadded:: 1.7





      :param name: toggle name




   .. method:: set_can_shrink(can_shrink: bool) -> None

      Sets whether the toggles can be smaller than the natural size of their
      contents.

      If ``can_shrink`` is ``TRUE``\, the toggle labels will ellipsize.

      See :obj:`~gi.repository.Gtk.Button.props.can_shrink`\.



      .. versionadded:: 1.7





      :param can_shrink: whether the toggles can shrink




   .. method:: set_homogeneous(homogeneous: bool) -> None

      Sets whether all toggles take the same size.



      .. versionadded:: 1.7





      :param homogeneous: whether all toggles should take the same size








Properties
----------

.. rst-class:: interim-class

.. class:: ToggleGroup
   :no-index:
   

   .. attribute:: props.active
      :type: int

      The type of the None singleton.



      .. versionadded:: 1.7





   .. attribute:: props.active_name
      :type: str

      The type of the None singleton.



      .. versionadded:: 1.7





   .. attribute:: props.can_shrink
      :type: bool

      The type of the None singleton.



      .. versionadded:: 1.7





   .. attribute:: props.homogeneous
      :type: bool

      The type of the None singleton.



      .. versionadded:: 1.7





   .. attribute:: props.n_toggles
      :type: int

      The type of the None singleton.



      .. versionadded:: 1.7





   .. attribute:: props.toggles
      :type: ~gi.repository.Gtk.SelectionModel

      The type of the None singleton.



      .. versionadded:: 1.7