:right-sidebar: True

FlowBox
===================================================================

.. currentmodule:: gi.repository.Gtk





.. class:: FlowBox(**properties: ~typing.Any)
   :no-contents-entry:


Superclasses: :class:`~gi.repository.Gtk.Widget`, :class:`~gi.repository.GObject.InitiallyUnowned`, :class:`~gi.repository.GObject.Object`



Implemented Interfaces: :class:`~gi.repository.Gtk.Accessible`, :class:`~gi.repository.Gtk.Buildable`, :class:`~gi.repository.Gtk.ConstraintTarget`, :class:`~gi.repository.Gtk.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 :obj:`~gi.repository.Gtk.FlowBox.insert`, and a
``GtkFlowBoxChild`` widget will automatically be inserted between the box
and the widget.

Also see :obj:`~gi.repository.Gtk.ListBox`.

CSS nodes
---------


.. code-block::
   :dedent:

   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 :const:`~gi.repository.Gtk.AccessibleRole.GRID` role, and ``GtkFlowBoxChild``
uses the :const:`~gi.repository.Gtk.AccessibleRole.GRID_CELL` role.



Constructors
------------

.. rst-class:: interim-class

.. class:: FlowBox
   :no-index:


   .. classmethod:: new() -> ~gi.repository.Gtk.Widget

      Creates a ``GtkFlowBox``.














Methods
-------

.. rst-class:: interim-class

.. class:: FlowBox
   :no-index:


   .. method:: append(child: ~gi.repository.Gtk.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: :obj:`~gi.repository.Gtk.FlowBox.insert`.



      .. versionadded:: 4.6





      :param child: the ``GtkWidget`` to add





   .. method:: bind_model(model: ~gi.repository.Gio.ListModel | None, create_widget_func: ~typing.Callable[[...], ~gi.repository.Gtk.Widget], *user_data: ~typing.Any) -> 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 :const:`None`, ``box`` is left empty.

      It is undefined to add or remove widgets directly (for example, with
      :obj:`~gi.repository.Gtk.FlowBox.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.







      :param model: the ``GListModel`` to be bound to ``box``


      :param create_widget_func: a function that creates widgets for items


      :param user_data: user data passed to ``create_widget_func``





   .. method:: get_activate_on_single_click() -> bool

      Returns whether children activate on single clicks.










   .. method:: get_child_at_index(idx: int) -> ~gi.repository.Gtk.FlowBoxChild | None

      Gets the nth child in the ``box``.







      :param idx: the position of the child





   .. method:: get_child_at_pos(x: int, y: int) -> ~gi.repository.Gtk.FlowBoxChild | None

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

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







      :param x: the x coordinate of the child


      :param y: the y coordinate of the child





   .. method:: get_column_spacing() -> int

      Gets the horizontal spacing.










   .. method:: get_homogeneous() -> bool

      Returns whether the box is homogeneous.










   .. method:: get_max_children_per_line() -> int

      Gets the maximum number of children per line.










   .. method:: get_min_children_per_line() -> int

      Gets the minimum number of children per line.










   .. method:: get_row_spacing() -> int

      Gets the vertical spacing.










   .. method:: get_selected_children() -> list[~gi.repository.Gtk.FlowBoxChild]

      Creates a list of all selected children.










   .. method:: get_selection_mode() -> ~gi.repository.Gtk.SelectionMode

      Gets the selection mode of ``box``.










   .. method:: insert(widget: ~gi.repository.Gtk.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.







      :param widget: the ``GtkWidget`` to add


      :param position: the position to insert ``child`` in





   .. method:: 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.










   .. method:: 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.










   .. method:: prepend(child: ~gi.repository.Gtk.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: :obj:`~gi.repository.Gtk.FlowBox.insert`.



      .. versionadded:: 4.6





      :param child: the ``GtkWidget`` to add





   .. method:: remove(widget: ~gi.repository.Gtk.Widget) -> None

      Removes a child from ``box``.







      :param widget: the child widget to remove





   .. method:: remove_all() -> None

      Removes all children from ``box``.

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



      .. versionadded:: 4.12








   .. method:: select_all() -> None

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










   .. method:: select_child(child: ~gi.repository.Gtk.FlowBoxChild) -> None

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







      :param child: a child of ``box``





   .. method:: selected_foreach(func: ~typing.Callable[[...], None], *data: ~typing.Any) -> None

      Calls a function for each selected child.

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







      :param func: the function to call for each selected child


      :param data: user data to pass to the function





   .. method:: set_activate_on_single_click(single: bool) -> None

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







      :param single: :const:`True` to emit child-activated on a single click





   .. method:: set_column_spacing(spacing: int) -> None

      Sets the horizontal space to add between children.







      :param spacing: the spacing to use





   .. method:: set_filter_func(filter_func: ~typing.Callable[[...], bool] | None = None, *user_data: ~typing.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 (via
      :obj:`~gi.repository.Gtk.FlowBoxChild.changed`) or when
      :obj:`~gi.repository.Gtk.FlowBox.invalidate_filter` is called.

      Note that using a filter function is incompatible with using a model
      (see :obj:`~gi.repository.Gtk.FlowBox.bind_model`).







      :param filter_func: callback that
         lets you filter which children to show


      :param user_data: user data passed to ``filter_func``





   .. method:: set_hadjustment(adjustment: ~gi.repository.Gtk.Adjustment) -> None

      Hooks up an adjustment to focus handling in ``box``.

      The adjustment is also used for autoscrolling during
      rubberband selection. See :obj:`~gi.repository.Gtk.ScrolledWindow.get_hadjustment`
      for a typical way of obtaining the adjustment, and
      :obj:`~gi.repository.Gtk.FlowBox.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.







      :param adjustment: an adjustment which should be adjusted
         when the focus is moved among the descendents of ``container``





   .. method:: set_homogeneous(homogeneous: bool) -> None

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







      :param homogeneous: :const:`True` to create equal allotments,
         :const:`False` for variable allotments





   .. method:: 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.







      :param n_children: the maximum number of children per line





   .. method:: set_min_children_per_line(n_children: int) -> None

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







      :param n_children: the minimum number of children per line





   .. method:: set_row_spacing(spacing: int) -> None

      Sets the vertical space to add between children.







      :param spacing: the spacing to use





   .. method:: set_selection_mode(mode: ~gi.repository.Gtk.SelectionMode) -> None

      Sets how selection works in ``box``.







      :param mode: the new selection mode





   .. method:: set_sort_func(sort_func: ~typing.Callable[[...], int] | None = None, *user_data: ~typing.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 (via
      :obj:`~gi.repository.Gtk.FlowBoxChild.changed`) and when
      :obj:`~gi.repository.Gtk.FlowBox.invalidate_sort` is called.

      Note that using a sort function is incompatible with using a model
      (see :obj:`~gi.repository.Gtk.FlowBox.bind_model`).







      :param sort_func: the sort function


      :param user_data: user data passed to ``sort_func``





   .. method:: set_vadjustment(adjustment: ~gi.repository.Gtk.Adjustment) -> None

      Hooks up an adjustment to focus handling in ``box``.

      The adjustment is also used for autoscrolling during
      rubberband selection. See :obj:`~gi.repository.Gtk.ScrolledWindow.get_vadjustment`
      for a typical way of obtaining the adjustment, and
      :obj:`~gi.repository.Gtk.FlowBox.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.







      :param adjustment: an adjustment which should be adjusted
         when the focus is moved among the descendents of ``container``





   .. method:: unselect_all() -> None

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










   .. method:: unselect_child(child: ~gi.repository.Gtk.FlowBoxChild) -> None

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







      :param child: a child of ``box``









Properties
----------

.. rst-class:: interim-class

.. class:: FlowBox
   :no-index:
   

   .. attribute:: props.accept_unpaired_release
      :type: bool

      






   .. attribute:: props.activate_on_single_click
      :type: bool

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







   .. attribute:: props.column_spacing
      :type: int

      The amount of horizontal space between two children.







   .. attribute:: props.homogeneous
      :type: bool

      Determines whether all children should be allocated the
      same size.







   .. attribute:: props.max_children_per_line
      :type: int

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







   .. attribute:: props.min_children_per_line
      :type: 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.







   .. attribute:: props.row_spacing
      :type: int

      The amount of vertical space between two children.







   .. attribute:: props.selection_mode
      :type: ~gi.repository.Gtk.SelectionMode

      The selection mode used by the flow box.











Signals
-------

.. rst-class:: interim-class

.. class:: FlowBox.signals
   :no-index:
   

   .. method:: activate_cursor_child() -> None

      Emitted when the user activates the ``box``.

      This is a `keybinding signal <class.SignalAction.html>`_.










   .. method:: child_activated(child: ~gi.repository.Gtk.FlowBoxChild) -> None

      Emitted when a child has been activated by the user.







      :param child: the child that is activated





   .. method:: move_cursor(step: ~gi.repository.Gtk.MovementStep, count: int, extend: bool, modify: bool) -> bool

      Emitted when the user initiates a cursor movement.

      This is a `keybinding signal <class.SignalAction.html>`_.
      Applications should not connect to it, but may emit it with
      :func:`~gi.repository.GObject.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.


      - :kbd:`←`, :kbd:`→`, :kbd:`↑`, :kbd:`↓`
        move by individual children
      - :kbd:`Home`, :kbd:`End` move to the ends of the box
      - :kbd:`PgUp`, :kbd:`PgDn` move vertically by pages







      :param step: the granularity of the move, as a ``GtkMovementStep``


      :param count: the number of ``step`` units to move


      :param extend: whether to extend the selection


      :param modify: whether to modify the selection





   .. method:: select_all() -> None

      Emitted to select all children of the box,
      if the selection mode permits it.

      This is a `keybinding signal <class.SignalAction.html>`_.

      The default bindings for this signal is :kbd:`Ctrl`-:kbd:`a`.










   .. method:: selected_children_changed() -> None

      Emitted when the set of selected children changes.

      Use :obj:`~gi.repository.Gtk.FlowBox.selected_foreach` or
      :obj:`~gi.repository.Gtk.FlowBox.get_selected_children` to obtain the
      selected children.










   .. method:: toggle_cursor_child() -> None

      Emitted to toggle the selection of the child that has the focus.

      This is a `keybinding signal <class.SignalAction.html>`_.

      The default binding for this signal is :kbd:`Ctrl`-:kbd:`Space`.










   .. method:: unselect_all() -> None

      Emitted to unselect all children of the box,
      if the selection mode permits it.

      This is a `keybinding signal <class.SignalAction.html>`_.

      The default bindings for this signal is :kbd:`Ctrl`-:kbd:`Shift`-:kbd:`a`.