GtkListBox

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 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.

GtkListBoxFilterFunc ()

gboolean
(*GtkListBoxFilterFunc) (GtkListBoxRow *row,
                         gpointer user_data);

Will be called whenever the row changes or is added and lets you control if the row should be visible or not.

Since: 3.10

GtkListBoxSortFunc ()

gint
(*GtkListBoxSortFunc) (GtkListBoxRow *row1,
                       GtkListBoxRow *row2,
                       gpointer user_data);

Compare two rows to determine which should be first.

Since: 3.10

GtkListBoxUpdateHeaderFunc ()

void
(*GtkListBoxUpdateHeaderFunc) (GtkListBoxRow *row,
                               GtkListBoxRow *before,
                               gpointer user_data);

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: 3.10

gtk_list_box_new ()

GtkWidget *
gtk_list_box_new (void);

Creates a new GtkListBox container.

Since: 3.10

gtk_list_box_prepend ()

void
gtk_list_box_prepend (GtkListBox *box,
                      GtkWidget *child);

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: 3.10

gtk_list_box_insert ()

void
gtk_list_box_insert (GtkListBox *box,
                     GtkWidget *child,
                     gint position);

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: 3.10

gtk_list_box_select_row ()

void
gtk_list_box_select_row (GtkListBox *box,
                         GtkListBoxRow *row);

Make row the currently selected row.

Since: 3.10

gtk_list_box_unselect_row ()

void
gtk_list_box_unselect_row (GtkListBox *box,
                           GtkListBoxRow *row);

Unselects a single row of box , if the selection mode allows it.

Since: 3.14

gtk_list_box_select_all ()

void
gtk_list_box_select_all (GtkListBox *box);

Select all children of box , if the selection mode allows it.

Since: 3.14

gtk_list_box_unselect_all ()

void
gtk_list_box_unselect_all (GtkListBox *box);

Unselect all children of box , if the selection mode allows it.

Since: 3.14

gtk_list_box_get_selected_row ()

GtkListBoxRow *
gtk_list_box_get_selected_row (GtkListBox *box);

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: 3.10

GtkListBoxForeachFunc ()

void
(*GtkListBoxForeachFunc) (GtkListBox *box,
                          GtkListBoxRow *row,
                          gpointer user_data);

A function used by gtk_list_box_selected_foreach(). It will be called on every selected child of the box .

Since: 3.14

gtk_list_box_selected_foreach ()

void
gtk_list_box_selected_foreach (GtkListBox *box,
                               GtkListBoxForeachFunc func,
                               gpointer data);

Calls a function for each selected child.

Note that the selection cannot be modified from within this function.

Since: 3.14

gtk_list_box_get_selected_rows ()

GList *
gtk_list_box_get_selected_rows (GtkListBox *box);

Creates a list of all selected children.

Since: 3.14

gtk_list_box_set_selection_mode ()

void
gtk_list_box_set_selection_mode (GtkListBox *box,
                                 GtkSelectionMode mode);

Sets how selection works in the listbox. See GtkSelectionMode for details.

Since: 3.10

gtk_list_box_get_selection_mode ()

GtkSelectionMode
gtk_list_box_get_selection_mode (GtkListBox *box);

Gets the selection mode of the listbox.

Since: 3.10

gtk_list_box_set_activate_on_single_click ()

void
gtk_list_box_set_activate_on_single_click
                               (GtkListBox *box,
                                gboolean single);

If single is TRUE, rows will be activated when you click on them, otherwise you need to double-click.

Since: 3.10

gtk_list_box_get_activate_on_single_click ()

gboolean
gtk_list_box_get_activate_on_single_click
                               (GtkListBox *box);

Returns whether rows activate on single clicks.

Since: 3.10

gtk_list_box_get_adjustment ()

GtkAdjustment *
gtk_list_box_get_adjustment (GtkListBox *box);

Gets the adjustment (if any) that the widget uses to for vertical scrolling.

Since: 3.10

gtk_list_box_set_adjustment ()

void
gtk_list_box_set_adjustment (GtkListBox *box,
                             GtkAdjustment *adjustment);

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 GtkScrolledWindow the adjustment from that will be picked up automatically, so there is no need to manually do that.

Since: 3.10

gtk_list_box_set_placeholder ()

void
gtk_list_box_set_placeholder (GtkListBox *box,
                              GtkWidget *placeholder);

Sets the placeholder widget that is shown in the list when it doesn't display any visible children.

Since: 3.10

gtk_list_box_get_row_at_index ()

GtkListBoxRow *
gtk_list_box_get_row_at_index (GtkListBox *box,
                               gint index_);

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: 3.10

gtk_list_box_get_row_at_y ()

GtkListBoxRow *
gtk_list_box_get_row_at_y (GtkListBox *box,
                           gint y);

Gets the row at the y position.

Since: 3.10

gtk_list_box_invalidate_filter ()

void
gtk_list_box_invalidate_filter (GtkListBox *box);

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: 3.10

gtk_list_box_invalidate_headers ()

void
gtk_list_box_invalidate_headers (GtkListBox *box);

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: 3.10

gtk_list_box_invalidate_sort ()

void
gtk_list_box_invalidate_sort (GtkListBox *box);

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: 3.10

gtk_list_box_set_filter_func ()

void
gtk_list_box_set_filter_func (GtkListBox *box,
                              GtkListBoxFilterFunc filter_func,
                              gpointer user_data,
                              GDestroyNotify destroy);

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: 3.10

gtk_list_box_set_header_func ()

void
gtk_list_box_set_header_func (GtkListBox *box,
                              GtkListBoxUpdateHeaderFunc update_header,
                              gpointer user_data,
                              GDestroyNotify destroy);

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: 3.10

gtk_list_box_set_sort_func ()

void
gtk_list_box_set_sort_func (GtkListBox *box,
                            GtkListBoxSortFunc sort_func,
                            gpointer user_data,
                            GDestroyNotify destroy);

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: 3.10

gtk_list_box_drag_highlight_row ()

void
gtk_list_box_drag_highlight_row (GtkListBox *box,
                                 GtkListBoxRow *row);

This is a helper function for implementing DnD onto a GtkListBox. The passed in row will be highlighted via gtk_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: 3.10

gtk_list_box_drag_unhighlight_row ()

void
gtk_list_box_drag_unhighlight_row (GtkListBox *box);

If a row has previously been highlighted via gtk_list_box_drag_highlight_row() it will have the highlight removed.

Since: 3.10

GtkListBoxCreateWidgetFunc ()

GtkWidget *
(*GtkListBoxCreateWidgetFunc) (gpointer item,
                               gpointer user_data);

Called for list boxes that are bound to a GListModel 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: 3.16

gtk_list_box_bind_model ()

void
gtk_list_box_bind_model (GtkListBox *box,
                         GListModel *model,
                         GtkListBoxCreateWidgetFunc create_widget_func,
                         gpointer user_data,
                         GDestroyNotify user_data_free_func);

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: 3.16

gtk_list_box_row_new ()

GtkWidget *
gtk_list_box_row_new (void);

Creates a new GtkListBoxRow, to be used as a child of a GtkListBox.

Since: 3.10

gtk_list_box_row_changed ()

void
gtk_list_box_row_changed (GtkListBoxRow *row);

Marks row as changed, causing any state that depends on this to be updated. This affects sorting, filtering and headers.

Note that calls to this method must be in sync with the data used for the row functions. For instance, if the list is mirroring some external data set, and *two* rows changed in the external data set then when you call gtk_list_box_row_changed() on the first row the sort function must only read the new data for the first of the two changed rows, otherwise the resorting of the rows will be wrong.

This generally means that if you don’t fully control the data model you have to duplicate the data that affects the listbox row functions into the row widgets themselves. Another alternative is to call gtk_list_box_invalidate_sort() on any model change, but that is more expensive.

Since: 3.10

gtk_list_box_row_is_selected ()

gboolean
gtk_list_box_row_is_selected (GtkListBoxRow *row);

Returns whether the child is currently selected in its GtkListBox container.

Since: 3.14

gtk_list_box_row_get_header ()

GtkWidget *
gtk_list_box_row_get_header (GtkListBoxRow *row);

Returns the current header of the row . This can be used in a GtkListBoxUpdateHeaderFunc to see if there is a header set already, and if so to update the state of it.

Since: 3.10

gtk_list_box_row_set_header ()

void
gtk_list_box_row_set_header (GtkListBoxRow *row,
                             GtkWidget *header);

Sets the current header of the row . This is only allowed to be called from a GtkListBoxUpdateHeaderFunc. It will replace any existing header in the row, and be shown in front of the row in the listbox.

Since: 3.10

gtk_list_box_row_get_index ()

gint
gtk_list_box_row_get_index (GtkListBoxRow *row);

Gets the current index of the row in its GtkListBox container.

Since: 3.10

gtk_list_box_row_set_activatable ()

void
gtk_list_box_row_set_activatable (GtkListBoxRow *row,
                                  gboolean activatable);

Set the “activatable” property for this row.

Since: 3.14

gtk_list_box_row_get_activatable ()

gboolean
gtk_list_box_row_get_activatable (GtkListBoxRow *row);

Gets the value of the “activatable” property for this row.

Since: 3.14

gtk_list_box_row_set_selectable ()

void
gtk_list_box_row_set_selectable (GtkListBoxRow *row,
                                 gboolean selectable);

Set the “selectable” property for this row.

Since: 3.14

gtk_list_box_row_get_selectable ()

gboolean
gtk_list_box_row_get_selectable (GtkListBoxRow *row);

Gets the value of the “selectable” property for this row.

Since: 3.14

struct GtkListBox

struct GtkListBox;

struct GtkListBoxClass

struct GtkListBoxClass {
  GtkContainerClass parent_class;

  void (*row_selected)        (GtkListBox      *box,
                               GtkListBoxRow   *row);
  void (*row_activated)       (GtkListBox      *box,
                               GtkListBoxRow   *row);
  void (*activate_cursor_row) (GtkListBox      *box);
  void (*toggle_cursor_row)   (GtkListBox      *box);
  void (*move_cursor)         (GtkListBox      *box,
                               GtkMovementStep  step,
                               gint             count);
  void (*selected_rows_changed) (GtkListBox    *box);
  void (*select_all)            (GtkListBox    *box);
  void (*unselect_all)          (GtkListBox    *box);
};

struct GtkListBoxRow

struct GtkListBoxRow;

struct GtkListBoxRowClass

struct GtkListBoxRowClass {
  GtkBinClass parent_class;

  void (* activate) (GtkListBoxRow *row);
};

The “activate-on-single-click” property

  “activate-on-single-click” gboolean

Activate row on a single click.

Owner: GtkListBox

Flags: Read / Write

Default value: TRUE

The “selection-mode” property

  “selection-mode”           GtkSelectionMode

The selection mode.

Owner: GtkListBox

Flags: Read / Write

Default value: GTK_SELECTION_SINGLE

The “activatable” property

  “activatable”              gboolean

The property determines whether the “row-activated” signal will be emitted for this row.

Owner: GtkListBoxRow

Flags: Read / Write

Default value: TRUE

Since: 3.14

The “selectable” property

  “selectable”               gboolean

The property determines whether this row can be selected.

Owner: GtkListBoxRow

Flags: Read / Write

Default value: TRUE

Since: 3.14

The “activate-cursor-row” signal

void
user_function (GtkListBox *listbox,
               gpointer    user_data)

Flags: Action

The “move-cursor” signal

void
user_function (GtkListBox     *listbox,
               GtkMovementStep arg1,
               int             arg2,
               gpointer        user_data)

Flags: Action

The “row-activated” signal

void
user_function (GtkListBox    *box,
               GtkListBoxRow *row,
               gpointer       user_data)

The ::row-activated signal is emitted when a row has been activated by the user.

Flags: Run Last

Since: 3.10

The “row-selected” signal

void
user_function (GtkListBox    *box,
               GtkListBoxRow *row,
               gpointer       user_data)

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 “selected-rows-changed” signal instead.

Flags: Run Last

Since: 3.10

The “select-all” signal

void
user_function (GtkListBox *box,
               gpointer    user_data)

The ::select-all signal is a keybinding signal 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.

Flags: Action

Since: 3.14

The “selected-rows-changed” signal

void
user_function (GtkListBox *box,
               gpointer    user_data)

The ::selected-rows-changed signal is emitted when the set of selected rows changes.

Flags: Run First

Since: 3.14

The “toggle-cursor-row” signal

void
user_function (GtkListBox *listbox,
               gpointer    user_data)

Flags: Action

The “unselect-all” signal

void
user_function (GtkListBox *box,
               gpointer    user_data)

The ::unselect-all signal is a keybinding signal 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.

Flags: Action

Since: 3.14

The “activate” signal

void
user_function (GtkListBoxRow *listboxrow,
               gpointer       user_data)

This is a keybinding signal, which will cause this row to be activated.

If you want to be notified when the user activates a row (by key or not), use the “row-activated” signal on the row’s parent GtkListBox.

Flags: Action

Since: 3.10