ListBox

Object Hierarchy:

Description:

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

A GtkListBox is a vertical container that 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 TreeView, especially when the list contents has a more complicated layout than what is allowed by a CellRenderer, or when the contents is interactive (i.e. has a button in it).

Although a ListBox must have only ListBoxRow children you can add any kind of widget to it via prepend, append and insert and a ListBoxRow widget will automatically be inserted between the list and the widget.

ListBoxRows can be marked as activatable or selectable. If a row is activatable, 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 Buildable interface supports setting a child as the placeholder by specifying “placeholder” as the “type” attribute of a <child> element. See set_placeholder for info.

CSS nodes

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

istBox uses a single CSS node named list. It may carry the .separators style class, when the 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.

The main list node may also carry style classes to select the style of [list presentation](ListContainers.html#list-styles): .rich-list, .navigation-sidebar or .data-table.

Accessibility

GtkListBox uses the LIST role and GtkListBoxRow uses the LIST_ITEM role.

Namespace: Gtk

Package: gtk4

Content:

Properties:

public bool accept_unpaired_release { get; set; }
public bool activate_on_single_click { get; set; }
public SelectionMode selection_mode { get; set; }
public bool show_separators { get; set; }

Creation methods:

public ListBox ()
Creates a new ListBox 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)
This is a helper function for implementing DnD onto a ListBox.
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.
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 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 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)
By setting a header function on the this one can dynamically add headers in front of rows, depending on the contents of the row and its position in the list.
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)
By setting a sort function on the this one can dynamically reorder the rows of the list, based on the contents of the rows.
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 ()
public signal void move_cursor (MovementStep object, int p0, bool p1, bool p2)
public signal void row_activated (ListBoxRow row)
The row_activated signal is emitted when a row has been activated by the user.
public signal void row_selected (ListBoxRow? row)
The row_selected signal is emitted when a new row is selected, or (with a null row) when the selection is cleared.
public signal void select_all ()
The select_all signal is a keybinding signal which gets emitted to select all children of the box, if the selection mode permits it.
public signal void selected_rows_changed ()
The selected_rows_changed signal is emitted when the set of selected rows changes.
public signal void toggle_cursor_row ()
public signal void unselect_all ()
The unselect_all signal is a keybinding signal which gets 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