Skip to content

Gtk.TreeExpander

class — extends Widget, Accessible, Buildable, ConstraintTarget

Provides an expander for a tree-like 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 ListItem.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 TreeExpander.set_list_row on the expander. The expander will then watch that row item automatically. TreeExpander.set_child sets the widget that displays the actual row contents.

GtkTreeExpander can be modified with properties such as TreeExpander.indent-for-icon, TreeExpander.indent-for-depth, and TreeExpander.hide-expander to achieve a different appearance. This can even be done to influence individual rows, for example by binding the TreeExpander.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</kbd> or <kbd>Ctrl</kbd>+<kbd>Shift</kbd>, will expand or collapse, depending on the locale's text direction.
  • <kbd>Ctrl</kbd>+<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

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 AccessibleRole.group role.

Since GTK 4.12, GtkTreeExpander uses the AccessibleRole.button role. Toggling it will change the GTK_ACCESSIBLE_STATE_EXPANDED state.

Constructors

new

@classmethod
def new(cls) -> Widget

Creates a new GtkTreeExpander

Methods

get_child

def get_child(self) -> Widget | None

Gets the child widget displayed by self.

get_hide_expander

def get_hide_expander(self) -> bool

Gets whether the TreeExpander should be hidden in a GtkTreeListRow.

get_indent_for_depth

def get_indent_for_depth(self) -> bool

TreeExpander indents each level of depth with an additional indent.

get_indent_for_icon

def get_indent_for_icon(self) -> bool

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

get_item

def get_item(self) -> GObject.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

def get_list_row(self) -> TreeListRow | None

Gets the list row managed by self.

set_child

def set_child(self, child: Widget | None = ...) -> None

Sets the content widget to display.

Parameters:

  • child — a GtkWidget

set_hide_expander

def set_hide_expander(self, hide_expander: bool) -> None

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

Parameters:

  • hide_expander — TRUE if the expander should be hidden. Otherwise FALSE.

set_indent_for_depth

def set_indent_for_depth(self, indent_for_depth: bool) -> None

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

Parameters:

  • indent_for_depth — TRUE if the child should be indented. Otherwise FALSE.

set_indent_for_icon

def set_indent_for_icon(self, 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.

Parameters:

  • indent_for_icon — TRUE if the child should be indented without expander. Otherwise FALSE.

set_list_row

def set_list_row(self, list_row: TreeListRow | None = ...) -> None

Sets the tree list row that this expander should manage.

Parameters:

  • list_row — a GtkTreeListRow

Properties

child

child: Widget  # read/write

The child widget with the actual contents.

hide_expander

hide_expander: bool  # read/write

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.

indent_for_depth

indent_for_depth: bool  # read/write

TreeExpander indents the child according to its depth.

indent_for_icon

indent_for_icon: bool  # read/write

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

item

item: GObject.Object  # read-only

The item held by this expander's row.

list_row

list_row: TreeListRow  # read/write

The list row to track for expander state.