A gtk.list_box.ListBox only contains gtk.list_box_row.ListBoxRow children. These rows can
by dynamically sorted and filtered, and headers can be added dynamically
depending on the row content. It also allows keyboard and mouse navigation
and selection like a typical list.
GtkListBoxRows can be marked as activatable or selectable. If a row is
activatable, signal@Gtk.ListBox::row-activated will be emitted for it when
the user tries to activate it. If it is selectable, the row will be marked
as selected when the user tries to select it.
gtk.list_box.ListBox uses a single CSS node named list. It may carry the .separators
style class, when the property@Gtk.ListBox:show-separators property is set.
Each gtk.list_box_row.ListBoxRow uses a single CSS node named row. The row nodes get the
.activatable style class added when appropriate.
It may also carry the .boxed-list style class. In this case, the list will be
automatically surrounded by a frame and have separators.
The main list node may also carry style classes to select
the style of list presentation:
.rich-list, .navigation-sidebar or .data-table.
gtk.list_box.ListBox is a vertical list.
A gtk.list_box.ListBox only contains gtk.list_box_row.ListBoxRow children. These rows can by dynamically sorted and filtered, and headers can be added dynamically depending on the row content. It also allows keyboard and mouse navigation and selection like a typical list.
Using gtk.list_box.ListBox is often an alternative to gtk.tree_view.TreeView, especially when the list contents has a more complicated layout than what is allowed by a gtk.cell_renderer.CellRenderer, or when the contents is interactive (i.e. has a button in it).
Although a gtk.list_box.ListBox must have only gtk.list_box_row.ListBoxRow children, you can add any kind of widget to it via gtk.list_box.ListBox.prepend, gtk.list_box.ListBox.append and gtk.list_box.ListBox.insert and a gtk.list_box_row.ListBoxRow widget will automatically be inserted between the list and the widget.
GtkListBoxRows can be marked as activatable or selectable. If a row is activatable, signal@Gtk.ListBox::row-activated will be emitted for it when the user tries to activate it. If it is selectable, the row will be marked as selected when the user tries to select it.
GtkListBox as GtkBuildable
The gtk.list_box.ListBox implementation of the gtk.buildable.Buildable interface supports setting a child as the placeholder by specifying “placeholder” as the “type” attribute of a <child> element. See gtk.list_box.ListBox.setPlaceholder for info.
CSS nodes
gtk.list_box.ListBox uses a single CSS node named list. It may carry the .separators style class, when the property@Gtk.ListBox:show-separators property is set. Each gtk.list_box_row.ListBoxRow uses a single CSS node named row. The row nodes get the .activatable style class added when appropriate.
It may also carry the .boxed-list style class. In this case, the list will be automatically surrounded by a frame and have separators.
The main list node may also carry style classes to select the style of list presentation: .rich-list, .navigation-sidebar or .data-table.
Accessibility
gtk.list_box.ListBox uses the gtk.types.AccessibleRole.List role and gtk.list_box_row.ListBoxRow uses the gtk.types.AccessibleRole.ListItem role.