: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`\. Shortcuts and Gestures -------------------------------------------------------------------------------- The following signals have default keybindings: - :obj:`~gi.repository.Gtk.FlowBox.signals.move_cursor` - :obj:`~gi.repository.Gtk.FlowBox.signals.select_all` - :obj:`~gi.repository.Gtk.FlowBox.signals.toggle_cursor_child` - :obj:`~gi.repository.Gtk.FlowBox.signals.unselect_all` CSS nodes -------------------------------------------------------------------------------- .. code-block:: :dedent: flowbox ├── flowboxchild │ ╰── ├── flowboxchild │ ╰── ┊ ╰── [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.GObject.Object, ~typing.Any], ~gi.repository.Gtk.Widget], user_data: ~typing.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 :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[[~gi.repository.Gtk.FlowBox, ~gi.repository.Gtk.FlowBoxChild, ~typing.Any], None], data: ~typing.Any = None) -> 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[[~gi.repository.Gtk.FlowBoxChild, ~typing.Any], bool] | None = None, user_data: ~typing.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 :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[[~gi.repository.Gtk.FlowBoxChild, ~gi.repository.Gtk.FlowBoxChild, ~typing.Any], int] | None = None, user_data: ~typing.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 :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 The type of the None singleton. .. attribute:: props.activate_on_single_click :type: bool The type of the None singleton. .. attribute:: props.column_spacing :type: int The type of the None singleton. .. attribute:: props.homogeneous :type: bool The type of the None singleton. .. attribute:: props.max_children_per_line :type: int The type of the None singleton. .. attribute:: props.min_children_per_line :type: int The type of the None singleton. .. attribute:: props.row_spacing :type: int The type of the None singleton. .. attribute:: props.selection_mode :type: ~gi.repository.Gtk.SelectionMode The type of the None singleton. Signals ------- .. rst-class:: interim-class .. class:: FlowBox.signals :no-index: .. method:: activate_cursor_child() -> None The type of the None singleton. .. method:: child_activated(child: ~gi.repository.Gtk.FlowBoxChild) -> None The type of the None singleton. :param child: the child that is activated .. method:: move_cursor(step: ~gi.repository.Gtk.MovementStep, count: int, extend: bool, modify: bool) -> bool The type of the None singleton. :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 The type of the None singleton. .. method:: selected_children_changed() -> None The type of the None singleton. .. method:: toggle_cursor_child() -> None The type of the None singleton. .. method:: unselect_all() -> None The type of the None singleton.