## GtkListBox

GtkListBox — A list container

## Functions

gboolean | (*GtkListBoxFilterFunc) ()
gint | (*GtkListBoxSortFunc) ()
void | (*GtkListBoxUpdateHeaderFunc) ()
GtkWidget * | gtk_list_box_new ()
void | gtk_list_box_prepend ()
void | gtk_list_box_insert ()
void | gtk_list_box_select_row ()
GtkListBoxRow * | gtk_list_box_get_selected_row ()
void | gtk_list_box_set_selection_mode ()
GtkSelectionMode | gtk_list_box_get_selection_mode ()
void | gtk_list_box_set_activate_on_single_click ()
gboolean | gtk_list_box_get_activate_on_single_click ()
GtkAdjustment * | gtk_list_box_get_adjustment ()
void | gtk_list_box_set_adjustment ()
void | gtk_list_box_set_placeholder ()
GtkListBoxRow * | gtk_list_box_get_row_at_index ()
GtkListBoxRow * | gtk_list_box_get_row_at_y ()
void | gtk_list_box_invalidate_filter ()
void | gtk_list_box_invalidate_headers ()
void | gtk_list_box_invalidate_sort ()
void | gtk_list_box_set_filter_func ()
void | gtk_list_box_set_header_func ()
void | gtk_list_box_set_sort_func ()
void | gtk_list_box_drag_highlight_row ()
void | gtk_list_box_drag_unhighlight_row ()
GtkWidget * | gtk_list_box_row_new ()
void | gtk_list_box_row_changed ()
GtkWidget * | gtk_list_box_row_get_header ()
GType | gtk_list_box_row_get_type ()
void | gtk_list_box_row_set_header ()
gint | gtk_list_box_row_get_index ()

## Properties

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

## Signals

void | activate-cursor-row | Action
void | move-cursor | Action
void | row-activated | Run Last
void | row-selected | Run Last
void | toggle-cursor-row | Action
void | activate | Action

## Types and Values

struct | GtkListBox
struct | GtkListBoxRow

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── GtkWidget
                ╰── GtkContainer
                    ├── GtkBin
                    │   ╰── GtkListBoxRow
                    ╰── GtkListBox

## Implemented Interfaces

GtkListBox implements AtkImplementorIface and GtkBuildable.

GtkListBoxRow implements AtkImplementorIface and GtkBuildable.

## Includes

    #include <gtk/gtk.h>

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

## Functions

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

#### Parameters

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 determine which should be first.

#### Parameters

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.

#### Parameters

row | the row to update |
before | the row before `row` , or `NULL` if it is first. | [allow-none]
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()`.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

row | a GtkListBoxRow |

#### Returns

the index of the `row` , or -1 if the `row` is not in a listbox

Since 3.10

## Types and Values

### struct GtkListBox

    struct GtkListBox;

### struct GtkListBoxRow

    struct GtkListBoxRow;

## Property Details

### The `“activate-on-single-click”` property

      “activate-on-single-click” gboolean

Activate row on a single click.

Flags: Read / Write

Default value: TRUE

### The `“selection-mode”` property

      “selection-mode”           GtkSelectionMode

The selection mode.

Flags: Read / Write

Default value: GTK_SELECTION_SINGLE

## Signal Details

### 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,
                   gint            arg2,
                   gpointer        user_data)

Flags: Action

### The `“row-activated”` signal

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

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

#### Parameters

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

Flags: Run Last

Since 3.10

### The `“row-selected”` signal

    void
    user_function (GtkListBox    *list_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.

#### Parameters

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

Flags: Run Last

Since 3.10

### The `“toggle-cursor-row”` signal

    void
    user_function (GtkListBox *listbox,
                   gpointer    user_data)

Flags: Action

### The `“activate”` signal

    void
    user_function (GtkListBoxRow *listboxrow,
                   gpointer       user_data)

Flags: Action

## See Also

GtkScrolledWindow