# 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)`
  Indicates whether some other object is "equal to" this one.
  `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()`
  Returns a hash code value for the object.
  `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()`
  Returns a string representation of the object.
  `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, 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:
      - Constant Field Values

  - ### 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:
      - Constant Field Values

  - ### 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:
      - Constant Field Values

  - ### 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:
      - Constant Field Values

  - ### 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:
      - Constant Field Values

  - ### NORTH

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

  - ### SOUTH

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

  - ### CENTER

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

  - ### WEST

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

  - ### EAST

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

  - ### OVERLAY

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

- ## 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()
    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())
    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)
    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).
    Overrides:
      `equals` in class `Layout`

  - ### hashCode

    public int hashCode()
    Description copied from class: `Layout`
    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.)
    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`