Class FlowBox

java.lang.Object
org.javagi.base.ProxyInstance
org.gnome.gobject.TypeInstance
org.gnome.gobject.GObject
org.gnome.gobject.InitiallyUnowned
org.gnome.gtk.Widget
org.gnome.gtk.FlowBox
All Implemented Interfaces:
Accessible, Buildable, ConstraintTarget, Orientable, Proxy
@Generated("org.javagi.JavaGI") public class FlowBox extends Widget implements Accessible, Buildable, ConstraintTarget, Orientable

Puts child widgets in a reflowing grid.

An example GtkFlowBox

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(Widget, int), 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:

  • Gtk.FlowBox::move-cursor
  • Gtk.FlowBox::select-all
  • Gtk.FlowBox::toggle-cursor-child
  • Gtk.FlowBox::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 Gtk.AccessibleRole.grid role, and GtkFlowBoxChild uses the Gtk.AccessibleRole.grid_cell role.

  • Constructor Details

    • FlowBox

      public FlowBox(MemorySegment address)
      Create a FlowBox instance for the provided memory address.
      Parameters:
      address - the memory address of the native object

    • FlowBox

      public FlowBox()
      Create a new FlowBox.

  • Method Details

    • getType

      public static @Nullable Type getType()
      Get the GType of the FlowBox class.
      Returns:
      the GType

    • getMemoryLayout

      public static MemoryLayout getMemoryLayout()
      The memory layout of the native struct.
      Returns:
      the memory layout

    • asParent

      protected FlowBox asParent()
      Return this instance as if it were its parent type. Comparable to the Java super keyword, but ensures the parent typeclass is also used in native code.
      Overrides:
      asParent in class Widget
      Returns:
      the instance as if it were its parent type

    • append

      public void append(Widget child)

      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(Widget, int).

      Parameters:
      child - the GtkWidget to add
      Since:
      4.6

    • bindModel

      public void bindModel(@Nullable ListModel model, @Nullable FlowBoxCreateWidgetFunc createWidgetFunc)

      Binds model to box.

      If this FlowBox was already bound to a model, that previous binding is destroyed.

      The contents of this FlowBox are cleared and then filled with widgets that represent items from model. this FlowBox is updated whenever model changes. If model is null, this FlowBox is left empty.

      It is undefined to add or remove widgets directly (for example, with insert(Widget, int)) while this FlowBox 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 this FlowBox
      createWidgetFunc - a function that creates widgets for items

    • getActivateOnSingleClick

      public boolean getActivateOnSingleClick()
      Returns whether children activate on single clicks.
      Returns:
      true if children are activated on single click, false otherwise

    • getChildAtIndex

      public @Nullable FlowBoxChild getChildAtIndex(int idx)
      Gets the nth child in the box.
      Parameters:
      idx - the position of the child
      Returns:
      the child widget, which will always be a GtkFlowBoxChild or null in case no child widget with the given index exists.

    • getChildAtPos

      public @Nullable FlowBoxChild getChildAtPos(int x, int y)

      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
      Returns:
      the child widget, which will always be a GtkFlowBoxChild or null in case no child widget exists for the given x and y coordinates.

    • getColumnSpacing

      public int getColumnSpacing()
      Gets the horizontal spacing.
      Returns:
      the horizontal spacing

    • getHomogeneous

      public boolean getHomogeneous()
      Returns whether the box is homogeneous.
      Returns:
      true if the box is homogeneous.

    • getMaxChildrenPerLine

      public int getMaxChildrenPerLine()
      Gets the maximum number of children per line.
      Returns:
      the maximum number of children per line

    • getMinChildrenPerLine

      public int getMinChildrenPerLine()
      Gets the minimum number of children per line.
      Returns:
      the minimum number of children per line

    • getRowSpacing

      public int getRowSpacing()
      Gets the vertical spacing.
      Returns:
      the vertical spacing

    • getSelectedChildren

      public List<FlowBoxChild> getSelectedChildren()
      Creates a list of all selected children.
      Returns:
      A GList containing the GtkWidget for each selected child. Free with g_list_free() when done.

    • getSelectionMode

      public SelectionMode getSelectionMode()
      Gets the selection mode of box.
      Returns:
      the GtkSelectionMode

    • insert

      public void insert(Widget widget, int position)

      Inserts the widget into this FlowBox 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

    • invalidateFilter

      public void invalidateFilter()

      Updates the filtering for all children.

      Call this function when the result of the filter function on the this FlowBox 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.

    • invalidateSort

      public void invalidateSort()

      Updates the sorting for all children.

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

    • prepend

      public void prepend(Widget child)

      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(Widget, int).

      Parameters:
      child - the GtkWidget to add
      Since:
      4.6

    • remove

      public void remove(Widget widget)
      Removes a child from box.
      Parameters:
      widget - the child widget to remove

    • removeAll

      public void removeAll()

      Removes all children from box.

      This function does nothing if this FlowBox is backed by a model.

      Since:
      4.12

    • selectAll

      public void selectAll()
      Select all children of box, if the selection mode allows it.

    • selectChild

      public void selectChild(FlowBoxChild child)
      Selects a single child of box, if the selection mode allows it.
      Parameters:
      child - a child of this FlowBox

    • selectedForeach

      public void selectedForeach(@Nullable FlowBoxForeachFunc func)

      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

    • setActivateOnSingleClick

      public void setActivateOnSingleClick(boolean single)
      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

    • setColumnSpacing

      public void setColumnSpacing(int spacing)
      Sets the horizontal space to add between children.
      Parameters:
      spacing - the spacing to use

    • setFilterFunc

      public void setFilterFunc(@Nullable FlowBoxFilterFunc filterFunc)

      By setting a filter function on the this FlowBox 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 filterFunc will be called for each child after the call, and it will continue to be called each time a child changes (via FlowBoxChild.changed()) or when invalidateFilter() is called.

      Note that using a filter function is incompatible with using a model (see bindModel(ListModel, FlowBoxCreateWidgetFunc)).

      Parameters:
      filterFunc - callback that lets you filter which children to show

    • setHadjustment

      public void setHadjustment(Adjustment adjustment)

      Hooks up an adjustment to focus handling in box.

      The adjustment is also used for autoscrolling during rubberband selection. See ScrolledWindow.getHadjustment() for a typical way of obtaining the adjustment, and setVadjustment(Adjustment) 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

    • setHomogeneous

      public void setHomogeneous(boolean homogeneous)
      Sets whether or not all children of this FlowBox are given equal space in the box.
      Parameters:
      homogeneous - true to create equal allotments, false for variable allotments

    • setMaxChildrenPerLine

      public void setMaxChildrenPerLine(int nChildren)

      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 nChildren children long in the given orientation.

      Parameters:
      nChildren - the maximum number of children per line

    • setMinChildrenPerLine

      public void setMinChildrenPerLine(int nChildren)
      Sets the minimum number of children to line up in box’s orientation before flowing.
      Parameters:
      nChildren - the minimum number of children per line

    • setRowSpacing

      public void setRowSpacing(int spacing)
      Sets the vertical space to add between children.
      Parameters:
      spacing - the spacing to use

    • setSelectionMode

      public void setSelectionMode(SelectionMode mode)
      Sets how selection works in box.
      Parameters:
      mode - the new selection mode

    • setSortFunc

      public void setSortFunc(@Nullable FlowBoxSortFunc sortFunc)

      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 sortFunc will be called for each child after the call, and will continue to be called each time a child changes (via FlowBoxChild.changed()) and when invalidateSort() is called.

      Note that using a sort function is incompatible with using a model (see bindModel(ListModel, FlowBoxCreateWidgetFunc)).

      Parameters:
      sortFunc - the sort function

    • setVadjustment

      public void setVadjustment(Adjustment adjustment)

      Hooks up an adjustment to focus handling in box.

      The adjustment is also used for autoscrolling during rubberband selection. See ScrolledWindow.getVadjustment() for a typical way of obtaining the adjustment, and setHadjustment(Adjustment) 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

    • unselectAll

      public void unselectAll()
      Unselect all children of box, if the selection mode allows it.

    • unselectChild

      public void unselectChild(FlowBoxChild child)
      Unselects a single child of box, if the selection mode allows it.
      Parameters:
      child - a child of this FlowBox

    • onActivateCursorChild

      public SignalConnection<FlowBox.ActivateCursorChildCallback> onActivateCursorChild(FlowBox.ActivateCursorChildCallback handler)

      Emitted when the user activates the box.

      This is a keybinding signal.

      Parameters:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      See Also:

    • emitActivateCursorChild

      public void emitActivateCursorChild()
      Emits the "activate-cursor-child" signal. See onActivateCursorChild(FlowBox.ActivateCursorChildCallback).

    • onChildActivated

      public SignalConnection<FlowBox.ChildActivatedCallback> onChildActivated(FlowBox.ChildActivatedCallback handler)
      Emitted when a child has been activated by the user.
      Parameters:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      See Also:

    • emitChildActivated

      public void emitChildActivated(@Nullable FlowBoxChild child)
      Emits the "child-activated" signal. See onChildActivated(FlowBox.ChildActivatedCallback).

    • onMoveCursor

      public SignalConnection<FlowBox.MoveCursorCallback> onMoveCursor(FlowBox.MoveCursorCallback handler)

      Emitted when the user initiates a cursor movement.

      This is a keybinding signal. 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 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:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      See Also:

    • emitMoveCursor

      public boolean emitMoveCursor(MovementStep step, int count, boolean extend, boolean modify)
      Emits the "move-cursor" signal. See onMoveCursor(FlowBox.MoveCursorCallback).

    • onSelectAll

      public SignalConnection<FlowBox.SelectAllCallback> onSelectAll(FlowBox.SelectAllCallback handler)

      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.

      Parameters:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      See Also:

    • emitSelectAll

      public void emitSelectAll()
      Emits the "select-all" signal. See onSelectAll(FlowBox.SelectAllCallback).

    • onSelectedChildrenChanged

      public SignalConnection<FlowBox.SelectedChildrenChangedCallback> onSelectedChildrenChanged(FlowBox.SelectedChildrenChangedCallback handler)

      Emitted when the set of selected children changes.

      Use selectedForeach(FlowBoxForeachFunc) or getSelectedChildren() to obtain the selected children.

      Parameters:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      See Also:

    • emitSelectedChildrenChanged

      public void emitSelectedChildrenChanged()
      Emits the "selected-children-changed" signal. See onSelectedChildrenChanged(FlowBox.SelectedChildrenChangedCallback).

    • onToggleCursorChild

      public SignalConnection<FlowBox.ToggleCursorChildCallback> onToggleCursorChild(FlowBox.ToggleCursorChildCallback handler)

      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.

      Parameters:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      See Also:

    • emitToggleCursorChild

      public void emitToggleCursorChild()
      Emits the "toggle-cursor-child" signal. See onToggleCursorChild(FlowBox.ToggleCursorChildCallback).

    • onUnselectAll

      public SignalConnection<FlowBox.UnselectAllCallback> onUnselectAll(FlowBox.UnselectAllCallback handler)

      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.

      Parameters:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      See Also:

    • emitUnselectAll

      public void emitUnselectAll()
      Emits the "unselect-all" signal. See onUnselectAll(FlowBox.UnselectAllCallback).

    • builder

      public static FlowBox.Builder<? extends FlowBox.Builder> builder()
      A FlowBox.Builder object constructs a FlowBox with the specified properties. Use the various set...() methods to set properties, and finish construction with FlowBox.Builder.build().
      Returns:
      the builder object