FlowBox
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
.
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
Methods
- class FlowBox
- append(child: Widget) None
Adds
child
to the end ofself
.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[[...], Widget], *user_data: Any) None
Binds
model
tobox
.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 frommodel
.box
is updated whenevermodel
changes. Ifmodel
isNone
,box
is left empty.It is undefined to add or remove widgets directly (for example, with
insert
) whilebox
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 tobox
create_widget_func – a function that creates widgets for items
user_data – user data passed to
create_widget_func
- 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
andy
are assumed to be relative to the origin ofbox
.- Parameters:
x – the x coordinate of the child
y – the y coordinate of the child
- 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
intobox
atposition
.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 thebox
, then thewidget
will be appended to the end.- Parameters:
widget – the
GtkWidget
to addposition – 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 ofself
.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_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[[...], None], *data: Any) 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
isTrue
, 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[[...], bool] | None = None, *user_data: Any) 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 (viachanged
) or wheninvalidate_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, andset_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[[...], int] | None = None, *user_data: Any) 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 (viachanged
) and wheninvalidate_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, andset_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_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.activate_on_single_click: bool
Determines whether children can be activated with a single click, or require a double-click.
- props.max_children_per_line: int
The maximum amount of children to request space for consecutively in the given orientation.
- props.min_children_per_line: int
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.
- props.selection_mode: SelectionMode
The selection mode used by the flow box.
Signals
- class FlowBox.signals
- activate_cursor_child() None
Emitted when the user activates the
box
.This is a keybinding signal.
- child_activated(child: FlowBoxChild) None
Emitted when a child has been activated by the user.
- Parameters:
child – the child that is activated
- move_cursor(step: MovementStep, count: int, extend: bool, modify: bool) bool
Emitted when the user initiates a cursor movement.
This is a keybinding signal. Applications should not connect to it, but may emit it with
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 modifier does not. There are too many key combinations to list them all here.
←, →, ↑, ↓ move by individual children
Home, End move to the ends of the box
PgUp, PgDn move vertically by pages
- Parameters:
step – the granularity of the move, as a
GtkMovementStep
count – the number of
step
units to moveextend – whether to extend the selection
modify – whether to modify the selection
- select_all() None
Emitted to select all children of the box, if the selection mode permits it.
This is a keybinding signal.
The default bindings for this signal is Ctrl-a.
- selected_children_changed() None
Emitted when the set of selected children changes.
Use
selected_foreach
orget_selected_children
to obtain the selected children.
- toggle_cursor_child() None
Emitted to toggle the selection of the child that has the focus.
This is a keybinding signal.
The default binding for this signal is Ctrl-Space.
- unselect_all() None
Emitted to unselect all children of the box, if the selection mode permits it.
This is a keybinding signal.
The default bindings for this signal is Ctrl-Shift-a.