GtkTreeExpander

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 GtkTreeListModel. 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 GtkListItem: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 GtkTreeListRow items which can be set via gtk_tree_expander_set_list_row() on the expander. The expander will then watch that row item automatically. gtk_tree_expander_set_child() sets the widget that displays the actual row contents.

GtkTreeExpander can be modified with properties such as GtkTreeExpander:indent-for-icon, GtkTreeExpander:indent-for-depth, and GtkTreeExpander:hide-expander to achieve a different appearance. This can even be done to influence individual rows, for example by binding the GtkTreeExpander: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:

• + or * expands the expander.
• - or / collapses the expander.
• Left and right arrow keys, when combined with Shift or Ctrl+Shift, will expand or collapse, depending on the locale’s text direction.
• Ctrl+␣ 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 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.