GTK+ 3 Reference Manual: GtkListBox

## GtkListBox GtkListBox — A list container |

## Synopsis

    #include <gtk/gtk.h>

    struct              GtkListBox;
    struct              GtkListBoxRow;
    gboolean            (*GtkListBoxFilterFunc)             (GtkListBoxRow *row,
                                                             gpointer user_data);
    gint                (*GtkListBoxSortFunc)               (GtkListBoxRow *row1,
                                                             GtkListBoxRow *row2,
                                                             gpointer user_data);
    void                (*GtkListBoxUpdateHeaderFunc)       (GtkListBoxRow *row,
                                                             GtkListBoxRow *before,
                                                             gpointer user_data);
    GtkWidget *         gtk_list_box_new                    (void);
    void                gtk_list_box_prepend                (GtkListBox *list_box,
                                                             GtkWidget *child);
    void                gtk_list_box_insert                 (GtkListBox *list_box,
                                                             GtkWidget *child,
                                                             gint position);
    void                gtk_list_box_select_row             (GtkListBox *list_box,
                                                             GtkListBoxRow *row);
    GtkListBoxRow *     gtk_list_box_get_selected_row       (GtkListBox *list_box);
    void                gtk_list_box_set_selection_mode     (GtkListBox *list_box,
                                                             GtkSelectionMode mode);
    GtkSelectionMode    gtk_list_box_get_selection_mode     (GtkListBox *list_box);
    void                gtk_list_box_set_activate_on_single_click
                                                            (GtkListBox *list_box,
                                                             gboolean single);
    gboolean            gtk_list_box_get_activate_on_single_click
                                                            (GtkListBox *list_box);
    GtkAdjustment *     gtk_list_box_get_adjustment         (GtkListBox *list_box);
    void                gtk_list_box_set_adjustment         (GtkListBox *list_box,
                                                             GtkAdjustment *adjustment);
    void                gtk_list_box_set_placeholder        (GtkListBox *list_box,
                                                             GtkWidget *placeholder);
    GtkListBoxRow *     gtk_list_box_get_row_at_index       (GtkListBox *list_box,
                                                             gint index_);
    GtkListBoxRow *     gtk_list_box_get_row_at_y           (GtkListBox *list_box,
                                                             gint y);
    void                gtk_list_box_invalidate_filter      (GtkListBox *list_box);
    void                gtk_list_box_invalidate_headers     (GtkListBox *list_box);
    void                gtk_list_box_invalidate_sort        (GtkListBox *list_box);
    void                gtk_list_box_set_filter_func        (GtkListBox *list_box,
                                                             GtkListBoxFilterFunc filter_func,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy);
    void                gtk_list_box_set_header_func        (GtkListBox *list_box,
                                                             GtkListBoxUpdateHeaderFunc update_header,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy);
    void                gtk_list_box_set_sort_func          (GtkListBox *list_box,
                                                             GtkListBoxSortFunc sort_func,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy);
    void                gtk_list_box_drag_highlight_row     (GtkListBox *list_box,
                                                             GtkListBoxRow *row);
    void                gtk_list_box_drag_unhighlight_row   (GtkListBox *list_box);
    GtkWidget *         gtk_list_box_row_new                (void);
    void                gtk_list_box_row_changed            (GtkListBoxRow *row);
    GtkWidget *         gtk_list_box_row_get_header         (GtkListBoxRow *row);
    GType               gtk_list_box_row_get_type           (void);
    void                gtk_list_box_row_set_header         (GtkListBoxRow *row,
                                                             GtkWidget *header);
    gint                gtk_list_box_row_get_index          (GtkListBoxRow *row);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----GtkWidget
                   +----GtkContainer
                         +----GtkListBox

      GObject
       +----GInitiallyUnowned
             +----GtkWidget
                   +----GtkContainer
                         +----GtkBin
                               +----GtkListBoxRow

## Implemented Interfaces

GtkListBox implements AtkImplementorIface and GtkBuildable.

GtkListBoxRow implements AtkImplementorIface and GtkBuildable.

## Properties

      "activate-on-single-click" gboolean              : Read / Write
      "selection-mode"           GtkSelectionMode      : Read / Write

## Signals

      "activate-cursor-row"                            : Action
      "move-cursor"                                    : Action
      "row-activated"                                  : Run Last
      "row-selected"                                   : Run Last
      "toggle-cursor-row"                              : Action

## Description

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 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 `gtk_container_add()`, and a GtkListBoxRow widget will automatically be inserted between the list and the widget.

The GtkListBox widget was added in GTK+ 3.10.

## Details

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

`row` : | the row that may be filtered
`user_data` : | user data. [closure]
Returns : | `TRUE` if the row should be visible, `FALSE` otherwise

Since 3.10

### GtkListBoxSortFunc ()

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

Compare two rows to determin which should be first.

`row1` : | the first row
`row2` : | the second row
`user_data` : | user data. [closure]
Returns : | < 0 if `row1` should be before `row2`, 0 if they are equal and > 0 otherwise

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.

`row` : | the row to update
`before` : | the row before `row`, or `NULL` if it is first
`user_data` : | user data. [closure]

Since 3.10

### gtk_list_box_new ()

    GtkWidget *         gtk_list_box_new                    (void);

Creates a new GtkListBox container.

Returns : | a new GtkListBox

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()`.

`list_box` : | a GtkListBox.
`child` : | the GtkWidget to 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.

`list_box` : | a GtkListBox.
`child` : | the GtkWidget to add
`position` : | the position to insert `child` in

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.

`list_box` : | a GtkListBox
`row` : | The row to select or `NULL`. [allow-none]

Since 3.10

### gtk_list_box_get_selected_row ()

    GtkListBoxRow *     gtk_list_box_get_selected_row       (GtkListBox *list_box);

Gets the selected row.

`list_box` : | a GtkListBox
Returns : | the selected GtkWidget. [transfer none]

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

`list_box` : | a GtkListBox
`mode` : | The GtkSelectionMode

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.

`list_box` : | a GtkListBox
Returns : | a GtkSelectionMode

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.

`list_box` : | a GtkListBox
`single` : | a boolean

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.

`list_box` : | a GtkListBox
Returns : | `TRUE` if rows are activated on single click, `FALSE` otherwise

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.

`list_box` : | a GtkListBox
Returns : | the adjustment. [transfer none]

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.

`list_box` : | a GtkListBox
`adjustment` : | the adjustment, or `NULL`. [allow-none]

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.

`list_box` : | a GtkListBox
`placeholder` : | a GtkWidget or `NULL`. [allow-none]

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

`list_box` : | a GtkListBox
`index_` : | the index of the row
Returns : | the child GtkWidget. [transfer none]

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.

`list_box` : | a GtkListBox
`y` : | position
Returns : | the row. [transfer none]

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.

`list_box` : | a GtkListBox

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.

`list_box` : | a GtkListBox

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.

`list_box` : | a GtkListBox

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.

`list_box` : | a GtkListBox
`filter_func` : | callback that lets you filter which rows to show. [closure user_data][allow-none]
`user_data` : | user data passed to `filter_func`
`destroy` : | destroy notifier for `user_data`

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.

`list_box` : | a GtkListBox
`update_header` : | callback that lets you add row headers. [closure user_data][allow-none]
`user_data` : | user data passed to `update_header`
`destroy` : | destroy notifier for `user_data`

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.

`list_box` : | a GtkListBox
`sort_func` : | the sort function. [closure user_data][allow-none]
`user_data` : | user data passed to `sort_func`
`destroy` : | destroy notifier for `user_data`

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.

`list_box` : | An GtkListBox.
`row` : | a GtkListBoxRow

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.

`list_box` : | An GtkListBox.

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.

Returns : | a new GtkListBoxRow

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.

`row` : | a GtkListBoxRow

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.

`row` : | a GtkListBoxRow
Returns : | the current header, or `NULL` if none. [transfer none]

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.

`row` : | a GtkListBoxRow
`header` : | the header, or `NULL`. [allow-none]

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.

`row` : | a GtkListBoxRow
Returns : | the index of the `row`, or -1 if the `row` is not in a listbox

Since 3.10

## Property Details

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

## Signal Details

### The `"activate-cursor-row"` signal

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

`listbox` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.

### The `"move-cursor"` signal

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

`listbox` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.

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

`list_box` : | the GtkListBox
`row` : | the activated row
`user_data` : | user data set when the signal handler was connected.

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.

`list_box` : | the GtkListBox
`row` : | the selected row
`user_data` : | user data set when the signal handler was connected.

Since 3.10

### The `"toggle-cursor-row"` signal

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

`listbox` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.

## See Also

GtkScrolledWindow