:right-sidebar: True

TreeExpander
===================================================================

.. currentmodule:: gi.repository.Gtk





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



``GtkTreeExpander`` is a widget that provides an expander for a list.

It is typically placed as a bottommost child into a ``GtkListView``
to allow users to expand and collapse children in a list with a
:obj:`~gi.repository.Gtk.TreeListModel`\. ``GtkTreeExpander`` provides the common UI
elements, gestures and keybindings for this purpose.

On top of this, the "listitem.expand", "listitem.collapse" and
"listitem.toggle-expand" actions are provided to allow adding custom
UI for managing expanded state.

It is important to mention that you want to set the
:obj:`~gi.repository.Gtk.ListItem.props.focusable` property to FALSE when using this
widget, as you want the keyboard focus to be in the treexpander, and not
inside the list to make use of the keybindings.

The ``GtkTreeListModel`` must be set to not be passthrough. Then it
will provide :obj:`~gi.repository.Gtk.TreeListRow` items which can be set via
:obj:`~gi.repository.Gtk.TreeExpander.set_list_row` on the expander.
The expander will then watch that row item automatically.
:obj:`~gi.repository.Gtk.TreeExpander.set_child` sets the widget that displays
the actual row contents.

``GtkTreeExpander`` can be modified with properties such as
:obj:`~gi.repository.Gtk.TreeExpander.props.indent_for_icon`\,
:obj:`~gi.repository.Gtk.TreeExpander.props.indent_for_depth`\, and
:obj:`~gi.repository.Gtk.TreeExpander.props.hide_expander` to achieve a different appearance.
This can even be done to influence individual rows, for example by binding
the :obj:`~gi.repository.Gtk.TreeExpander.props.hide_expander` property to the item count of
the model of the treelistrow, to hide the expander for rows without children,
even if the row is expandable.

Shortcuts and Gestures
--------------------------------------------------------------------------------

``GtkTreeExpander`` supports the following keyboard shortcuts:

- <kbd>+</kbd> or <kbd>\*</kbd> expands the expander.
- <kbd>-</kbd> or <kbd>/</kbd> collapses the expander.
- Left and right arrow keys, when combined with :kbd:`Shift` or
  :kbd:`Ctrl`\+:kbd:`Shift`\, will expand or collapse, depending on
  the locale's text direction.
- :kbd:`Ctrl`\+<kbd>␣</kbd> toggles the expander state.


The row can also expand on drag gestures.

Actions
--------------------------------------------------------------------------------

``GtkTreeExpander`` defines a set of built-in actions:

- ``listitem.expand`` expands the expander if it can be expanded.
- ``listitem.collapse`` collapses the expander.
- ``listitem.toggle-expand`` tries to expand the expander if it was collapsed
  or collapses it if it was expanded.


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


.. code-block::
    :dedent:

    treeexpander
    ├── [indent]*
    ├── [expander]
    ╰── <child>

``GtkTreeExpander`` has zero or one CSS nodes with the name "expander" that
should display the expander icon. The node will be ``:checked`` when it
is expanded. If the node is not expandable, an "indent" node will be
displayed instead.

For every level of depth, another "indent" node is prepended.

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

Until GTK 4.10, ``GtkTreeExpander`` used the ``GTK_ACCESSIBLE_ROLE_GROUP`` role.

Since GTK 4.12, ``GtkTreeExpander`` uses the ``GTK_ACCESSIBLE_ROLE_BUTTON`` role.
Toggling it will change the ``GTK_ACCESSIBLE_STATE_EXPANDED`` state.


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

.. rst-class:: interim-class

.. class:: TreeExpander
   :no-index:


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

      Creates a new ``GtkTreeExpander``













Methods
-------

.. rst-class:: interim-class

.. class:: TreeExpander
   :no-index:


   .. method:: get_child() -> ~gi.repository.Gtk.Widget | None

      Gets the child widget displayed by ``self``\.









   .. method:: get_hide_expander() -> bool

      Gets whether the TreeExpander should be hidden in a GtkTreeListRow.


      .. versionadded:: 4.10








   .. method:: get_indent_for_depth() -> bool

      TreeExpander indents each level of depth with an additional indent.


      .. versionadded:: 4.10








   .. method:: get_indent_for_icon() -> bool

      TreeExpander indents the child by the width of an expander-icon if it is not expandable.


      .. versionadded:: 4.6








   .. method:: get_item() -> ~gi.repository.GObject.Object | None

      Forwards the item set on the ``GtkTreeListRow`` that ``self`` is managing.

      This call is essentially equivalent to calling:


      .. code-block:: c
          :dedent:

          gtk_tree_list_row_get_item (gtk_tree_expander_get_list_row (@self));









   .. method:: get_list_row() -> ~gi.repository.Gtk.TreeListRow | None

      Gets the list row managed by ``self``\.









   .. method:: set_child(child: ~gi.repository.Gtk.Widget | None = None) -> None

      Sets the content widget to display.






      :param child: a ``GtkWidget``




   .. method:: set_hide_expander(hide_expander: bool) -> None

      Sets whether the expander icon should be visible in a GtkTreeListRow.


      .. versionadded:: 4.10





      :param hide_expander: TRUE if the expander should be hidden. Otherwise FALSE.




   .. method:: set_indent_for_depth(indent_for_depth: bool) -> None

      Sets if the TreeExpander should indent the child according to its depth.


      .. versionadded:: 4.10





      :param indent_for_depth: TRUE if the child should be indented. Otherwise FALSE.




   .. method:: set_indent_for_icon(indent_for_icon: bool) -> None

      Sets if the TreeExpander should indent the child by the width of an expander-icon when it is not expandable.


      .. versionadded:: 4.6





      :param indent_for_icon: TRUE if the child should be indented without expander. Otherwise FALSE.




   .. method:: set_list_row(list_row: ~gi.repository.Gtk.TreeListRow | None = None) -> None

      Sets the tree list row that this expander should manage.






      :param list_row: a ``GtkTreeListRow``








Properties
----------

.. rst-class:: interim-class

.. class:: TreeExpander
   :no-index:
   

   .. attribute:: props.child
      :type: ~gi.repository.Gtk.Widget

      The type of the None singleton.







   .. attribute:: props.hide_expander
      :type: bool

      The type of the None singleton.



      .. versionadded:: 4.10





   .. attribute:: props.indent_for_depth
      :type: bool

      The type of the None singleton.



      .. versionadded:: 4.10





   .. attribute:: props.indent_for_icon
      :type: bool

      The type of the None singleton.



      .. versionadded:: 4.6





   .. attribute:: props.item
      :type: ~gi.repository.GObject.Object

      The type of the None singleton.







   .. attribute:: props.list_row
      :type: ~gi.repository.Gtk.TreeListRow

      The type of the None singleton.