GtkFlowBox

CSS nodes

flowbox
├── flowboxchild
│   ╰── <child>
├── flowboxchild
│   ╰── <child>
┊
╰── [rubberband]

GtkFlowBox uses a single CSS node with name flowbox. GtkFlowBoxChild uses a single CSS node with name flowboxchild. For rubberband selection, a subnode with name rubberband is used.

gtk_flow_box_new ()

GtkWidget *
gtk_flow_box_new (void);

Creates a GtkFlowBox.

Since: 3.12

gtk_flow_box_insert ()

void
gtk_flow_box_insert (GtkFlowBox *box,
                     GtkWidget *widget,
                     gint position);

Inserts the widget into 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 as gtk_container_add().

If position is -1, or larger than the total number of children in the box , then the widget will be appended to the end.

Since: 3.12

gtk_flow_box_get_child_at_index ()

GtkFlowBoxChild *
gtk_flow_box_get_child_at_index (GtkFlowBox *box,
                                 gint idx);

Gets the nth child in the box .

Since: 3.12

gtk_flow_box_get_child_at_pos ()

GtkFlowBoxChild *
gtk_flow_box_get_child_at_pos (GtkFlowBox *box,
                               gint x,
                               gint y);

Gets the child in the (x , y ) position.

Since: 3.22.6

gtk_flow_box_set_hadjustment ()

void
gtk_flow_box_set_hadjustment (GtkFlowBox *box,
                              GtkAdjustment *adjustment);

Hooks up an adjustment to focus handling in box . The adjustment is also used for autoscrolling during rubberband selection. See gtk_scrolled_window_get_hadjustment() for a typical way of obtaining the adjustment, and gtk_flow_box_set_vadjustment()for setting the vertical adjustment.

The adjustments have to be in pixel units and in the same coordinate system as the allocation for immediate children of the box.

Since: 3.12

gtk_flow_box_set_vadjustment ()

void
gtk_flow_box_set_vadjustment (GtkFlowBox *box,
                              GtkAdjustment *adjustment);

Hooks up an adjustment to focus handling in box . The adjustment is also used for autoscrolling during rubberband selection. See gtk_scrolled_window_get_vadjustment() for a typical way of obtaining the adjustment, and gtk_flow_box_set_hadjustment()for setting the horizontal adjustment.

The adjustments have to be in pixel units and in the same coordinate system as the allocation for immediate children of the box.

Since: 3.12

gtk_flow_box_set_homogeneous ()

void
gtk_flow_box_set_homogeneous (GtkFlowBox *box,
                              gboolean homogeneous);

Sets the “homogeneous” property of box , controlling whether or not all children of box are given equal space in the box.

Since: 3.12

gtk_flow_box_get_homogeneous ()

gboolean
gtk_flow_box_get_homogeneous (GtkFlowBox *box);

Returns whether the box is homogeneous (all children are the same size). See gtk_box_set_homogeneous().

Since: 3.12

gtk_flow_box_set_row_spacing ()

void
gtk_flow_box_set_row_spacing (GtkFlowBox *box,
                              guint spacing);

Sets the vertical space to add between children. See the “row-spacing” property.

Since: 3.12

gtk_flow_box_get_row_spacing ()

guint
gtk_flow_box_get_row_spacing (GtkFlowBox *box);

Gets the vertical spacing.

Since: 3.12

gtk_flow_box_set_column_spacing ()

void
gtk_flow_box_set_column_spacing (GtkFlowBox *box,
                                 guint spacing);

Sets the horizontal space to add between children. See the “column-spacing” property.

Since: 3.12

gtk_flow_box_get_column_spacing ()

guint
gtk_flow_box_get_column_spacing (GtkFlowBox *box);

Gets the horizontal spacing.

Since: 3.12

gtk_flow_box_set_min_children_per_line ()

void
gtk_flow_box_set_min_children_per_line
                               (GtkFlowBox *box,
                                guint n_children);

Sets the minimum number of children to line up in box ’s orientation before flowing.

Since: 3.12

gtk_flow_box_get_min_children_per_line ()

guint
gtk_flow_box_get_min_children_per_line
                               (GtkFlowBox *box);

Gets the minimum number of children per line.

Since: 3.12

gtk_flow_box_set_max_children_per_line ()

void
gtk_flow_box_set_max_children_per_line
                               (GtkFlowBox *box,
                                guint n_children);

Sets the maximum number of children to request and allocate space for in box ’s orientation.

Setting the maximum number of children per line limits the overall natural size request to be no more than n_children children long in the given orientation.

Since: 3.12

gtk_flow_box_get_max_children_per_line ()

guint
gtk_flow_box_get_max_children_per_line
                               (GtkFlowBox *box);

Gets the maximum number of children per line.

Since: 3.12

gtk_flow_box_set_activate_on_single_click ()

void
gtk_flow_box_set_activate_on_single_click
                               (GtkFlowBox *box,
                                gboolean single);

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

Since: 3.12

gtk_flow_box_get_activate_on_single_click ()

gboolean
gtk_flow_box_get_activate_on_single_click
                               (GtkFlowBox *box);

Returns whether children activate on single clicks.

Since: 3.12

GtkFlowBoxForeachFunc ()

void
(*GtkFlowBoxForeachFunc) (GtkFlowBox *box,
                          GtkFlowBoxChild *child,
                          gpointer user_data);

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

Since: 3.12

gtk_flow_box_selected_foreach ()

void
gtk_flow_box_selected_foreach (GtkFlowBox *box,
                               GtkFlowBoxForeachFunc func,
                               gpointer data);

Calls a function for each selected child.

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

Since: 3.12

gtk_flow_box_get_selected_children ()

GList *
gtk_flow_box_get_selected_children (GtkFlowBox *box);

Creates a list of all selected children.

Since: 3.12

gtk_flow_box_select_child ()

void
gtk_flow_box_select_child (GtkFlowBox *box,
                           GtkFlowBoxChild *child);

Selects a single child of box , if the selection mode allows it.

Since: 3.12

gtk_flow_box_unselect_child ()

void
gtk_flow_box_unselect_child (GtkFlowBox *box,
                             GtkFlowBoxChild *child);

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

Since: 3.12

gtk_flow_box_select_all ()

void
gtk_flow_box_select_all (GtkFlowBox *box);

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

Since: 3.12

gtk_flow_box_unselect_all ()

void
gtk_flow_box_unselect_all (GtkFlowBox *box);

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

Since: 3.12

gtk_flow_box_set_selection_mode ()

void
gtk_flow_box_set_selection_mode (GtkFlowBox *box,
                                 GtkSelectionMode mode);

Sets how selection works in box . See GtkSelectionMode for details.

Since: 3.12

gtk_flow_box_get_selection_mode ()

GtkSelectionMode
gtk_flow_box_get_selection_mode (GtkFlowBox *box);

Gets the selection mode of box .

Since: 3.12

GtkFlowBoxFilterFunc ()

gboolean
(*GtkFlowBoxFilterFunc) (GtkFlowBoxChild *child,
                         gpointer user_data);

A function that will be called whenrever a child changes or is added. It lets you control if the child should be visible or not.

Since: 3.12

gtk_flow_box_set_filter_func ()

void
gtk_flow_box_set_filter_func (GtkFlowBox *box,
                              GtkFlowBoxFilterFunc filter_func,
                              gpointer user_data,
                              GDestroyNotify destroy);

By setting a filter function on the box one can decide dynamically which of the children to show. For instance, to implement a search function that only shows the children matching the search terms.

The filter_func will be called for each child after the call, and it will continue to be called each time a child changes (via gtk_flow_box_child_changed()) or when gtk_flow_box_invalidate_filter() is called.

Note that using a filter function is incompatible with using a model (see gtk_flow_box_bind_model()).

Since: 3.12

gtk_flow_box_invalidate_filter ()

void
gtk_flow_box_invalidate_filter (GtkFlowBox *box);

Updates the filtering for all children.

Call this function when the result of the filter function on the box is changed due ot an external factor. For instance, this would be used if the filter function just looked for a specific search term, and the entry with the string has changed.

Since: 3.12

GtkFlowBoxSortFunc ()

gint
(*GtkFlowBoxSortFunc) (GtkFlowBoxChild *child1,
                       GtkFlowBoxChild *child2,
                       gpointer user_data);

A function to compare two children to determine which should come first.

Since: 3.12

gtk_flow_box_set_sort_func ()

void
gtk_flow_box_set_sort_func (GtkFlowBox *box,
                            GtkFlowBoxSortFunc sort_func,
                            gpointer user_data,
                            GDestroyNotify destroy);

By setting a sort function on the box , one can dynamically reorder the children of the box, based on the contents of the children.

The sort_func will be called for each child after the call, and will continue to be called each time a child changes (via gtk_flow_box_child_changed()) and when gtk_flow_box_invalidate_sort() is called.

Note that using a sort function is incompatible with using a model (see gtk_flow_box_bind_model()).

Since: 3.12

gtk_flow_box_invalidate_sort ()

void
gtk_flow_box_invalidate_sort (GtkFlowBox *box);

Updates the sorting for all children.

Call this when the result of the sort function on box is changed due to an external factor.

Since: 3.12

GtkFlowBoxCreateWidgetFunc ()

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

Called for flow boxes that are bound to a GListModel with gtk_flow_box_bind_model() for each item that gets added to the model.

Since: 3.18

gtk_flow_box_bind_model ()

void
gtk_flow_box_bind_model (GtkFlowBox *box,
                         GListModel *model,
                         GtkFlowBoxCreateWidgetFunc 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_flow_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 GtkFlowBox. When using a model, filtering and sorting should be implemented by the model.

Since: 3.18

gtk_flow_box_child_new ()

GtkWidget *
gtk_flow_box_child_new (void);

Creates a new GtkFlowBoxChild, to be used as a child of a GtkFlowBox.

Since: 3.12

gtk_flow_box_child_get_index ()

gint
gtk_flow_box_child_get_index (GtkFlowBoxChild *child);

Gets the current index of the child in its GtkFlowBox container.

Since: 3.12

gtk_flow_box_child_is_selected ()

gboolean
gtk_flow_box_child_is_selected (GtkFlowBoxChild *child);

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

Since: 3.12

gtk_flow_box_child_changed ()

void
gtk_flow_box_child_changed (GtkFlowBoxChild *child);

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

Note that calls to this method must be in sync with the data used for the sorting and filtering functions. For instance, if the list is mirroring some external data set, and *two* children changed in the external data set when you call gtk_flow_box_child_changed() on the first child, the sort function must only read the new data for the first of the two changed children, otherwise the resorting of the children 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 sorting and filtering functions into the widgets themselves. Another alternative is to call gtk_flow_box_invalidate_sort() on any model change, but that is more expensive.

Since: 3.12

struct GtkFlowBox

struct GtkFlowBox;

struct GtkFlowBoxChild

struct GtkFlowBoxChild;

The “activate-on-single-click” property

  “activate-on-single-click” gboolean

Determines whether children can be activated with a single click, or require a double-click.

Owner: GtkFlowBox

Flags: Read / Write

Default value: TRUE

The “column-spacing” property

  “column-spacing”           guint

The amount of horizontal space between two children.

Owner: GtkFlowBox

Flags: Read / Write

Default value: 0

The “homogeneous” property

  “homogeneous”              gboolean

Determines whether all children should be allocated the same size.

Owner: GtkFlowBox

Flags: Read / Write

Default value: FALSE

The “max-children-per-line” property

  “max-children-per-line”    guint

The maximum amount of children to request space for consecutively in the given orientation.

Owner: GtkFlowBox

Flags: Read / Write

Allowed values: >= 1

Default value: 7

The “min-children-per-line” property

  “min-children-per-line”    guint

The minimum number of children to allocate consecutively in the given orientation.

Setting the minimum children per line ensures that a reasonably small height will be requested for the overall minimum width of the box.

Owner: GtkFlowBox

Flags: Read / Write

Default value: 0

The “row-spacing” property

  “row-spacing”              guint

The amount of vertical space between two children.

Owner: GtkFlowBox

Flags: Read / Write

Default value: 0

The “selection-mode” property

  “selection-mode”           GtkSelectionMode

The selection mode used by the flow box.

Owner: GtkFlowBox

Flags: Read / Write

Default value: GTK_SELECTION_SINGLE

The “activate-cursor-child” signal

void
user_function (GtkFlowBox *box,
               gpointer    user_data)

The ::activate-cursor-child signal is a keybinding signal which gets emitted when the user activates the box .

Flags: Action

The “child-activated” signal

void
user_function (GtkFlowBox      *box,
               GtkFlowBoxChild *child,
               gpointer         user_data)

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

Flags: Run Last

The “move-cursor” signal

gboolean
user_function (GtkFlowBox     *box,
               GtkMovementStep step,
               int             count,
               gpointer        user_data)

The ::move-cursor signal is a keybinding signal which gets emitted when the user initiates a cursor movement.

Applications should not connect to it, but may emit it with g_signal_emit_by_name() if they need to control the cursor programmatically.

The default bindings for this signal come in two variants, the variant with the Shift modifier extends the selection, the variant without the Shift modifer does not. There are too many key combinations to list them all here.

Flags: Action

The “select-all” signal

void
user_function (GtkFlowBox *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

The “selected-children-changed” signal

void
user_function (GtkFlowBox *box,
               gpointer    user_data)

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

Use gtk_flow_box_selected_foreach() or gtk_flow_box_get_selected_children() to obtain the selected children.

Flags: Run First

The “toggle-cursor-child” signal

void
user_function (GtkFlowBox *box,
               gpointer    user_data)

The ::toggle-cursor-child signal is a keybinding signal which toggles the selection of the child that has the focus.

The default binding for this signal is Ctrl-Space.

Flags: Action

The “unselect-all” signal

void
user_function (GtkFlowBox *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

The “activate” signal

void
user_function (GtkFlowBoxChild *child,
               gpointer         user_data)

The ::activate signal is emitted when the user activates a child widget in a GtkFlowBox, either by clicking or double-clicking, or by using the Space or Enter key.

While this signal is used as a keybinding signal, it can be used by applications for their own purposes.

Flags: Action