Class BorderLayout

java.lang.Object
com.codename1.ui.layouts.Layout
com.codename1.ui.layouts.BorderLayout
public class BorderLayout extends Layout

A border layout lays out a container, arranging and resizing its components to fit in five regions: north, south, east, west, and center. Each region may contain no more than one component, and is identified by a corresponding constant: NORTH, SOUTH, EAST, WEST, and CENTER. When adding a component to a container with a border layout, use one of these five constants.

The border layout scales all of the components within it to match the available constraints. The NORTH & SOUTH components use their preferred height but are stretched to take up the full width available. The EAST & WEST do the same for the reverse axis however they leave room for the NORTH/SOUTH entries if they are defined.

The CENTER constraint will take up the rest of the available space regardless of its preferred size. This is normally very useful, however in some cases we would prefer that the center component will actually position itself in the middle of the available space. For this we have the setCenterBehavior method.

Because of its scaling behavior scrolling a border layout makes no sense. However it is a common mistake to apply a border layout to a scrollable container or trying to make a border layout scrollable. That is why the com.codename1.ui.Container class explicitly blocks scrolling on a BorderLayout.

Typical usage of this class:

Form hi = new Form("Border Layout", new BorderLayout());
hi.add(BorderLayout.CENTER, new Label("Center")).
    add(BorderLayout.SOUTH, new Label("South")).
    add(BorderLayout.NORTH, new Label("North")).
    add(BorderLayout.EAST, new Label("East")).
    add(BorderLayout.WEST, new Label("West"));
hi.show();

When defining the center behavior we can get very different results:

Form hi = new Form("Border Layout", new BorderLayout());
((BorderLayout)hi.getLayout()).setCenterBehavior(BorderLayout.CENTER_BEHAVIOR_CENTER);
hi.add(BorderLayout.CENTER, new Label("Center")).
    add(BorderLayout.SOUTH, new Label("South")).
    add(BorderLayout.NORTH, new Label("North")).
    add(BorderLayout.EAST, new Label("East")).
    add(BorderLayout.WEST, new Label("West"));
hi.show();

Notice that in the case of RTL (right to left language also known as bidi) the EAST and WEST values are implicitly reversed as shown in this image:

You can read further in the BorderLayout section in the developer guide.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    CENTER
    The center layout constraint (middle of container)
    static final int
    CENTER_BEHAVIOR_CENTER
    Defines the behavior of the component placed in the center position of the layout, places the component in the center of the space available to the center component.
    static final int
    CENTER_BEHAVIOR_CENTER_ABSOLUTE
    Defines the behavior of the component placed in the center position of the layout, places the component in the center of the surrounding container
    static final int
    CENTER_BEHAVIOR_SCALE
    Defines the behavior of the component placed in the center position of the layout, by default it is scaled to the available space
    static final int
    CENTER_BEHAVIOR_TOTAL_BELLOW
    Deprecated due to spelling mistake, use CENTER_BEHAVIOR_TOTAL_BELOW The center component takes up the entire screens and the sides are automatically placed on top of it thus creating a layered effect
    static final int
    CENTER_BEHAVIOR_TOTAL_BELOW
    The center component takes up the entire screens and the sides are automatically placed on top (or below based on z-order) thus creating a layered effect
    static final String
    EAST
    The east layout constraint (right of container).
    static final String
    NORTH
    The north layout constraint (top of container).
    static final String
    OVERLAY
    Overlay on top of the other layout components
    static final String
    SOUTH
    The south layout constraint (bottom of container).
    static final String
    WEST
    The west layout constraint (left of container).

  • Constructor Summary

    Constructors
    Constructor
    Description
    BorderLayout()
    Creates a new instance of BorderLayout
    BorderLayout(int behavior)
    Creates a new instance of BorderLayout with absolute behavior

  • Method Summary

    Modifier and Type
    Method
    Description
    static BorderLayout
    absolute()
    Shorthand for new BorderLayout(BorderLayout.CENTER_BEHAVIOR_CENTER_ABSOLUTE)
    void
    addLayoutComponent(Object name, Component comp, Container c)
    Some layouts can optionally track the addition of elements with meta-data that allows the user to "hint" on object positioning.
    static BorderLayout
    center()
    Shorthand for new BorderLayout(BorderLayout.CENTER_BEHAVIOR_CENTER)
    static Container
    center(Component center)
    Convenience method that creates a border layout container and places the given component in the center
    static Container
    centerAbsolute(Component center)
    Convenience method that creates a border layout container and places the given component in the center with the #CENTER_BEHAVIOR_CENTER_ABSOLUTE constraint applied
    static Container
    centerAbsoluteEastWest(Component center, Component east, Component west)
    Convenience method that creates a border layout absolute center container and places the given component in the center east and west respectively
    static Container
    centerCenter(Component center)
    Convenience method that creates a border layout container and places the given component in the center with the #CENTER_BEHAVIOR_CENTER constraint applied
    static Container
    centerCenterEastWest(Component center, Component east, Component west)
    Convenience method that creates a border layout center container and places the given component in the center east and west respectively with the #CENTER_BEHAVIOR_CENTER constraint applied
    static Container
    centerEastWest(Component center, Component east, Component west)
    Convenience method that creates a border layout container and places the given component in the center east and west respectively
    static Container
    centerTotalBelow(Component center)
    Convenience method that creates a border layout container and places the given component in the center with the #CENTER_BEHAVIOR_TOTAL_BELOW constraint applied
    static Container
    centerTotalBelowEastWest(Component center, Component east, Component west)
    Convenience method that creates a border layout center container and places the given component in the center east and west respectively with the #CENTER_BEHAVIOR_TOTAL_BELOW constraint applied
    void
    defineLandscapeSwap(String portraitPosition, String landscapePosition)
    This method allows swapping positions within the border layout when the layout orientation changes to landscape or if the layout starts off as landscape.
    static Container
    east(Component east)
    Convenience method that creates a border layout container and places the given component in the east
    boolean
    equals(Object o)
    Component
    getCenter()
    Returns the component in the center location
    int
    getCenterBehavior()
    Defines the behavior of the center component to one of the constants defined in this class
    protected Component[]
    getChildrenInTraversalOrder(Container parent)
    Gets the children of the parent container in the order that they should be traversed when tabbing through a form.
    Object
    getComponentConstraint(Component comp)
    Returns the component constraint
    Component
    getEast()
    Returns the component in the east location
    String
    getLandscapeSwap(String portraitPosition)
    Returns the landscape swap destination for the given border layout element if such a destination is defined.
    Component
    getNorth()
    Returns the component in the north location
    Component
    getOverlay()
    Returns overlay component.
    Dimension
    getPreferredSize(Container parent)
    Returns the container preferred size
    Component
    getSouth()
    Returns the component in the south location
    Component
    getWest()
    Returns the component in the west location
    int
    hashCode()
    boolean
    isAbsoluteCenter()
    Indicates that the center shouldn't grow and should be placed exactly in the center of the layout
    boolean
    isConstraintTracking()
    If this method returns true, the addLayoutComponent method will be called when replacing a layout for every component within the container
    boolean
    isOverlapSupported()
    This method returns true if the Layout allows Components to Overlap.
    boolean
    isScaleEdges()
    Stretches the edge components (NORTH/EAST/WEST/SOUTH)
    void
    layoutContainer(Container target)
    Layout the given parent container children
    static Container
    north(Component north)
    Convenience method that creates a border layout container and places the given component in the north
    boolean
    obscuresPotential(Container parent)
    Some layout managers can obscure their child components in some cases this returns true if the basic underpinnings are in place for that.
    boolean
    overridesTabIndices(Container parent)
    If a layout specifies a different traversal order of its components than the component index, then it should override this method to return true, and it should also override #getChildrenInTraversalOrder(com.codename1.ui.Container) to set the tab indices of a container's children.
    void
    removeLayoutComponent(Component comp)
    Removes the component from the layout this operation is only useful if the layout maintains references to components within it
    void
    setAbsoluteCenter(boolean absoluteCenter)
    Indicates that the center shouldn't grow and should be placed exactly in the center of the layout
    void
    setCenterBehavior(int centerBehavior)
    Defines the behavior of the center component to one of the constants defined in this class
    void
    setScaleEdges(boolean scaleEdges)
    Stretches the edge components (NORTH/EAST/WEST/SOUTH)
    static Container
    south(Component south)
    Convenience method that creates a border layout container and places the given component in the south
    String
    toString()
    static BorderLayout
    totalBelow()
    Shorthand for new BorderLayout(BorderLayout.CENTER_BEHAVIOR_TOTAL_BELOW)
    static Container
    west(Component west)
    Convenience method that creates a border layout container and places the given component in the west

    Methods inherited from class Layout

    cloneConstraint, updateTabIndices

    Methods inherited from class Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

  • Field Details

    • CENTER_BEHAVIOR_SCALE

      public static final int CENTER_BEHAVIOR_SCALE
      Defines the behavior of the component placed in the center position of the layout, by default it is scaled to the available space
      See Also:

    • CENTER_BEHAVIOR_CENTER

      public static final int CENTER_BEHAVIOR_CENTER
      Defines the behavior of the component placed in the center position of the layout, places the component in the center of the space available to the center component.
      See Also:

    • CENTER_BEHAVIOR_CENTER_ABSOLUTE

      public static final int CENTER_BEHAVIOR_CENTER_ABSOLUTE
      Defines the behavior of the component placed in the center position of the layout, places the component in the center of the surrounding container
      See Also:

    • CENTER_BEHAVIOR_TOTAL_BELLOW

      public static final int CENTER_BEHAVIOR_TOTAL_BELLOW

      Deprecated due to spelling mistake, use CENTER_BEHAVIOR_TOTAL_BELOW The center component takes up the entire screens and the sides are automatically placed on top of it thus creating a layered effect

      Deprecated

      Deprecated due to spelling mistake, use CENTER_BEHAVIOR_TOTAL_BELOW

      See Also:

    • CENTER_BEHAVIOR_TOTAL_BELOW

      public static final int CENTER_BEHAVIOR_TOTAL_BELOW
      The center component takes up the entire screens and the sides are automatically placed on top (or below based on z-order) thus creating a layered effect
      See Also:

    • NORTH

      public static final String NORTH
      The north layout constraint (top of container).
      See Also:

    • SOUTH

      public static final String SOUTH
      The south layout constraint (bottom of container).
      See Also:

    • CENTER

      public static final String CENTER
      The center layout constraint (middle of container)
      See Also:

    • WEST

      public static final String WEST
      The west layout constraint (left of container).
      See Also:

    • EAST

      public static final String EAST
      The east layout constraint (right of container).
      See Also:

    • OVERLAY

      public static final String OVERLAY
      Overlay on top of the other layout components
      See Also:

  • Constructor Details

    • BorderLayout

      public BorderLayout()
      Creates a new instance of BorderLayout

    • BorderLayout

      public BorderLayout(int behavior)

      Creates a new instance of BorderLayout with absolute behavior

      Parameters
      • behavior: identical value as the setCenterBehavior method

  • Method Details

    • center

      public static BorderLayout center()

      Shorthand for new BorderLayout(BorderLayout.CENTER_BEHAVIOR_CENTER)

      Returns

      a new BorderLayout with #CENTER_BEHAVIOR_CENTER constraint applied

    • absolute

      public static BorderLayout absolute()

      Shorthand for new BorderLayout(BorderLayout.CENTER_BEHAVIOR_CENTER_ABSOLUTE)

      Returns

      a new BorderLayout with #CENTER_BEHAVIOR_CENTER_ABSOLUTE constraint applied

    • totalBelow

      public static BorderLayout totalBelow()

      Shorthand for new BorderLayout(BorderLayout.CENTER_BEHAVIOR_TOTAL_BELOW)

      Returns

      a new BorderLayout with #CENTER_BEHAVIOR_TOTAL_BELOW constraint applied

    • center

      public static Container center(Component center)

      Convenience method that creates a border layout container and places the given component in the center

      Parameters
      • center: the center component
      Returns

      the created component

    • centerEastWest

      public static Container centerEastWest(Component center, Component east, Component west)

      Convenience method that creates a border layout container and places the given component in the center east and west respectively

      Parameters

      • center: the center component

      • east: component or null to ignore

      • west: component or null to ignore

      Returns

      the created component

    • centerAbsoluteEastWest

      public static Container centerAbsoluteEastWest(Component center, Component east, Component west)

      Convenience method that creates a border layout absolute center container and places the given component in the center east and west respectively

      Parameters

      • center: the center component

      • east: component or null to ignore

      • west: component or null to ignore

      Returns

      the created component

    • centerCenterEastWest

      public static Container centerCenterEastWest(Component center, Component east, Component west)

      Convenience method that creates a border layout center container and places the given component in the center east and west respectively with the #CENTER_BEHAVIOR_CENTER constraint applied

      Parameters

      • center: the center component

      • east: component or null to ignore

      • west: component or null to ignore

      Returns

      the created component

    • centerTotalBelowEastWest

      public static Container centerTotalBelowEastWest(Component center, Component east, Component west)

      Convenience method that creates a border layout center container and places the given component in the center east and west respectively with the #CENTER_BEHAVIOR_TOTAL_BELOW constraint applied

      Parameters

      • center: the center component

      • east: component or null to ignore

      • west: component or null to ignore

      Returns

      the created component

    • centerCenter

      public static Container centerCenter(Component center)

      Convenience method that creates a border layout container and places the given component in the center with the #CENTER_BEHAVIOR_CENTER constraint applied

      Parameters
      • center: the center component
      Returns

      the created component

    • centerAbsolute

      public static Container centerAbsolute(Component center)

      Convenience method that creates a border layout container and places the given component in the center with the #CENTER_BEHAVIOR_CENTER_ABSOLUTE constraint applied

      Parameters
      • center: the center component
      Returns

      the created component

    • centerTotalBelow

      public static Container centerTotalBelow(Component center)

      Convenience method that creates a border layout container and places the given component in the center with the #CENTER_BEHAVIOR_TOTAL_BELOW constraint applied

      Parameters
      • center: the center component
      Returns

      the created component

    • north

      public static Container north(Component north)

      Convenience method that creates a border layout container and places the given component in the north

      Parameters
      • north: the north component
      Returns

      the created component

    • south

      public static Container south(Component south)

      Convenience method that creates a border layout container and places the given component in the south

      Parameters
      • south: the south component
      Returns

      the created component

    • east

      public static Container east(Component east)

      Convenience method that creates a border layout container and places the given component in the east

      Parameters
      • east: the east component
      Returns

      the created component

    • west

      public static Container west(Component west)

      Convenience method that creates a border layout container and places the given component in the west

      Parameters
      • west: the west component
      Returns

      the created component

    • addLayoutComponent

      public void addLayoutComponent(Object name, Component comp, Container c)

      Some layouts can optionally track the addition of elements with meta-data that allows the user to "hint" on object positioning.

      Parameters

      • value: optional meta data information, like alignment orientation

      • comp: the added component to the layout

      • c: the parent container

      Overrides:
      addLayoutComponent in class Layout

    • removeLayoutComponent

      public void removeLayoutComponent(Component comp)

      Removes the component from the layout this operation is only useful if the layout maintains references to components within it

      Parameters
      • comp: the removed component from layout
      Overrides:
      removeLayoutComponent in class Layout

    • getComponentConstraint

      public Object getComponentConstraint(Component comp)

      Returns the component constraint

      Parameters
      • comp: the component whose constraint is queried
      Returns

      one of the constraints defined in this class

      Overrides:
      getComponentConstraint in class Layout

    • layoutContainer

      public void layoutContainer(Container target)

      Layout the given parent container children

      Parameters
      • parent: the given parent container
      Specified by:
      layoutContainer in class Layout

    • getPreferredSize

      public Dimension getPreferredSize(Container parent)

      Returns the container preferred size

      Parameters
      • parent: the parent container
      Returns

      the container preferred size

      Specified by:
      getPreferredSize in class Layout

    • getSouth

      public Component getSouth()

      Returns the component in the south location

      Returns

      the component in the constraint

    • getCenter

      public Component getCenter()

      Returns the component in the center location

      Returns

      the component in the constraint

    • getNorth

      public Component getNorth()

      Returns the component in the north location

      Returns

      the component in the constraint

    • getEast

      public Component getEast()

      Returns the component in the east location

      Returns

      the component in the constraint

    • getWest

      public Component getWest()

      Returns the component in the west location

      Returns

      the component in the constraint

    • getOverlay

      public Component getOverlay()

      Returns overlay component.

      Returns

      The overlay component.

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • defineLandscapeSwap

      public void defineLandscapeSwap(String portraitPosition, String landscapePosition)

      This method allows swapping positions within the border layout when the layout orientation changes to landscape or if the layout starts off as landscape.

      Parameters

      • portraitPosition: @param portraitPosition the position for the component when in portrait (this position should always be used when adding a component to the layout). One of NORTH/SOUTH/EAST/WEST/CENTER.

      • landscapePosition: the destination position to use in landscape

    • getLandscapeSwap

      public String getLandscapeSwap(String portraitPosition)

      Returns the landscape swap destination for the given border layout element if such a destination is defined.

      Parameters
      • portraitPosition: the constraint used when placing the component
      Returns

      the constraint to use when in landscape or null if undefined

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Layout

    • hashCode

      public int hashCode()
      Description copied from class: Layout
      Overrides:
      hashCode in class Layout

    • isAbsoluteCenter

      public boolean isAbsoluteCenter()

      Indicates that the center shouldn't grow and should be placed exactly in the center of the layout

      Returns

      the absoluteCenter

      Deprecated

      use center behavior instead

    • setAbsoluteCenter

      public void setAbsoluteCenter(boolean absoluteCenter)

      Indicates that the center shouldn't grow and should be placed exactly in the center of the layout

      Parameters
      • absoluteCenter: the absoluteCenter to set
      Deprecated

      use center behavior instead

    • getCenterBehavior

      public int getCenterBehavior()

      Defines the behavior of the center component to one of the constants defined in this class

      Returns

      the centerBehavior

    • setCenterBehavior

      public void setCenterBehavior(int centerBehavior)

      Defines the behavior of the center component to one of the constants defined in this class

      Parameters
      • centerBehavior: the centerBehavior to set

    • isOverlapSupported

      public boolean isOverlapSupported()

      This method returns true if the Layout allows Components to Overlap.

      Returns

      true if Components may intersect in this layout

      Overrides:
      isOverlapSupported in class Layout

    • isScaleEdges

      public boolean isScaleEdges()

      Stretches the edge components (NORTH/EAST/WEST/SOUTH)

      Returns

      the scaleEdges

    • setScaleEdges

      public void setScaleEdges(boolean scaleEdges)

      Stretches the edge components (NORTH/EAST/WEST/SOUTH)

      Parameters
      • scaleEdges: the scaleEdges to set

    • isConstraintTracking

      public boolean isConstraintTracking()

      If this method returns true, the addLayoutComponent method will be called when replacing a layout for every component within the container

      Returns

      false by default

      Overrides:
      isConstraintTracking in class Layout

    • obscuresPotential

      public boolean obscuresPotential(Container parent)

      Some layout managers can obscure their child components in some cases this returns true if the basic underpinnings are in place for that. This method doesn't take padding/margin etc. into account since that is checked by the caller

      Parameters
      • parent: parent container
      Returns

      true if there is a chance that this layout manager can fully obscure the background, when in doubt return false...

      Overrides:
      obscuresPotential in class Layout

    • overridesTabIndices

      public boolean overridesTabIndices(Container parent)
      Description copied from class: Layout

      If a layout specifies a different traversal order of its components than the component index, then it should override this method to return true, and it should also override #getChildrenInTraversalOrder(com.codename1.ui.Container) to set the tab indices of a container's children.

      Parameters
      • parent: The parent component.
      Returns

      True if this layout overrides tab traversal order.

      Overrides:
      overridesTabIndices in class Layout

    • getChildrenInTraversalOrder

      protected Component[] getChildrenInTraversalOrder(Container parent)
      Description copied from class: Layout

      Gets the children of the parent container in the order that they should be traversed when tabbing through a form.

      This should only be overridden if the Layout defines a different traversal order than the standard index order.

      Layouts that implement this method, should override the #overridesTabIndices(com.codename1.ui.Container) method to return true.

      Parameters
      • parent
      Returns

      Array of Components in the order

      Overrides:
      getChildrenInTraversalOrder in class Layout