TreeExpander

class TreeExpander(**properties: Any)

Superclasses: Widget, InitiallyUnowned, Object

Implemented Interfaces: Accessible, Buildable, 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 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 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 TreeListRow items which can be set via set_list_row on the expander. The expander will then watch that row item automatically. set_child sets the widget that displays the actual row contents.

GtkTreeExpander can be modified with properties such as indent_for_icon, indent_for_depth, and hide_expander to achieve a different appearance. This can even be done to influence individual rows, for example by binding the 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

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

class TreeExpander

classmethod new() → Widget: Creates a new GtkTreeExpander

Methods

class TreeExpander

get_child() → Widget | None: Gets the child widget displayed by self.

get_hide_expander() → bool: Gets whether the TreeExpander should be hidden in a GtkTreeListRow.

Added in version 4.10.

get_indent_for_depth() → bool: TreeExpander indents each level of depth with an additional indent.

Added in version 4.10.

get_indent_for_icon() → bool: TreeExpander indents the child by the width of an expander-icon if it is not expandable.

Added in version 4.6.

get_item() → Object | None

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

This call is essentially equivalent to calling:

gtk_tree_list_row_get_item (gtk_tree_expander_get_list_row (``self``));

get_list_row() → TreeListRow | None: Gets the list row managed by self.

set_child(child: Widget | None = None) → None

Sets the content widget to display.

Parameters:: child – a GtkWidget

set_hide_expander(hide_expander: bool) → None

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

Added in version 4.10.

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

set_indent_for_depth(indent_for_depth: bool) → None

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

Added in version 4.10.

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

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.

Added in version 4.6.

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

set_list_row(list_row: TreeListRow | None = None) → None

Sets the tree list row that this expander should manage.

Parameters:: list_row – a GtkTreeListRow

Properties

class TreeExpander

props.child: Widget: The child widget with the actual contents.

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

Added in version 4.10.

props.indent_for_depth: bool: TreeExpander indents the child according to its depth.

Added in version 4.10.

props.indent_for_icon: bool: TreeExpander indents the child by the width of an expander-icon if it is not expandable.

Added in version 4.6.

props.item: Object: The item held by this expander’s row.

props.list_row: TreeListRow: The list row to track for expander state.