: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.

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::
         :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 child widget with the actual contents.







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

      Whether the expander icon should be hidden in a GtkTreeListRow.
      Note that this property simply hides the icon.  The actions and keybinding
      (i.e. collapse and expand) are not affected by this property.

      A common use for this property would be to bind to the number of children in a
      GtkTreeListRow's model in order to hide the expander when a row has no children.



      .. versionadded:: 4.10





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

      TreeExpander indents the child according to its depth.



      .. versionadded:: 4.10





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

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



      .. versionadded:: 4.6





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

      The item held by this expander's row.







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

      The list row to track for expander state.