Package swingtree.api

Interface Layout

All Known Implementing Classes:
Layout.BorderLayoutInstaller, Layout.ForBoxLayout, Layout.ForFlowLayout, Layout.ForMigLayout, Layout.GridLayoutInstaller, Layout.None, Layout.Unspecific
@Immutable public interface Layout
An abstract representation of an immutable layout configuration for a specific component, for which layout manager specific implementations can be instantiated through various factory methods like border(), flow(), grid(int, int)... and then supplied to the style API through ComponentStyleDelegate.layout(Layout) so that the layout can then be installed onto a component dynamically.

The various layout types hold necessary information and implementation logic required for installing the layout onto a component through the installFor(JComponent) method, which will be used by the style engine of SwingTree every time the layout object state changes compared to the previous state effectively making the layout mechanics of a component fully dynamic.

You may implement this interface to create custom layout configurations for other kinds of LayoutManager implementations.

This interface also contains various implementations for supporting the most common types of LayoutManagers.

See Also:

  • Method Details

    • hashCode

      int hashCode()
      Overrides:
      hashCode in class Object
      Returns:
      A hash code value for this layout.

    • equals

      boolean equals(Object o)
      Overrides:
      equals in class Object
      Parameters:
      o - The object to compare this layout to.
      Returns:
      true if the supplied object is a layout that is equal to this layout, false otherwise.

    • installFor

      void installFor(JComponent component)
      Installs this layout for the supplied component.
      Parameters:
      component - The component to install this layout for.

    • unspecific

      static Layout unspecific()
      A factory method for creating a layout that does nothing (i.e. it does not install any layout for a component). This is a no-op layout that can be used to represent the lack of a specific layout being set for a component without having to set the layout to null.
      Returns:
      A layout that does nothing, i.e. it does not install any layout for a component.

    • none

      static Layout.None none()
      Returns a Layout.None layout that removes any existing LayoutManager from a component (sets it to null), enabling manual positioning of child components via their Component.setBounds(int, int, int, int) method.

      To also specify the initial bounds of child components declaratively, chain Layout.None.withChildBounds(Bounds...) on the returned instance, or use the none(Bounds...) shorthand factory.

      Returns:
      A Layout.None layout that removes any existing layout manager from a component.

    • none

      static Layout.None none(Bounds... childBounds)
      A convenience factory that creates a Layout.None layout pre-loaded with per-child Bounds. This is a shorthand for: 
      
      Layout.none().withChildBounds(childBounds)
      When installFor is called, the layout manager is first removed from the component (enabling absolute positioning), and then each supplied Bounds entry is applied to the corresponding child by index via Component.setBounds(int, int, int, int). Because the underlying storage is a sparse Association, you only need to supply bounds for the children you actually want to position; children without an entry are left untouched.
      Parameters:
      childBounds - The Bounds to apply to the component's children, in child-index order.
      Returns:
      A Layout.None layout that removes any layout manager and applies the given bounds to the corresponding children.

    • mig

      static Layout.ForMigLayout mig(LayoutConstraint constr, LayoutConstraint colConstr, LayoutConstraint rowConstr)
      The preferred factory method for creating a MigLayout-based layout configuration from type-safe LayoutConstraint objects.

      LayoutConstraint is a composable, type-safe wrapper around MigLayout constraint strings. The recommended way to use it is through the constants and factory methods available via import static swingtree.UI.*, which can then be combined with LayoutConstraint.and(LayoutConstraint): 

      
      import static swingtree.UI.*;
      // ...
      Layout.mig( FILL.and(WRAP(2)), "[shrink][grow]", "[]8[]" )
      Using LayoutConstraint instead of raw strings catches typos at call-site and makes constraint composition explicit and refactor-friendly. See the MigLayout whitepaper for full constraint documentation.

      The returned Layout.ForMigLayout instance supports fluent chaining to specify per-child component constraints via the various Layout.ForMigLayout.withChildConstraints(MigAddConstraint...) overloads.

      Parameters:
      constr - The general layout constraints for the MigLayout (e.g. FILL.and(WRAP(2))).
      colConstr - The column constraints for the MigLayout (e.g. LayoutConstraint.of("[shrink][grow]")).
      rowConstr - The row constraints for the MigLayout (e.g. LayoutConstraint.of("[]8[]")).
      Returns:
      A Layout.ForMigLayout configured with the supplied constraints.

    • mig

      static Layout.ForMigLayout mig(LayoutConstraint constr, LayoutConstraint rowConstr)
      A factory method for creating a MigLayout-based layout configuration from type-safe LayoutConstraint objects, without column constraints. This is the preferred approach over the plain-String overloads.

      See mig(LayoutConstraint, LayoutConstraint, LayoutConstraint) for full details on the LayoutConstraint API and chaining child constraints.

      Parameters:
      constr - The general layout constraints for the MigLayout.
      rowConstr - The row constraints for the MigLayout.
      Returns:
      A Layout.ForMigLayout configured with the supplied constraints.

    • mig

      static Layout.ForMigLayout mig(LayoutConstraint constr)
      A factory method for creating a MigLayout-based layout configuration from a single type-safe LayoutConstraint, with no column or row constraints. This is the preferred approach over the plain-String overload.

      See mig(LayoutConstraint, LayoutConstraint, LayoutConstraint) for full details on the LayoutConstraint API and chaining child constraints.

      Parameters:
      constr - The general layout constraints for the MigLayout.
      Returns:
      A Layout.ForMigLayout configured with the supplied constraints.

    • mig

      static Layout.ForMigLayout mig(LayoutConstraint constr, MigAddConstraint... childConstraints)
      A convenience factory method that creates a MigLayout-based layout configuration from a single type-safe LayoutConstraint together with per-child MigAddConstraints for the component's direct children.

      The childConstraints are mapped positionally: the first entry is applied to the first child, the second to the second child, and so on. Excess entries (more constraints than children) are silently ignored; children without a matching entry keep whatever constraint the parent MigLayout already has for them.

      This is a shorthand for: 

      
      Layout.mig(constr).withChildConstraints(childConstraints)
      See mig(LayoutConstraint, LayoutConstraint, LayoutConstraint) for full details on the LayoutConstraint API.
      Parameters:
      constr - The general layout constraints for the MigLayout.
      childConstraints - The MigAddConstraints to apply to the component's children, in child-index order.
      Returns:
      A Layout.ForMigLayout configured with the supplied constraints.

    • mig

      static Layout.ForMigLayout mig(String constr, String colConstr, String rowConstr)
      A convenience overload of mig(LayoutConstraint, LayoutConstraint, LayoutConstraint) that accepts plain constraint strings instead of LayoutConstraint objects. Each string is wrapped via LayoutConstraint.of(String...) before being forwarded.

      Prefer the LayoutConstraint-based overloads for new code, as they are composable and less error-prone than raw strings. Click here for more information about MigLayout.

      Parameters:
      constr - The general layout constraints string for the MigLayout.
      colConstr - The column constraints string for the MigLayout.
      rowConstr - The row constraints string for the MigLayout.
      Returns:
      A Layout.ForMigLayout configured with the supplied constraints.

    • mig

      static Layout.ForMigLayout mig(String constr, String rowConstr)
      A convenience overload of mig(LayoutConstraint, LayoutConstraint) that accepts plain constraint strings instead of LayoutConstraint objects. Each string is wrapped via LayoutConstraint.of(String...) before being forwarded.

      Prefer the LayoutConstraint-based overloads for new code, as they are composable and less error-prone than raw strings. Click here for more information about MigLayout.

      Parameters:
      constr - The general layout constraints string for the MigLayout.
      rowConstr - The row constraints string for the MigLayout.
      Returns:
      A Layout.ForMigLayout configured with the supplied constraints.

    • mig

      static Layout.ForMigLayout mig(String constr)
      A convenience overload of mig(LayoutConstraint) that accepts a plain constraint string instead of a LayoutConstraint object. The string is wrapped via LayoutConstraint.of(String...) before being forwarded.

      Prefer the LayoutConstraint-based overloads for new code, as they are composable and less error-prone than raw strings. In case you are not familiar with the MigLayout constraints, you can find more information about them here.

      Parameters:
      constr - The general layout constraints string for the MigLayout.
      Returns:
      A Layout.ForMigLayout configured with the supplied constraints.

    • mig

      static Layout.ForMigLayout mig(String constr, MigAddConstraint... childConstraints)
      A convenience factory method that creates a MigLayout-based layout configuration from a plain constraint string together with per-child MigAddConstraints for the component's direct children.

      The childConstraints are mapped positionally: the first entry is applied to the first child, the second to the second child, and so on. This is a shorthand for: 

      
      Layout.mig(constr).withChildConstraints(childConstraints)
      Prefer the LayoutConstraint-based overload mig(LayoutConstraint, MigAddConstraint...) for new code.
      Parameters:
      constr - The general layout constraints string for the MigLayout.
      childConstraints - The MigAddConstraints to apply to the component's children, in child-index order.
      Returns:
      A Layout.ForMigLayout configured with the supplied constraints.

    • flow

      static Layout.ForFlowLayout flow(UI.HorizontalAlignment align, int hgap, int vgap)
      A factory method for creating a Layout.ForFlowLayout configuration that installs a ResponsiveGridFlowLayout onto a component with the given alignment and gaps.

      The returned Layout.ForFlowLayout supports fluent chaining to specify per-child FlowCell constraints via the various Layout.ForFlowLayout.withChildConstraints(FlowCell...) overloads, enabling fully reactive responsive layouts when used together with UIForAnySwing.withLayout(sprouts.Val).

      Parameters:
      align - The alignment for the layout, which has to be one of
      hgap - The horizontal gap between components, in pixels.
      vgap - The vertical gap between component rows, in pixels.
      Returns:
      A Layout.ForFlowLayout configured with the supplied alignment and gaps.

    • flow

      static Layout.ForFlowLayout flow(UI.HorizontalAlignment align)
      A factory method for creating a Layout.ForFlowLayout configuration that installs a ResponsiveGridFlowLayout with the given alignment and default gaps of 5 pixels.

      The returned Layout.ForFlowLayout supports fluent chaining to specify per-child FlowCell constraints. See flow(UI.HorizontalAlignment, int, int) for full details.

      Parameters:
      align - The horizontal alignment for the flow of components.
      Returns:
      A Layout.ForFlowLayout configured with the supplied alignment.

    • flow

      static Layout.ForFlowLayout flow()
      A factory method for creating a Layout.ForFlowLayout configuration that installs a ResponsiveGridFlowLayout with centered alignment and default gaps of 5 pixels.

      The returned Layout.ForFlowLayout supports fluent chaining to specify per-child FlowCell constraints. See flow(UI.HorizontalAlignment, int, int) for full details.

      Returns:
      A Layout.ForFlowLayout with centered alignment and 5-pixel gaps.

    • flow

      static Layout.ForFlowLayout flow(FlowCell... childConstraints)
      A convenience factory method that creates a centered Layout.ForFlowLayout pre-loaded with per-child FlowCell constraints. This is a shorthand for: 
      
      Layout.flow().withChildConstraints(childConstraints)
      Each FlowCell is typically created via UILayoutConstants.AUTO_SPAN(Configurator): 
      
      import static swingtree.UI.*;
      // ...
      Var<Layout> layout = Var.of(
          Layout.flow(
              AUTO_SPAN( it -> it.small(12).medium(6) ),
              AUTO_SPAN( it -> it.small(12).medium(6) )
          )
      );
      UI.panel()
        .withLayout(layout)
        .add( label("Left") )
        .add( label("Right") );
      Changing the layout property at runtime will reinstall the layout and re-push all child FlowCell constraints, making the span behaviour fully reactive.
      Parameters:
      childConstraints - The FlowCell constraints to apply to the component's children in child-index order.
      Returns:
      A Layout.ForFlowLayout with centered alignment and the given child constraints.

    • flow

      static Layout.ForFlowLayout flow(UI.HorizontalAlignment align, FlowCell... childConstraints)
      A convenience factory method that creates a Layout.ForFlowLayout with the given alignment and per-child FlowCell constraints pre-loaded. This is a shorthand for: 
      
      Layout.flow(align).withChildConstraints(childConstraints)
      See flow(FlowCell...) for a usage example and reactive design notes.
      Parameters:
      align - The horizontal alignment for the flow of components.
      childConstraints - The FlowCell constraints to apply to the component's children in child-index order.
      Returns:
      A Layout.ForFlowLayout with the given alignment and child constraints.

    • border

      static Layout border(int horizontalGap, int verticalGap)
      A factory method for creating a layout that installs the BorderLayout onto a component based on the supplied parameters.
      Parameters:
      horizontalGap - The horizontal gap for the layout.
      verticalGap - The vertical gap for the layout.
      Returns:
      A layout that installs the BorderLayout onto a component.

    • border

      static Layout border()
      A factory method for creating a layout that installs the BorderLayout onto a component based on the supplied parameters. The installed layout will have a default gap of 0 pixels.
      Returns:
      A layout that installs the BorderLayout onto a component.

    • grid

      static Layout grid(int rows, int cols, int horizontalGap, int verticalGap)
      A factory method for creating a layout that installs the GridLayout onto a component based on the supplied parameters.
      Parameters:
      rows - The number of rows for the layout.
      cols - The number of columns for the layout.
      horizontalGap - The horizontal gap for the layout.
      verticalGap - The vertical gap for the layout.
      Returns:
      A layout that installs the GridLayout onto a component.

    • grid

      static Layout grid(int rows, int cols)
      A factory method for creating a layout that installs the GridLayout onto a component based on the supplied parameters. The installed layout will have a default gap of 0 pixels.
      Parameters:
      rows - The number of rows for the layout.
      cols - The number of columns for the layout.
      Returns:
      A layout that installs the GridLayout onto a component.

    • box

      static Layout box(UI.Axis axis)
      A factory method for creating a layout that installs the BoxLayout onto a component based on the supplied UI.Axis parameter. The axis determines whether the layout will be a horizontal or vertical BoxLayout.
      Parameters:
      axis - The axis for the layout, which has to be one of
      Returns:
      A layout that installs the BoxLayout onto a component.

    • box

      static Layout box()
      A factory method for creating a layout that installs the BoxLayout onto a component with a default axis of UI.Axis.X.
      Returns:
      A layout that installs the default BoxLayout onto a component.