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 Gtk.Tree_View.Gtk_Tree_View, especially when the list contents has a more complicated layout than what is allowed by a Gtk.Cell_Renderer.Gtk_Cell_Renderer, or when the contents is interactive (i.e. has a button in it).
Although a Gtk.List_Box.Gtk_List_Box must have only Gtk.List_Box_Row.Gtk_List_Box_Row children you can add any kind of widget to it via Gtk.Container.Add, and a Gtk.List_Box_Row.Gtk_List_Box_Row widget will automatically be inserted between the list and the widget.
Gtk_List_Box_Rows can be marked as activatable or selectable. If a row is activatable, Gtk.List_Box.Gtk_List_Box::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.
The GtkListBox widget was added in GTK+ 3.10.
# GtkListBox as GtkBuildable
The GtkListBox implementation of the Gtk.Buildable.Gtk_Buildable interface supports setting a child as the placeholder by specifying "placeholder" as the "type" attribute of a <child> element. See Gtk.List_Box.Set_Placeholder for info.
# CSS nodes
list
â°ââ row[.activatable]
GtkListBox uses a single CSS node named list. Each GtkListBoxRow uses a single CSS node named row. The row nodes get the .activatable style class added when appropriate.
function "+"
(Widget : access Gtk_List_Box_Record'Class)
return Gtk.Buildable.Gtk_Buildable
function "-"
(Interf : Gtk.Buildable.Gtk_Buildable)
return Gtk_List_Box
Activate_On_Single_Click_Property : constant Glib.Properties.Property_Boolean;
procedure Bind_Model
(Self : not null access Gtk_List_Box_Record;
Model : Glib.List_Model.Glist_Model;
Create_Widget_Func : Gtk_List_Box_Create_Widget_Func;
User_Data_Free_Func : Glib.G_Destroy_Notify_Address)
Binds Model to Box. If Box was already bound to a model, that previous binding is destroyed. The contents of Box are cleared and then filled with widgets that represent items from Model. Box is updated whenever Model changes. If Model is null, Box is left empty. It is undefined to add or remove widgets directly (for example, with Gtk.List_Box.Insert or Gtk.Container.Add) while Box is bound to a model. Note that using a model is incompatible with the filtering and sorting functionality in GtkListBox. When using a model, filtering and sorting should be implemented by the model. Since: gtk+ 3.16
the Glib.List_Model.Glist_Model to be bound to Box
a function that creates widgets for items or null in case you also passed null as Model
function for freeing User_Data
type Cb_GObject_Gtk_List_Box_Row_Void is not null access procedure
(Self : access Glib.Object.GObject_Record'Class;
Row : not null access Gtk.List_Box_Row.Gtk_List_Box_Row_Record'Class);
type Cb_GObject_Gtk_Movement_Step_Gint_Void is not null access procedure
(Self : access Glib.Object.GObject_Record'Class;
Object : Gtk.Enums.Gtk_Movement_Step;
P0 : Glib.Gint);
type Cb_GObject_Void is not null access procedure
(Self : access Glib.Object.GObject_Record'Class);
type Cb_Gtk_List_Box_Gtk_List_Box_Row_Void is not null access procedure
(Self : access Gtk_List_Box_Record'Class;
Row : not null access Gtk.List_Box_Row.Gtk_List_Box_Row_Record'Class);
type Cb_Gtk_List_Box_Gtk_Movement_Step_Gint_Void is not null access procedure
(Self : access Gtk_List_Box_Record'Class;
Object : Gtk.Enums.Gtk_Movement_Step;
P0 : Glib.Gint);
type Cb_Gtk_List_Box_Void is not null access procedure (Self : access Gtk_List_Box_Record'Class);
procedure Drag_Highlight_Row
(Self : not null access Gtk_List_Box_Record;
Row : not null access Gtk.List_Box_Row.Gtk_List_Box_Row_Record'Class)
This is a helper function for implementing DnD onto a Gtk.List_Box.Gtk_List_Box. The passed in Row will be highlighted via Gtk.Widget.Drag_Highlight, and any previously highlighted row will be unhighlighted. The row will also be unhighlighted when the widget gets a drag leave event. Since: gtk+ 3.10
a Gtk.List_Box_Row.Gtk_List_Box_Row
procedure Drag_Unhighlight_Row
(Self : not null access Gtk_List_Box_Record)
If a row has previously been highlighted via Gtk.List_Box.Drag_Highlight_Row it will have the highlight removed. Since: gtk+ 3.10
function Get_Activate_On_Single_Click
(Self : not null access Gtk_List_Box_Record) return Boolean
Returns whether rows activate on single clicks. Since: gtk+ 3.10
True if rows are activated on single click, False otherwise
function Get_Adjustment
(Self : not null access Gtk_List_Box_Record)
return Gtk.Adjustment.Gtk_Adjustment
Gets the adjustment (if any) that the widget uses to for vertical scrolling. Since: gtk+ 3.10
the adjustment
function Get_Row_At_Index
(Self : not null access Gtk_List_Box_Record;
Index : Glib.Gint) return Gtk.List_Box_Row.Gtk_List_Box_Row
Gets the n-th child in the list (not counting headers). If _Index is negative or larger than the number of items in the list, null is returned. Since: gtk+ 3.10
the index of the row
the child Gtk.Widget.Gtk_Widget or null
function Get_Row_At_Y
(Self : not null access Gtk_List_Box_Record;
Y : Glib.Gint) return Gtk.List_Box_Row.Gtk_List_Box_Row
Gets the row at the Y position. Since: gtk+ 3.10
position
the row or null in case no row exists for the given y coordinate.
function Get_Selected_Row
(Self : not null access Gtk_List_Box_Record)
return Gtk.List_Box_Row.Gtk_List_Box_Row
Gets the selected row. Note that the box may allow multiple selection, in which case you should use Gtk.List_Box.Selected_Foreach to find all selected rows. Since: gtk+ 3.10
the selected row
function Get_Selected_Rows
(Self : not null access Gtk_List_Box_Record)
return Gtk.List_Box_Row.List_Box_Row_List.Glist
Creates a list of all selected children. Since: gtk+ 3.14
function Get_Selection_Mode
(Self : not null access Gtk_List_Box_Record)
return Gtk.Enums.Gtk_Selection_Mode
Gets the selection mode of the listbox. Since: gtk+ 3.10
a Gtk.Enums.Gtk_Selection_Mode
function Get_Type return Glib.GType
type Gtk_List_Box is access all Gtk_List_Box_Record'Class;
type Gtk_List_Box_Create_Widget_Func is access function (Item : System.Address) return Gtk.Widget.Gtk_Widget;
Called for list boxes that are bound to a Glib.List_Model.Glist_Model with Gtk.List_Box.Bind_Model for each item that gets added to the model. Versions of GTK+ prior to 3.18 called gtk_widget_show_all on the rows created by the GtkListBoxCreateWidgetFunc, but this forced all widgets inside the row to be shown, and is no longer the case. Applications should be updated to show the desired row widgets. Since: gtk+ 3.16
the item from the model for which to create a widget for
a Gtk.Widget.Gtk_Widget that represents Item
type Gtk_List_Box_Filter_Func is access function
(Row : not null access Gtk.List_Box_Row.Gtk_List_Box_Row_Record'Class)
return Boolean;
Will be called whenever the row changes or is added and lets you control if the row should be visible or not. Since: gtk+ 3.10
the row that may be filtered
True if the row should be visible, False otherwise
type Gtk_List_Box_Foreach_Func is access procedure
(Box : not null access Gtk_List_Box_Record'Class;
Row : not null access Gtk.List_Box_Row.Gtk_List_Box_Row_Record'Class);
A function used by Gtk.List_Box.Selected_Foreach. It will be called on every selected child of the Box. Since: gtk+ 3.14
a Gtk.List_Box.Gtk_List_Box
a Gtk.List_Box_Row.Gtk_List_Box_Row
function Gtk_List_Box_New return Gtk_List_Box
Creates a new Gtk.List_Box.Gtk_List_Box container. Since: gtk+ 3.10
type Gtk_List_Box_Record is new Gtk_Container_Record with null record;
type Gtk_List_Box_Sort_Func is access function
(Row1 : not null access Gtk.List_Box_Row.Gtk_List_Box_Row_Record'Class;
Row2 : not null access Gtk.List_Box_Row.Gtk_List_Box_Row_Record'Class)
return Glib.Gint;
Compare two rows to determine which should be first. Since: gtk+ 3.10
the first row
the second row
< 0 if Row1 should be before Row2, 0 if they are equal and > 0 otherwise
type Gtk_List_Box_Update_Header_Func is access procedure
(Row : not null access Gtk.List_Box_Row.Gtk_List_Box_Row_Record'Class;
Before : access Gtk.List_Box_Row.Gtk_List_Box_Row_Record'Class);
Whenever Row changes or which row is before Row changes this is called, which lets you update the header on Row. You may remove or set a new one via gtk_list_box_row_set_header or just change the state of the current header widget. Since: gtk+ 3.10
the row to update
the row before Row, or null if it is first
procedure Gtk_New (Self : out Gtk_List_Box)
Creates a new Gtk.List_Box.Gtk_List_Box container. Since: gtk+ 3.10 Initialize does nothing if the object was already created with another call to Initialize* or G_New.
package Implements_Gtk_Buildable is new Glib.Types.Implements
(Gtk.Buildable.Gtk_Buildable, Gtk_List_Box_Record, Gtk_List_Box);
procedure Initialize (Self : not null access Gtk_List_Box_Record'Class)
Creates a new Gtk.List_Box.Gtk_List_Box container. Since: gtk+ 3.10 Initialize does nothing if the object was already created with another call to Initialize* or G_New.
procedure Insert
(Self : not null access Gtk_List_Box_Record;
Child : not null access Gtk.Widget.Gtk_Widget_Record'Class;
Position : Glib.Gint)
Insert the Child into the Box at Position. If a sort function is set, the widget will actually be inserted at the calculated position and this function has the same effect of Gtk.Container.Add. If Position is -1, or larger than the total number of items in the Box, then the Child will be appended to the end. Since: gtk+ 3.10
the Gtk.Widget.Gtk_Widget to add
the position to insert Child in
procedure Invalidate_Filter (Self : not null access Gtk_List_Box_Record)
Update the filtering for all rows. Call this when result of the filter function on the Box is changed due to an external factor. For instance, this would be used if the filter function just looked for a specific search string and the entry with the search string has changed. Since: gtk+ 3.10
procedure Invalidate_Headers (Self : not null access Gtk_List_Box_Record)
Update the separators for all rows. Call this when result of the header function on the Box is changed due to an external factor. Since: gtk+ 3.10
procedure Invalidate_Sort (Self : not null access Gtk_List_Box_Record)
Update the sorting for all rows. Call this when result of the sort function on the Box is changed due to an external factor. Since: gtk+ 3.10
procedure On_Activate_Cursor_Row
(Self : not null access Gtk_List_Box_Record;
Call : Cb_GObject_Void;
Slot : not null access Glib.Object.GObject_Record'Class;
After : Boolean := False)
procedure On_Activate_Cursor_Row
(Self : not null access Gtk_List_Box_Record;
Call : Cb_Gtk_List_Box_Void;
After : Boolean := False)
procedure On_Move_Cursor
(Self : not null access Gtk_List_Box_Record;
Call : Cb_GObject_Gtk_Movement_Step_Gint_Void;
Slot : not null access Glib.Object.GObject_Record'Class;
After : Boolean := False)
Callback parameters:
procedure On_Move_Cursor
(Self : not null access Gtk_List_Box_Record;
Call : Cb_Gtk_List_Box_Gtk_Movement_Step_Gint_Void;
After : Boolean := False)
Callback parameters:
procedure On_Row_Activated
(Self : not null access Gtk_List_Box_Record;
Call : Cb_GObject_Gtk_List_Box_Row_Void;
Slot : not null access Glib.Object.GObject_Record'Class;
After : Boolean := False)
The ::row-activated signal is emitted when a row has been activated by the user.
procedure On_Row_Activated
(Self : not null access Gtk_List_Box_Record;
Call : Cb_Gtk_List_Box_Gtk_List_Box_Row_Void;
After : Boolean := False)
The ::row-activated signal is emitted when a row has been activated by the user.
procedure On_Row_Selected
(Self : not null access Gtk_List_Box_Record;
Call : Cb_GObject_Gtk_List_Box_Row_Void;
Slot : not null access Glib.Object.GObject_Record'Class;
After : Boolean := False)
The ::row-selected signal is emitted when a new row is selected, or (with a null Row) when the selection is cleared.
When the Box is using GTK_SELECTION_MULTIPLE, this signal will not give you the full picture of selection changes, and you should use the Gtk.List_Box.Gtk_List_Box::selected-rows-changed signal instead.
procedure On_Row_Selected
(Self : not null access Gtk_List_Box_Record;
Call : Cb_Gtk_List_Box_Gtk_List_Box_Row_Void;
After : Boolean := False)
The ::row-selected signal is emitted when a new row is selected, or (with a null Row) when the selection is cleared.
When the Box is using GTK_SELECTION_MULTIPLE, this signal will not give you the full picture of selection changes, and you should use the Gtk.List_Box.Gtk_List_Box::selected-rows-changed signal instead.
procedure On_Select_All
(Self : not null access Gtk_List_Box_Record;
Call : Cb_GObject_Void;
Slot : not null access Glib.Object.GObject_Record'Class;
After : Boolean := False)
The ::select-all signal is a [keybinding signal][GtkBindingSignal] which gets emitted to select all children of the box, if the selection mode permits it.
The default bindings for this signal is Ctrl-a.
procedure On_Select_All
(Self : not null access Gtk_List_Box_Record;
Call : Cb_Gtk_List_Box_Void;
After : Boolean := False)
The ::select-all signal is a [keybinding signal][GtkBindingSignal] which gets emitted to select all children of the box, if the selection mode permits it.
The default bindings for this signal is Ctrl-a.
procedure On_Selected_Rows_Changed
(Self : not null access Gtk_List_Box_Record;
Call : Cb_GObject_Void;
Slot : not null access Glib.Object.GObject_Record'Class;
After : Boolean := False)
The ::selected-rows-changed signal is emitted when the set of selected rows changes.
procedure On_Selected_Rows_Changed
(Self : not null access Gtk_List_Box_Record;
Call : Cb_Gtk_List_Box_Void;
After : Boolean := False)
The ::selected-rows-changed signal is emitted when the set of selected rows changes.
procedure On_Toggle_Cursor_Row
(Self : not null access Gtk_List_Box_Record;
Call : Cb_GObject_Void;
Slot : not null access Glib.Object.GObject_Record'Class;
After : Boolean := False)
procedure On_Toggle_Cursor_Row
(Self : not null access Gtk_List_Box_Record;
Call : Cb_Gtk_List_Box_Void;
After : Boolean := False)
procedure On_Unselect_All
(Self : not null access Gtk_List_Box_Record;
Call : Cb_GObject_Void;
Slot : not null access Glib.Object.GObject_Record'Class;
After : Boolean := False)
The ::unselect-all signal is a [keybinding signal][GtkBindingSignal] which gets emitted to unselect all children of the box, if the selection mode permits it.
The default bindings for this signal is Ctrl-Shift-a.
procedure On_Unselect_All
(Self : not null access Gtk_List_Box_Record;
Call : Cb_Gtk_List_Box_Void;
After : Boolean := False)
The ::unselect-all signal is a [keybinding signal][GtkBindingSignal] which gets emitted to unselect all children of the box, if the selection mode permits it.
The default bindings for this signal is Ctrl-Shift-a.
procedure Prepend
(Self : not null access Gtk_List_Box_Record;
Child : not null access Gtk.Widget.Gtk_Widget_Record'Class)
Prepend a widget to the list. If a sort function is set, the widget will actually be inserted at the calculated position and this function has the same effect of Gtk.Container.Add. Since: gtk+ 3.10
the Gtk.Widget.Gtk_Widget to add
procedure Select_All (Self : not null access Gtk_List_Box_Record)
Select all children of Box, if the selection mode allows it. Since: gtk+ 3.14
procedure Select_Row
(Self : not null access Gtk_List_Box_Record;
Row : access Gtk.List_Box_Row.Gtk_List_Box_Row_Record'Class)
Make Row the currently selected row. Since: gtk+ 3.10
The row to select or null
procedure Selected_Foreach
(Self : not null access Gtk_List_Box_Record;
Func : Gtk_List_Box_Foreach_Func)
Calls a function for each selected child. Note that the selection cannot be modified from within this function. Since: gtk+ 3.14
the function to call for each selected child
Selection_Mode_Property : constant Gtk.Enums.Property_Gtk_Selection_Mode;
procedure Set_Activate_On_Single_Click
(Self : not null access Gtk_List_Box_Record;
Single : Boolean)
If Single is True, rows will be activated when you click on them, otherwise you need to double-click. Since: gtk+ 3.10
a boolean
procedure Set_Adjustment
(Self : not null access Gtk_List_Box_Record;
Adjustment : access Gtk.Adjustment.Gtk_Adjustment_Record'Class)
Sets the adjustment (if any) that the widget uses to for vertical scrolling. For instance, this is used to get the page size for PageUp/Down key handling. In the normal case when the Box is packed inside a Gtk.Scrolled_Window.Gtk_Scrolled_Window the adjustment from that will be picked up automatically, so there is no need to manually do that. Since: gtk+ 3.10
the adjustment, or null
procedure Set_Filter_Func
(Self : not null access Gtk_List_Box_Record;
Filter_Func : Gtk_List_Box_Filter_Func)
By setting a filter function on the Box one can decide dynamically which of the rows to show. For instance, to implement a search function on a list that filters the original list to only show the matching rows. The Filter_Func will be called for each row after the call, and it will continue to be called each time a row changes (via Gtk.List_Box_Row.Changed) or when Gtk.List_Box.Invalidate_Filter is called. Note that using a filter function is incompatible with using a model (see Gtk.List_Box.Bind_Model). Since: gtk+ 3.10
callback that lets you filter which rows to show
procedure Set_Header_Func
(Self : not null access Gtk_List_Box_Record;
Update_Header : Gtk_List_Box_Update_Header_Func)
By setting a header function on the Box one can dynamically add headers in front of rows, depending on the contents of the row and its position in the list. For instance, one could use it to add headers in front of the first item of a new kind, in a list sorted by the kind. The Update_Header can look at the current header widget using Gtk.List_Box_Row.Get_Header and either update the state of the widget as needed, or set a new one using Gtk.List_Box_Row.Set_Header. If no header is needed, set the header to null. Note that you may get many calls Update_Header to this for a particular row when e.g. changing things that don't affect the header. In this case it is important for performance to not blindly replace an existing header with an identical one. The Update_Header function will be called for each row after the call, and it will continue to be called each time a row changes (via Gtk.List_Box_Row.Changed) and when the row before changes (either by Gtk.List_Box_Row.Changed on the previous row, or when the previous row becomes a different row). It is also called for all rows when Gtk.List_Box.Invalidate_Headers is called. Since: gtk+ 3.10
callback that lets you add row headers
procedure Set_Placeholder
(Self : not null access Gtk_List_Box_Record;
Placeholder : access Gtk.Widget.Gtk_Widget_Record'Class)
Sets the placeholder widget that is shown in the list when it doesn't display any visible children. Since: gtk+ 3.10
a Gtk.Widget.Gtk_Widget or null
procedure Set_Selection_Mode
(Self : not null access Gtk_List_Box_Record;
Mode : Gtk.Enums.Gtk_Selection_Mode)
Sets how selection works in the listbox. See Gtk.Enums.Gtk_Selection_Mode for details. Since: gtk+ 3.10
The Gtk.Enums.Gtk_Selection_Mode
procedure Set_Sort_Func
(Self : not null access Gtk_List_Box_Record;
Sort_Func : Gtk_List_Box_Sort_Func)
By setting a sort function on the Box one can dynamically reorder the rows of the list, based on the contents of the rows. The Sort_Func will be called for each row after the call, and will continue to be called each time a row changes (via Gtk.List_Box_Row.Changed) and when Gtk.List_Box.Invalidate_Sort is called. Note that using a sort function is incompatible with using a model (see Gtk.List_Box.Bind_Model). Since: gtk+ 3.10
the sort function
Signal_Activate_Cursor_Row : constant Glib.Signal_Name := "activate-cursor-row";
Signal_Move_Cursor : constant Glib.Signal_Name := "move-cursor";
Callback parameters:
Signal_Row_Activated : constant Glib.Signal_Name := "row-activated";
The ::row-activated signal is emitted when a row has been activated by the user.
Signal_Row_Selected : constant Glib.Signal_Name := "row-selected";
The ::row-selected signal is emitted when a new row is selected, or (with a null Row) when the selection is cleared.
When the Box is using GTK_SELECTION_MULTIPLE, this signal will not give you the full picture of selection changes, and you should use the Gtk.List_Box.Gtk_List_Box::selected-rows-changed signal instead.
Signal_Select_All : constant Glib.Signal_Name := "select-all";
The ::select-all signal is a [keybinding signal][GtkBindingSignal] which gets emitted to select all children of the box, if the selection mode permits it.
The default bindings for this signal is Ctrl-a.
Signal_Selected_Rows_Changed : constant Glib.Signal_Name := "selected-rows-changed";
The ::selected-rows-changed signal is emitted when the set of selected rows changes.
Signal_Toggle_Cursor_Row : constant Glib.Signal_Name := "toggle-cursor-row";
Signal_Unselect_All : constant Glib.Signal_Name := "unselect-all";
The ::unselect-all signal is a [keybinding signal][GtkBindingSignal] which gets emitted to unselect all children of the box, if the selection mode permits it.
The default bindings for this signal is Ctrl-Shift-a.
procedure Unselect_All (Self : not null access Gtk_List_Box_Record)
Unselect all children of Box, if the selection mode allows it. Since: gtk+ 3.14
procedure Unselect_Row
(Self : not null access Gtk_List_Box_Record;
Row : not null access Gtk.List_Box_Row.Gtk_List_Box_Row_Record'Class)
Unselects a single row of Box, if the selection mode allows it. Since: gtk+ 3.14
the row to unselected