FlowBox

class FlowBox(**properties: Any)

Superclasses: Widget, InitiallyUnowned, Object

Implemented Interfaces: Accessible, Buildable, ConstraintTarget, Orientable

A GtkFlowBox puts child widgets in reflowing grid.

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 size request of a GtkFlowBox alone may not be what you expect; if you need to be able to shrink it along both axes and dynamically reflow its children, you may have to wrap it in a GtkScrolledWindow to enable that.

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 insert, and a GtkFlowBoxChild widget will automatically be inserted between the box and the widget.

Also see ListBox.

Shortcuts and Gestures

The following signals have default keybindings:

• move_cursor

• select_all

• toggle_cursor_child

• unselect_all

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.

Accessibility

GtkFlowBox uses the GRID role, and GtkFlowBoxChild uses the GRID_CELL role.

Constructors

class FlowBox

classmethod new() → Widget

Creates a GtkFlowBox.

Methods

class FlowBox

append(child: Widget) → None

Adds child to the end of self.

If a sort function is set, the widget will actually be inserted at the calculated position.

See also: insert.

Added in version 4.6.

Parameters:

child – the GtkWidget to add

bind_model(model: ListModel | None, create_widget_func: Callable[[Object, Any], Widget], user_data: Any = None) → None

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 None, box is left empty.

It is undefined to add or remove widgets directly (for example, with insert) 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.

Parameters:

• model – the GListModel to be bound to box

• create_widget_func – a function that creates widgets for items

• user_data – user data passed to create_widget_func

get_activate_on_single_click() → bool

Returns whether children activate on single clicks.

get_child_at_index(idx: int) → FlowBoxChild | None

Gets the nth child in the box.

Parameters:

idx – the position of the child

get_child_at_pos(x: int, y: int) → FlowBoxChild | None

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

Both x and y are assumed to be relative to the origin of box.

Parameters:

• x – the x coordinate of the child

• y – the y coordinate of the child

get_column_spacing() → int

Gets the horizontal spacing.

get_homogeneous() → bool

Returns whether the box is homogeneous.

get_max_children_per_line() → int

Gets the maximum number of children per line.

get_min_children_per_line() → int

Gets the minimum number of children per line.

get_row_spacing() → int

Gets the vertical spacing.

get_selected_children() → list[FlowBoxChild]

Creates a list of all selected children.

get_selection_mode() → SelectionMode

Gets the selection mode of box.

insert(widget: Widget, position: int) → None

Inserts the widget into box at position.

If a sort function is set, the widget will actually be inserted at the calculated position.

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:

• widget – the GtkWidget to add

• position – the position to insert child in

invalidate_filter() → None

Updates the filtering for all children.

Call this function when the 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 term, and the entry with the string has changed.

invalidate_sort() → None

Updates the sorting for all children.

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

prepend(child: Widget) → None

Adds child to the start of self.

If a sort function is set, the widget will actually be inserted at the calculated position.

See also: insert.

Added in version 4.6.

Parameters:

child – the GtkWidget to add

remove(widget: Widget) → None

Removes a child from box.

Parameters:

widget – the child widget to remove

remove_all() → None

Removes all children from box.

This function does nothing if box is backed by a model.

Added in version 4.12.

select_all() → None

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

select_child(child: FlowBoxChild) → None

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

Parameters:

child – a child of box

selected_foreach(func: Callable[[FlowBox, FlowBoxChild, Any], None], data: Any = None) → None

Calls a function for each selected child.

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

Parameters:

• func – the function to call for each selected child

• data – user data to pass to the function

set_activate_on_single_click(single: bool) → None

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

Parameters:

single – True to emit child-activated on a single click

set_column_spacing(spacing: int) → None

Sets the horizontal space to add between children.

Parameters:

spacing – the spacing to use

set_filter_func(filter_func: Callable[[FlowBoxChild, Any], bool] | None = None, user_data: Any = None) → None

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 changed) or when invalidate_filter is called.

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

Parameters:

• filter_func – callback that lets you filter which children to show

• user_data – user data passed to filter_func

set_hadjustment(adjustment: Adjustment) → None

Hooks up an adjustment to focus handling in box.

The adjustment is also used for autoscrolling during rubberband selection. See get_hadjustment for a typical way of obtaining the adjustment, and 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:

adjustment – an adjustment which should be adjusted when the focus is moved among the descendents of container

set_homogeneous(homogeneous: bool) → None

Sets whether or not all children of box are given equal space in the box.

Parameters:

homogeneous – True to create equal allotments, False for variable allotments

set_max_children_per_line(n_children: int) → None

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:

n_children – the maximum number of children per line

set_min_children_per_line(n_children: int) → None

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

Parameters:

n_children – the minimum number of children per line

set_row_spacing(spacing: int) → None

Sets the vertical space to add between children.

Parameters:

spacing – the spacing to use

set_selection_mode(mode: SelectionMode) → None

Sets how selection works in box.

Parameters:

mode – the new selection mode

set_sort_func(sort_func: Callable[[FlowBoxChild, FlowBoxChild, Any], int] | None = None, user_data: Any = None) → None

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 changed) and when invalidate_sort is called.

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

Parameters:

• sort_func – the sort function

• user_data – user data passed to sort_func

set_vadjustment(adjustment: Adjustment) → None

Hooks up an adjustment to focus handling in box.

The adjustment is also used for autoscrolling during rubberband selection. See get_vadjustment for a typical way of obtaining the adjustment, and 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:

adjustment – an adjustment which should be adjusted when the focus is moved among the descendents of container

unselect_all() → None

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

unselect_child(child: FlowBoxChild) → None

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

Parameters:

child – a child of box

Properties

class FlowBox

props.accept_unpaired_release: bool

The type of the None singleton.

props.activate_on_single_click: bool

The type of the None singleton.

props.column_spacing: int

The type of the None singleton.

props.homogeneous: bool

The type of the None singleton.

props.max_children_per_line: int

The type of the None singleton.

props.min_children_per_line: int

The type of the None singleton.

props.row_spacing: int

The type of the None singleton.

props.selection_mode: SelectionMode

The type of the None singleton.

Signals

class FlowBox.signals

activate_cursor_child() → None

The type of the None singleton.

child_activated(child: FlowBoxChild) → None

The type of the None singleton.

Parameters:

child – the child that is activated

move_cursor(step: MovementStep, count: int, extend: bool, modify: bool) → bool

The type of the None singleton.

Parameters:

• step – the granularity of the move, as a GtkMovementStep

• count – the number of step units to move

• extend – whether to extend the selection

• modify – whether to modify the selection

select_all() → None

The type of the None singleton.

selected_children_changed() → None

The type of the None singleton.

toggle_cursor_child() → None

The type of the None singleton.

unselect_all() → None

The type of the None singleton.