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.
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.
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.
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.
Returns
the selected row.
[transfer none]
Since: 3.10
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.
Returns
A GList containing the GtkWidget for each selected child.
Free with g_list_free() when done.
[element-type GtkListBoxRow][transfer container]
Since: 3.14
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.
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 *box);
Gets the adjustment (if any) that the widget uses to
for vertical scrolling.
Returns
the adjustment.
[transfer none]
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.
Returns
the row or NULL
in case no row exists for the given y coordinate.
[transfer none][nullable]
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_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_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
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.
Returns
a GtkWidget that represents item
.
[transfer full]
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_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.
Returns
TRUE if row
is selected
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.
Returns
the current header, or NULL if none.
[transfer none][nullable]
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.
Returns
the index of the row
, or -1 if the row
is not in a listbox
Since: 3.10
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.
Returns
TRUE if the row is selectable
Since: 3.14
Signal Details
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 “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