ListBox

Object Hierarchy:

Description:

[ CCode ( type_id = "gtk_list_box_get_type ()" ) ]
public sealed class ListBox : Widget, Accessible, Buildable, ConstraintTarget

Shows a vertical list.

A `GtkListBox` only contains `GtkListBoxRow` 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 `GtkListBox` is often an alternative to `GtkTreeView`, especially when the list contents has a more complicated layout than what is allowed by a `GtkCellRenderer`, or when the contents is interactive (i.e. has a button in it).

Although a `GtkListBox` must have only `GtkListBoxRow` children, you can add any kind of widget to it via [method@Gtk.ListBox.prepend], [ method@Gtk.ListBox.append] and [method@Gtk.ListBox.insert] and a `GtkListBoxRow` 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:GtkListBox: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 `GtkListBox` implementation of the `GtkBuildable` interface supports setting a child as the placeholder by specifying “placeholder” as the “type” attribute of a `<child>` element. See [method@Gtk.ListBox.set_placeholder] for info.

Shortcuts and Gestures

The following signals have default keybindings:

[signal@Gtk.ListBox:GtkListBox:move-cursor]
[signal@Gtk.ListBox:GtkListBox:select-all]
[signal@Gtk.ListBox:GtkListBox:toggle-cursor-row]
[signal@Gtk.ListBox:GtkListBox:unselect-all]

CSS nodes

``` list.separators.navigation-sidebar ╰── row[.activatable] ```

`GtkListBox` 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 `GtkListBoxRow` 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](section-list-widget.html#list-styles): .rich-list, .navigation-sidebar or .data-table.

Accessibility

`GtkListBox` uses the [enum@Gtk.AccessibleRole.list] role and `GtkListBoxRow` uses the [enum@Gtk.AccessibleRole.list_item] role.

Namespace: Gtk

Package: gtk4

Content:

Properties:

public bool accept_unpaired_release { get; set; }
Whether to accept unpaired release events.
public bool activate_on_single_click { get; set; }
Determines whether children can be activated with a single click, or require a double-click.
public SelectionMode selection_mode { get; set; }
The selection mode used by the list box.
public bool show_separators { get; set; }
Whether to show separators between rows.
public ListTabBehavior tab_behavior { get; set; }
Behavior of the <kbd>Tab</kbd> key

Creation methods:

public ListBox ()
Creates a new `GtkListBox` container.

Methods:

public void append (Widget child)
Append a widget to the list.
public void bind_model (ListModel? model, owned ListBoxCreateWidgetFunc? create_widget_func)
Binds model to this.
public void drag_highlight_row (ListBoxRow row)
Add a drag highlight to a row.
public void drag_unhighlight_row ()
If a row has previously been highlighted via drag_highlight_row, it will have the highlight removed.
public bool get_activate_on_single_click ()
Returns whether rows activate on single clicks.
public unowned Adjustment? get_adjustment ()
Gets the adjustment (if any) that the widget uses to for vertical scrolling.
public unowned ListBoxRow? get_row_at_index (int index_)
Gets the n-th child in the list (not counting headers).
public unowned ListBoxRow? get_row_at_y (int y)
Gets the row at the y position.
public unowned ListBoxRow? get_selected_row ()
Gets the selected row, or null if no rows are selected.
public List<unowned ListBoxRow> get_selected_rows ()
Creates a list of all selected children.
public SelectionMode get_selection_mode ()
Gets the selection mode of the listbox.
public bool get_show_separators ()
Returns whether the list box should show separators between rows.
public ListTabBehavior get_tab_behavior ()
Returns the behavior of the <kbd>Tab</kbd> and <kbd>Shift </kbd>+<kbd>Tab</kbd> keys.
public void insert (Widget child, int position)
Insert the child into the this at position.
public void invalidate_filter ()
Update the filtering for all rows.
public void invalidate_headers ()
Update the separators for all rows.
public void invalidate_sort ()
Update the sorting for all rows.
public void prepend (Widget child)
Prepend a widget to the list.
public void remove (Widget child)
Removes a child from this.
public void remove_all ()
Removes all rows from this.
public void select_row (ListBoxRow? row)
Make row the currently selected row.
public void selected_foreach (ListBoxForeachFunc func)
Calls a function for each selected child.
public void set_activate_on_single_click (bool single)
If single is true, rows will be activated when you click on them, otherwise you need to double-click.
public void set_adjustment (Adjustment? adjustment)
Sets the adjustment (if any) that the widget uses to for vertical scrolling.
public void set_filter_func (owned ListBoxFilterFunc? filter_func)
By setting a filter function on the this one can decide dynamically which of the rows to show.
public void set_header_func (owned ListBoxUpdateHeaderFunc? update_header)
Sets a header function.
public void set_placeholder (Widget? placeholder)
Sets the placeholder widget that is shown in the list when it doesn't display any visible children.
public void set_selection_mode (SelectionMode mode)
Sets how selection works in the listbox.
public void set_show_separators (bool show_separators)
Sets whether the list box should show separators between rows.
public void set_sort_func (owned ListBoxSortFunc? sort_func)
Sets a sort function.
public void set_tab_behavior (ListTabBehavior behavior)
Sets the behavior of the <kbd>Tab</kbd> and <kbd>Shift< /kbd>+<kbd>Tab</kbd> keys.
public void unselect_row (ListBoxRow row)
Unselects a single row of this, if the selection mode allows it.

Signals:

public signal void activate_cursor_row ()
Emitted when the cursor row is activated.
public signal void move_cursor (MovementStep step, int count, bool extend, bool modify)
Emitted when the user initiates a cursor movement.
public signal void row_activated (ListBoxRow row)
Emitted when a row has been activated by the user.
public signal void row_selected (ListBoxRow? row)
Emitted when a new row is selected, or (with a null row) when the selection is cleared.
public signal void select_all ()
Emitted to select all children of the box, if the selection mode permits it.
public signal void selected_rows_changed ()
Emitted when the set of selected rows changes.
public signal void toggle_cursor_row ()
Emitted when the cursor row is toggled.
public signal void unselect_all ()
Emitted to unselect all children of the box, if the selection mode permits it.

Inherited Members:

All known members inherited from class Gtk.Widget

All known members inherited from class GLib.Object

All known members inherited from interface Gtk.Accessible

All known members inherited from interface Gtk.Buildable