struct GtkListBox

struct GtkListBox;

struct GtkListBoxRow

struct GtkListBoxRow;

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 *list_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 *list_box,
                                                         GtkWidget *child,
                                                         gint position);

Insert the child into the list_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 list_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 *list_box,
                                                         GtkListBoxRow *row);

Make row the currently selected row.

Since 3.10

gtk_list_box_get_selected_row ()

GtkListBoxRow *     gtk_list_box_get_selected_row       (GtkListBox *list_box);

Gets the selected row.

Since 3.10

gtk_list_box_set_selection_mode ()

void                gtk_list_box_set_selection_mode     (GtkListBox *list_box,
                                                         GtkSelectionMode mode);

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

Note: GtkListBox does not support GTK_SELECTION_MULTIPLE.

Since 3.10

gtk_list_box_get_selection_mode ()

GtkSelectionMode    gtk_list_box_get_selection_mode     (GtkListBox *list_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 *list_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 *list_box);

Returns whether rows activate on single clicks.

Since 3.10

gtk_list_box_get_adjustment ()

GtkAdjustment *     gtk_list_box_get_adjustment         (GtkListBox *list_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 *list_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 list_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 *list_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 *list_box,
                                                         gint index_);

Gets the n:th child in the list (not counting headers).

Since 3.10

gtk_list_box_get_row_at_y ()

GtkListBoxRow *     gtk_list_box_get_row_at_y           (GtkListBox *list_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 *list_box);

Update the filtering for all rows. Call this when result of the filter function on the list_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 *list_box);

Update the separators for all rows. Call this when result of the header function on the list_box is changed due to an external factor.

Since 3.10

gtk_list_box_invalidate_sort ()

void                gtk_list_box_invalidate_sort        (GtkListBox *list_box);

Update the sorting for all rows. Call this when result of the sort function on the list_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 *list_box,
                                                         GtkListBoxFilterFunc filter_func,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy);

By setting a filter function on the list_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.

Since 3.10

gtk_list_box_set_header_func ()

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

By setting a header function on the list_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 exisiting header widh 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 *list_box,
                                                         GtkListBoxSortFunc sort_func,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy);

By setting a sort function on the list_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.

Since 3.10

gtk_list_box_drag_highlight_row ()

void                gtk_list_box_drag_highlight_row     (GtkListBox *list_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 *list_box);

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

Since 3.10

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_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_get_type ()

GType               gtk_list_box_row_get_type           (void);

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

The "activate-on-single-click" property

  "activate-on-single-click" gboolean              : Read / Write

Activate row on a single click.

Default value: TRUE

The "selection-mode" property

  "selection-mode"           GtkSelectionMode      : Read / Write

The selection mode.

Default value: GTK_SELECTION_SINGLE

The "activate-cursor-row" signal

void                user_function                      (GtkListBox *listbox,
                                                        gpointer    user_data)      : Action

The "move-cursor" signal

void                user_function                      (GtkListBox     *listbox,
                                                        GtkMovementStep arg1,
                                                        gint            arg2,
                                                        gpointer        user_data)      : Action

The "row-activated" signal

void                user_function                      (GtkListBox    *list_box,
                                                        GtkListBoxRow *row,
                                                        gpointer       user_data)      : Run Last

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

Since 3.10

The "row-selected" signal

void                user_function                      (GtkListBox    *list_box,
                                                        GtkListBoxRow *row,
                                                        gpointer       user_data)      : Run Last

The ::row-selected signal is emitted when a new row is selected, or (with a NULL row) when the selection is cleared.

Since 3.10

The "toggle-cursor-row" signal

void                user_function                      (GtkListBox *listbox,
                                                        gpointer    user_data)      : Action

The "activate" signal

void                user_function                      (GtkListBoxRow *listboxrow,
                                                        gpointer       user_data)       : Action