## GtkFlowBox

GtkFlowBox — A container that allows reflowing its children

## Functions

GtkWidget * | gtk_flow_box_new ()
void | gtk_flow_box_insert ()
GtkFlowBoxChild * | gtk_flow_box_get_child_at_index ()
void | gtk_flow_box_set_hadjustment ()
void | gtk_flow_box_set_vadjustment ()
void | gtk_flow_box_set_homogeneous ()
gboolean | gtk_flow_box_get_homogeneous ()
void | gtk_flow_box_set_row_spacing ()
guint | gtk_flow_box_get_row_spacing ()
void | gtk_flow_box_set_column_spacing ()
guint | gtk_flow_box_get_column_spacing ()
void | gtk_flow_box_set_min_children_per_line ()
guint | gtk_flow_box_get_min_children_per_line ()
void | gtk_flow_box_set_max_children_per_line ()
guint | gtk_flow_box_get_max_children_per_line ()
void | gtk_flow_box_set_activate_on_single_click ()
gboolean | gtk_flow_box_get_activate_on_single_click ()
void | (*GtkFlowBoxForeachFunc) ()
void | gtk_flow_box_selected_foreach ()
GList * | gtk_flow_box_get_selected_children ()
void | gtk_flow_box_select_child ()
void | gtk_flow_box_unselect_child ()
void | gtk_flow_box_select_all ()
void | gtk_flow_box_unselect_all ()
void | gtk_flow_box_set_selection_mode ()
GtkSelectionMode | gtk_flow_box_get_selection_mode ()
gboolean | (*GtkFlowBoxFilterFunc) ()
void | gtk_flow_box_set_filter_func ()
void | gtk_flow_box_invalidate_filter ()
gint | (*GtkFlowBoxSortFunc) ()
void | gtk_flow_box_set_sort_func ()
void | gtk_flow_box_invalidate_sort ()
GtkWidget * | gtk_flow_box_child_new ()
gint | gtk_flow_box_child_get_index ()
gboolean | gtk_flow_box_child_is_selected ()
void | gtk_flow_box_child_changed ()

## Properties

gboolean | activate-on-single-click | Read / Write
guint | column-spacing | Read / Write
gboolean | homogeneous | Read / Write
guint | max-children-per-line | Read / Write
guint | min-children-per-line | Read / Write
guint | row-spacing | Read / Write
GtkSelectionMode | selection-mode | Read / Write

## Signals

void | activate-cursor-child | Action
void | child-activated | Run Last
void | move-cursor | Action
void | select-all | Action
void | selected-children-changed | Run First
void | toggle-cursor-child | Action
void | unselect-all | Action
void | activate | Action

## Types and Values

struct | GtkFlowBox
struct | GtkFlowBoxChild

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── GtkWidget
                ╰── GtkContainer
                    ├── GtkBin
                    │   ╰── GtkFlowBoxChild
                    ╰── GtkFlowBox

## Implemented Interfaces

GtkFlowBox implements AtkImplementorIface, GtkBuildable and GtkOrientable.

GtkFlowBoxChild implements AtkImplementorIface and GtkBuildable.

## Includes

    #include <gtk/gtk.h>

## Description

A GtkFlowBox positions child widgets in sequence according to its orientation.

For instance, with the horizontal orientation, the widgets will be arranged from left to right, starting a new row under the previous row when necessary. Reducing the width in this case will require more rows, so a larger height will be requested.

Likewise, with the vertical orientation, the widgets will be arranged from top to bottom, starting a new column to the right when necessary. Reducing the height will require more columns, so a larger width will be requested.

The children of a GtkFlowBox can be dynamically sorted and filtered.

Although a GtkFlowBox must have only GtkFlowBoxChild children, you can add any kind of widget to it via `gtk_container_add()`, and a GtkFlowBoxChild widget will automatically be inserted between the box and the widget.

Also see GtkListBox.

GtkFlowBox was added in GTK+ 3.12.

## Functions

### gtk_flow_box_new ()

    GtkWidget *
    gtk_flow_box_new (void);

Creates a GtkFlowBox.

#### Returns

a new GtkFlowBox container

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.

#### Parameters

box | a GtkFlowBox |
widget | the GtkWidget to add |
position | the position to insert `child` in |

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

#### Parameters

box | a GtkFlowBox |
idx | the position of the child |

#### Returns

the child widget, which will always be a GtkFlowBoxChild.

[transfer none]

Since 3.12

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

#### Parameters

box | a GtkFlowBox |
adjustment | an adjustment which should be adjusted when the focus is moved among the descendents of `container` |

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.

#### Parameters

box | a GtkFlowBox |
adjustment | an adjustment which should be adjusted when the focus is moved among the descendents of `container` |

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.

#### Parameters

box | a GtkFlowBox |
homogeneous | `TRUE` to create equal allotments, `FALSE` for variable allotments |

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

#### Parameters

box | a GtkFlowBox |

#### Returns

`TRUE` if the box is 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.

#### Parameters

box | a GtkFlowBox |
spacing | the spacing to use |

Since 3.12

### gtk_flow_box_get_row_spacing ()

    guint
    gtk_flow_box_get_row_spacing (GtkFlowBox *box);

Gets the vertical spacing.

#### Parameters

box | a GtkFlowBox |

#### Returns

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.

#### Parameters

box | a GtkFlowBox |
spacing | the spacing to use |

Since 3.12

### gtk_flow_box_get_column_spacing ()

    guint
    gtk_flow_box_get_column_spacing (GtkFlowBox *box);

Gets the horizontal spacing.

#### Parameters

box | a GtkFlowBox |

#### Returns

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.

#### Parameters

box | a GtkFlowBox |
n_children | the minimum number of children per line |

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.

#### Parameters

box | a GtkFlowBox |

#### Returns

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.

#### Parameters

box | a GtkFlowBox |
n_children | the maximum number of children per line |

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.

#### Parameters

box | a GtkFlowBox |

#### Returns

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.

#### Parameters

box | a GtkFlowBox |
single | `TRUE` to emit child-activated on a single 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.

#### Parameters

box | a GtkFlowBox |

#### Returns

`TRUE` if children are activated on single click, `FALSE` otherwise

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

#### Parameters

box | a GtkFlowBox |
child | a GtkFlowBoxChild |
user_data | user data. | [closure]

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.

#### Parameters

box | a GtkFlowBox |
func | the function to call for each selected child. | [scope call]
data | user data to pass to the 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.

#### Parameters

box | a GtkFlowBox |

#### Returns

A GList containing the GtkWidget for each selected child. Free with `g_list_free()` when done.

[element-type GtkFlowBoxChild][transfer container]

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.

#### Parameters

box | a GtkFlowBox |
child | a child of `box` |

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.

#### Parameters

box | a GtkFlowBox |
child | a child of `box` |

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.

#### Parameters

box | a GtkFlowBox |

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.

#### Parameters

box | a GtkFlowBox |

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.

#### Parameters

box | a GtkFlowBox |
mode | the new selection mode |

Since 3.12

### gtk_flow_box_get_selection_mode ()

    GtkSelectionMode
    gtk_flow_box_get_selection_mode (GtkFlowBox *box);

Gets the selection mode of `box` .

#### Parameters

box | a GtkFlowBox |

#### Returns

the GtkSelectionMode

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.

#### Parameters

child | a GtkFlowBoxChild that may be filtered |
user_data | user data. | [closure]

#### Returns

`TRUE` if the row should be visible, `FALSE` otherwise

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.

#### Parameters

box | a GtkFlowBox |
filter_func | callback that lets you filter which children to show. | [closure user_data][allow-none]
user_data | user data passed to `filter_func` |
destroy | destroy notifier for `user_data` |

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.

#### Parameters

box | a GtkFlowBox |

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.

#### Parameters

child1 | the first child |
child2 | the second child |
user_data | user data. | [closure]

#### Returns

< 0 if `child1` should be before `child2` , 0 if the are equal, and > 0 otherwise

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.

#### Parameters

box | a GtkFlowBox |
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.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.

#### Parameters

box | a GtkFlowBox |

Since 3.12

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

#### Returns

a new GtkFlowBoxChild

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.

#### Parameters

child | a GtkFlowBoxChild |

#### Returns

the index of the `child` , or -1 if the `child` is not in a flow box.

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.

#### Parameters

child | a GtkFlowBoxChild |

#### Returns

`TRUE` if `child` is selected

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.

#### Parameters

child | a GtkFlowBoxChild |

Since 3.12

## Types and Values

### struct GtkFlowBox

    struct GtkFlowBox;

### struct GtkFlowBoxChild

    struct GtkFlowBoxChild;

## Property Details

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

Flags: Read / Write

Default value: TRUE

### The `“column-spacing”` property

      “column-spacing”           guint

The amount of horizontal space between two children.

Flags: Read / Write

Default value: 0

### The `“homogeneous”` property

      “homogeneous”              gboolean

Determines whether all children should be allocated the same size.

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.

Flags: Read / Write

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.

Flags: Read / Write

Default value: 0

### The `“row-spacing”` property

      “row-spacing”              guint

The amount of vertical space between two children.

Flags: Read / Write

Default value: 0

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

      “selection-mode”           GtkSelectionMode

The selection mode used by the flow box.

Flags: Read / Write

Default value: GTK_SELECTION_SINGLE

## Signal Details

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

#### Parameters

box | the GtkFlowBox on which the signal is emitted |
user_data | user data set when the signal handler was connected. |

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.

#### Parameters

box | the GtkFlowBox on which the signal is emitted |
child | the child that is activated |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“move-cursor”` signal

    void
    user_function (GtkFlowBox     *box,
                   GtkMovementStep step,
                   gint            count,
                   gpointer        user_data)

The ::move-cursor signal is a keybinding signal which gets emitted when the user initiates a cursor movement. If the cursor is not visible in `text_view` , this signal causes the viewport to be moved instead.

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.

- Arrow keys move by individual children

- Home/End keys move to the ends of the box

- PageUp/PageDown keys move vertically by pages

#### Parameters

box | the GtkFlowBox on which the signal is emitted |
step | the granularity fo the move, as a GtkMovementStep |
count | the number of `step` units to move |
user_data | user data set when the signal handler was connected. |

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.

#### Parameters

box | the GtkFlowBox on which the signal is emitted |
user_data | user data set when the signal handler was connected. |

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.

#### Parameters

box | the GtkFlowBox on wich the signal is emitted |
user_data | user data set when the signal handler was connected. |

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.

#### Parameters

box | the GtkFlowBox on which the signal is emitted |
user_data | user data set when the signal handler was connected. |

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.

#### Parameters

box | the GtkFlowBox on which the signal is emitted |
user_data | user data set when the signal handler was connected. |

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.

#### Parameters

child | The child on which the signal is emitted |
user_data | user data set when the signal handler was connected. |

Flags: Action