public class BorderLayout

  1. Object
  2. Layout
  3. BorderLayout

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.

Fields

public static final int CENTER_BEHAVIOR_SCALE = 0Defines the behavior of the component placed in the center position of the layout, by default it is scaled to the available space
public static final int CENTER_BEHAVIOR_CENTER = 1Defines 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.
public static final int CENTER_BEHAVIOR_CENTER_ABSOLUTE = 2Defines the behavior of the component placed in the center position of the layout, places the component in the center of the surrounding container
public static final int CENTER_BEHAVIOR_TOTAL_BELLOW = 3Deprecated 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
public static final int CENTER_BEHAVIOR_TOTAL_BELOW = 3The 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
public static final String NORTH = "North"The north layout constraint (top of container).
public static final String SOUTH = "South"The south layout constraint (bottom of container).
public static final String CENTER = "Center"The center layout constraint (middle of container)
public static final String WEST = "West"The west layout constraint (left of container).
public static final String EAST = "East"The east layout constraint (right of container).
public static final String OVERLAY = "Overlay"Overlay on top of the other layout components

Constructors

public BorderLayout()Creates a new instance of BorderLayout
public BorderLayout(int behavior)Creates a new instance of BorderLayout with absolute behavior

Methods

public static BorderLayout center()Shorthand for new BorderLayout(BorderLayout.CENTER_BEHAVIOR_CENTER)
public static BorderLayout absolute()Shorthand for new BorderLayout(BorderLayout.CENTER_BEHAVIOR_CENTER_ABSOLUTE)
public static BorderLayout totalBelow()Shorthand for new BorderLayout(BorderLayout.CENTER_BEHAVIOR_TOTAL_BELOW)
public static Container center(Component center)Convenience method that creates a border layout container and places the given component in the center
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
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
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
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
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
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
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
public static Container north(Component north)Convenience method that creates a border layout container and places the given component in the north
public static Container south(Component south)Convenience method that creates a border layout container and places the given component in the south
public static Container east(Component east)Convenience method that creates a border layout container and places the given component in the east
public static Container west(Component west)Convenience method that creates a border layout container and places the given component in the west
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.
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
public Object getComponentConstraint(Component comp)Returns the component constraint
public void layoutContainer(Container target)Layout the given parent container children
public Dimension getPreferredSize(Container parent)Returns the container preferred size
public Component getSouth()Returns the component in the south location
public Component getCenter()Returns the component in the center location
public Component getNorth()Returns the component in the north location
public Component getEast()Returns the component in the east location
public Component getWest()Returns the component in the west location
public Component getOverlay()Returns overlay component.
public String toString()Returns a string representation of the object.
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.
public String getLandscapeSwap(String portraitPosition)Returns the landscape swap destination for the given border layout element if such a destination is defined.
public boolean equals(Object o)Indicates whether some other object is “equal to” this one.
public int hashCode()Returns a hash code value for the object.
public boolean isAbsoluteCenter()Deprecated Indicates that the center shouldn’t grow and should be placed exactly in the center of the layout
public void setAbsoluteCenter(boolean absoluteCenter)Deprecated Indicates that the center shouldn’t grow and should be placed exactly in the center of the layout
public int getCenterBehavior()Defines the behavior of the center component to one of the constants defined in this class
public void setCenterBehavior(int centerBehavior)Defines the behavior of the center component to one of the constants defined in this class
public boolean isOverlapSupported()This method returns true if the Layout allows Components to Overlap.
public boolean isScaleEdges()Stretches the edge components (NORTH/EAST/WEST/SOUTH)
public void setScaleEdges(boolean scaleEdges)Stretches the edge components (NORTH/EAST/WEST/SOUTH)
public boolean isConstraintTracking()If this method returns true, the addLayoutComponent method will be called when replacing a layout for every component within the container
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.
public 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.
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.

Inherited methods

From Layout

cloneConstraint, updateTabIndices

From Object

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

Field details

CENTER_BEHAVIOR_SCALE

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

CENTER_BEHAVIOR_CENTER

public static final int CENTER_BEHAVIOR_CENTER = 1
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.

CENTER_BEHAVIOR_CENTER_ABSOLUTE

public static final int CENTER_BEHAVIOR_CENTER_ABSOLUTE = 2
Defines the behavior of the component placed in the center position of the layout, places the component in the center of the surrounding container

CENTER_BEHAVIOR_TOTAL_BELLOW

public static final int CENTER_BEHAVIOR_TOTAL_BELLOW = 3
Deprecated. Deprecated due to spelling mistake, use CENTER_BEHAVIOR_TOTAL_BELOW
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

CENTER_BEHAVIOR_TOTAL_BELOW

public static final int CENTER_BEHAVIOR_TOTAL_BELOW = 3
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

NORTH

public static final String NORTH = "North"
The north layout constraint (top of container).

SOUTH

public static final String SOUTH = "South"
The south layout constraint (bottom of container).

CENTER

public static final String CENTER = "Center"
The center layout constraint (middle of container)

WEST

public static final String WEST = "West"
The west layout constraint (left of container).

EAST

public static final String EAST = "East"
The east layout constraint (right of container).

OVERLAY

public static final String OVERLAY = "Overlay"
Overlay on top of the other layout components

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 int
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 Component
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 Component
the center component
east Component
component or null to ignore
west Component
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 Component
the center component
east Component
component or null to ignore
west Component
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 Component
the center component
east Component
component or null to ignore
west Component
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 Component
the center component
east Component
component or null to ignore
west Component
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 Component
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 Component
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 Component
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 Component
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 Component
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 Component
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 Component
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

name Object
optional meta data information, like alignment orientation
comp Component
the added component to the layout
c Container
the parent container

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 Component
the removed component from layout

getComponentConstraint

public Object getComponentConstraint(Component comp)
Returns the component constraint

Parameters

comp Component
the component whose constraint is queried

Returns

one of the constraints defined in this class

layoutContainer

public void layoutContainer(Container target)
Layout the given parent container children

Parameters

target Container
the given parent container

getPreferredSize

public Dimension getPreferredSize(Container parent)
Returns the container preferred size

Parameters

parent Container
the parent container

Returns

the container preferred size

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()
Returns a string representation of the object. In general, the toString method returns a string that “textually represents” this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method. The toString method for class Object returns a string consisting of the name of the class of which the object is an instance, the at-sign character `@’, and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of: getClass().getName() + ‘@’ + Integer.toHexString(hashCode())

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 String
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 String
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 String
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)
Indicates whether some other object is “equal to” this one. The equals method implements an equivalence relation: It is reflexive: for any reference value x, x.equals(x) should return true. It is symmetric: for any reference values x and y, x.equals(y) should return true if and only if y.equals(x) returns true. It is transitive: for any reference values x, y, and z, if x.equals(y) returns true and y.equals(z) returns true, then x.equals(z) should return true. It is consistent: for any reference values x and y, multiple invocations of x.equals(y) consistently return true or consistently return false, provided no information used in equals comparisons on the object is modified. For any non-null reference value x, x.equals(null) should return false. The equals method for class Object implements the most discriminating possible equivalence relation on objects; that is, for any reference values x and y, this method returns true if and only if x and y refer to the same object (x==y has the value true).

hashCode

public int hashCode()
Returns a hash code value for the object. This method is supported for the benefit of hashtables such as those provided by java.util.Hashtable. The general contract of hashCode is: Whenever it is invoked on the same object more than once during an execution of a Java application, the hashCode method must consistently return the same integer, provided no information used in equals comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application. If two objects are equal according to the equals(Object) method, then calling the hashCode method on each of the two objects must produce the same integer result. It is not required that if two objects are unequal according to the equals(java.lang.Object) method, then calling the hashCode method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hashtables. As much as is reasonably practical, the hashCode method defined by class Object does return distinct integers for distinct objects. (This is typically implemented by converting the internal address of the object into an integer, but this implementation technique is not required by the JavaTM programming language.)

isAbsoluteCenter

public boolean isAbsoluteCenter()
Deprecated. use center behavior instead
Indicates that the center shouldn’t grow and should be placed exactly in the center of the layout

Returns

the absoluteCenter

setAbsoluteCenter

public void setAbsoluteCenter(boolean absoluteCenter)
Deprecated. use center behavior instead
Indicates that the center shouldn’t grow and should be placed exactly in the center of the layout

Parameters

absoluteCenter boolean
the absoluteCenter to set

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 int
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

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 boolean
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

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 Container
parent container

Returns

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

overridesTabIndices

public 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.

Parameters

parent Container
The parent component.

Returns

True if this layout overrides tab traversal order.

getChildrenInTraversalOrder

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.

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.

Returns

Array of Components in the order