# Class GroupLayout

java.lang.Object
com.codename1.ui.layouts.Layout
com.codename1.ui.layouts.GroupLayout

public class GroupLayout extends Layout

GroupLayout is a LayoutManager that hierarchically groups components to achieve common, and not so common, layouts. Grouping is done by instances of the Group class. GroupLayout supports two types of groups:

Sequential:A sequential group positions its child elements sequentially, one after another. Parallel:A parallel group positions its child elements in the same space on top of each other. Parallel groups can also align the child elements along their baseline.

Each Group can contain any number of child groups, Components or gaps. GroupLayout treats each axis independently. That is, there is a group representing the horizontal axis, and a separate group representing the vertical axis. The horizontal group is responsible for setting the x and width of its contents, where as the vertical group is responsible for setting the y and height of its contents.

The following code builds a simple layout consisting of two labels in one column, followed by two textfields in the next column:

      Container panel = ...;
      GroupLayout layout = new GroupLayout(panel);
      panel.setLayout(layout);
      layout.setAutocreateGaps(true);
      layout.setAutocreateContainerGaps(true);
      GroupLayout.SequentialGroup hGroup = layout.createSequentialGroup();
      hGroup.add(layout.createParallelGroup().add(label1).add(label2)).
             add(layout.createParallelGroup().add(tf1).add(tf2));
      layout.setHorizontalGroup(hGroup);
      GroupLayout.SequentialGroup vGroup = layout.createSequentialGroup();
      vGroup.add(layout.createParallelGroup(GroupLayout.BASELINE).add(label1).add(tf1)).
             add(layout.createParallelGroup(GroupLayout.BASELINE).add(label2).add(tf2));
      layout.setVerticalGroup(vGroup);

This layout consists of the following:

- The horizontal axis consists of a sequential group containing two parallel groups. The first parallel group consists of the labels, with the second parallel group consisting of the text fields.

- The vertical axis similarly consists of a sequential group containing two parallel groups. The parallel groups align their contents along the baseline. The first parallel group consists of the first label and text field, and the second group consists of the second label and text field.

There are a couple of things to notice in this code:

- You need not explicitly add the components to the container, this is indirectly done by using one of the `add` methods.

- The various `add` methods of `Groups` return themselves. This allows for easy chaining of invocations. For example, `group.add(label1).add(label2);` is equivalent to `group.add(label1);group.add(label2);`.

- There are no public constructors for the Groups, instead use the create methods of `GroupLayout`.

GroupLayout offer the ability to automatically insert the appropriate gap between components. This can be turned on using the `setAutocreateGaps()` method. Similarly you can use the `setAutocreateContainerGaps()` method to insert gaps between the components and the container.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `class`
  `GroupLayout.Group`
  Group provides for commonality between the two types of operations supported by `GroupLayout`: laying out components one after another (`SequentialGroup`) or layout on top of each other (`ParallelGroup`).
  `class`
  `GroupLayout.ParallelGroup`
  A `Group` that lays out its elements on top of each other.
  `class`
  `GroupLayout.SequentialGroup`
  A `Group` that lays out its elements sequentially, one after another.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `BASELINE`
  Possible alignment type.
  `static final int`
  `CENTER`
  Possible alignment type.
  `static final int`
  `DEFAULT_SIZE`
  Possible value for the add methods that takes a Component.
  `static final int`
  `EAST`
  Compass-direction east (right).
  `static final int`
  `HORIZONTAL`
  Possible argument when linking sizes of components.
  `static final int`
  `LEADING`
  Possible alignment type.
  `static final int`
  `NORTH`
  Compass-direction North (up).
  `static final int`
  `PREFERRED_SIZE`
  Possible value for the add methods that takes a Component.
  `static final int`
  `SOUTH`
  Compass-direction south (down).
  `static final int`
  `TRAILING`
  Possible alignment type.
  `static final int`
  `VERTICAL`
  Possible argument when linking sizes of components.
  `static final int`
  `WEST`
  Compass-direction west (left).

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `GroupLayout(Container host)`
  Creates a GroupLayout for the specified Container.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `GroupLayout.ParallelGroup`
  `createBaselineGroup(boolean resizable, boolean anchorBaselineToTop)`
  Creates and returns a `ParallelGroup` that aligns it's elements along the baseline.
  `GroupLayout.ParallelGroup`
  `createParallelGroup()`
  Creates and returns a `ParallelGroup` with a `LEADING` alignment.
  `GroupLayout.ParallelGroup`
  `createParallelGroup(int alignment)`
  Creates and returns an `ParallelGroup`.
  `GroupLayout.ParallelGroup`
  `createParallelGroup(int alignment, boolean resizable)`
  Creates and returns an `ParallelGroup`.
  `GroupLayout.SequentialGroup`
  `createSequentialGroup()`
  Creates and returns a `SequentialGroup`.
  `boolean`
  `getAutocreateContainerGaps()`
  Returns whether or not gaps between the container and the first/last components should automatically be created.
  `boolean`
  `getAutocreateGaps()`
  Returns true if gaps between components are automatically be created.
  `boolean`
  `getHonorsVisibility()`
  Returns whether component visibility is considered when sizing and positioning components.
  `GroupLayout.Group`
  `getHorizontalGroup()`
  Returns the `Group` that is responsible for layout along the horizontal axis.
  `LayoutStyle`
  `getLayoutStyle()`
  Returns the LayoutStyle instance to use
  `Dimension`
  `getPreferredSize(Container parent)`
  Returns the preferred size for the specified container.
  `GroupLayout.Group`
  `getVerticalGroup()`
  Returns the `ParallelGroup` that is responsible for layout along the vertical axis.
  `void`
  `layoutContainer(Container parent)`
  Lays out the specified container.
  `void`
  `linkSize(Component[] components)`
  Forces the set of components to have the same size.
  `void`
  `linkSize(Component[] components, int axis)`
  Forces the set of components to have the same size.
  `void`
  `removeLayoutComponent(Component component)`
  Notification that a `Component` has been removed from the parent container.
  `void`
  `replace(Component existingComponent, Component newComponent)`
  Removes an existing component replacing it with the specified component.
  `void`
  `setAutocreateContainerGaps(boolean autocreatePadding)`
  Sets whether or not gaps between the container and the first/last components should automatically be created.
  `void`
  `setAutocreateGaps(boolean autocreatePadding)`
  Sets whether or not a gap between components should automatically be created.
  `void`
  `setHonorsVisibility(boolean honorsVisibility)`
  Sets whether component visibility is considered when sizing and positioning components.
  `void`
  `setHonorsVisibility(Component component, Boolean honorsVisibility)`
  Sets whether the component's visibility is considered for sizing and positioning.
  `void`
  `setHorizontalGroup(GroupLayout.Group group)`
  Sets the `Group` that is responsible for layout along the horizontal axis.
  `void`
  `setLayoutStyle(LayoutStyle layoutStyle)`
  Sets the LayoutStyle this GroupLayout is to use.
  `void`
  `setVerticalGroup(GroupLayout.Group group)`
  Sets the `Group` that is responsible for layout along the vertical axis.
  `String`
  `toString()`
  Returns a textual description of this GroupLayout.

  ### Methods inherited from class Layout

  `addLayoutComponent, cloneConstraint, equals, getChildrenInTraversalOrder, getComponentConstraint, hashCode, isConstraintTracking, isOverlapSupported, obscuresPotential, overridesTabIndices, updateTabIndices`

  ### Methods inherited from class Object

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

- ## Field Details

  - ### NORTH

    public static final int NORTH
    Compass-direction North (up).
    See Also:
      - Constant Field Values

  - ### EAST

    public static final int EAST
    Compass-direction east (right).
    See Also:
      - Constant Field Values

  - ### SOUTH

    public static final int SOUTH
    Compass-direction south (down).
    See Also:
      - Constant Field Values

  - ### WEST

    public static final int WEST
    Compass-direction west (left).
    See Also:
      - Constant Field Values

  - ### HORIZONTAL

    public static final int HORIZONTAL

    Possible argument when linking sizes of components. Specifies the the two component should share the same size along the horizontal axis.

    ###### See also

    - #linkSize(Component[], int)
    See Also:
      - Constant Field Values

  - ### VERTICAL

    public static final int VERTICAL

    Possible argument when linking sizes of components. Specifies the the two component should share the same size along the vertical axis.

    ###### See also

    - #linkSize(Component[], int)
    See Also:
      - Constant Field Values

  - ### LEADING

    public static final int LEADING

    Possible alignment type. Indicates the elements should be aligned to the origin. For the horizontal axis with a left to right orientation this means aligned to the left.

    ###### See also

    - #createParallelGroup(int)
    See Also:
      - Constant Field Values

  - ### TRAILING

    public static final int TRAILING

    Possible alignment type. Indicates the elements should be aligned to the end. For the horizontal axis with a left to right orientation this means aligned to the right.

    ###### See also

    - #createParallelGroup(int)
    See Also:
      - Constant Field Values

  - ### CENTER

    public static final int CENTER

    Possible alignment type. Indicates the elements should centered in the spaced provided.

    ###### See also

    - #createParallelGroup(int)
    See Also:
      - Constant Field Values

  - ### BASELINE

    public static final int BASELINE

    Possible alignment type. Indicates the elements should aligned along their baseline.

    ###### See also

    - #createParallelGroup(int)
    See Also:
      - Constant Field Values

  - ### DEFAULT_SIZE

    public static final int DEFAULT_SIZE
    Possible value for the add methods that takes a Component. Indicates the size from the component should be used.
    See Also:
      - Constant Field Values

  - ### PREFERRED_SIZE

    public static final int PREFERRED_SIZE
    Possible value for the add methods that takes a Component. Indicates the preferred size should be used.
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### GroupLayout

    public GroupLayout(Container host)

    Creates a GroupLayout for the specified Container.

    ###### Parameters

    - `host`: the Container to layout

    ###### Throws

    - `IllegalArgumentException`: if host is null

- ## Method Details

  - ### getHonorsVisibility

    public boolean getHonorsVisibility()

    Returns whether component visibility is considered when sizing and positioning components.

    ###### Returns

    Returns:
      whether component visibility is considered when sizing and positioning components

  - ### setHonorsVisibility

    public void setHonorsVisibility(boolean honorsVisibility)

    Sets whether component visibility is considered when sizing and positioning components. A value of `true` indicates that non-visible components should not be treated as part of the layout. A value of `false` indicates that components should be positioned and sized regardless of visibility.

    A value of `false` is useful when the visibility of components is dynamically adjusted and you don't want surrounding components and the sizing to change.

    The specified value is used for components that do not have an explicit visibility specified.

    The default is `true`.

    ###### Parameters

    - `honorsVisibility`: @param honorsVisibility whether component visibility is considered when sizing and positioning components

    ###### See also

    - #setHonorsVisibility(Component, Boolean)

  - ### setHonorsVisibility

    public void setHonorsVisibility(Component component, Boolean honorsVisibility)

    Sets whether the component's visibility is considered for sizing and positioning. A value of `Boolean.TRUE` indicates that if `component` is not visible it should not be treated as part of the layout. A value of `false` indicates that `component` is positioned and sized regardless of it's visibility. A value of `null` indicates the value specified by the single argument method `setHonorsVisibility` should be used.

    If `component` is not a child of the `Container` this `GroupLayout` is managing, it will be added to the `Container`.

    ###### Parameters

    - `component`: the component

    - `honorsVisibility`: @param honorsVisibility whether `component`'s visibility should be considered for sizing and positioning

    ###### Throws

    - `IllegalArgumentException`: if `component` is `null`

    ###### See also

    - #setHonorsVisibility(boolean)

  - ### toString

    public String toString()

    Returns a textual description of this GroupLayout. The return value is intended for debugging purposes only.

    ###### Returns

    textual description of this GroupLayout

    Overrides:
      `toString` in class `Object`

  - ### getAutocreateGaps

    public boolean getAutocreateGaps()

    Returns true if gaps between components are automatically be created.

    ###### Returns

    true if gaps between components should automatically be created

  - ### setAutocreateGaps

    public void setAutocreateGaps(boolean autocreatePadding)

    Sets whether or not a gap between components should automatically be created. For example, if this is true and you add two components to a `SequentialGroup` a gap between the two will automatically be created. The default is false.

    ###### Parameters

    - `autocreatePadding`: @param autocreatePadding whether or not to automatically created a gap between components and the container

  - ### getAutocreateContainerGaps

    public boolean getAutocreateContainerGaps()

    Returns whether or not gaps between the container and the first/last components should automatically be created. The default is false.

    ###### Returns

    Returns:
      whether or not the gaps between the container and the first/last components should automatically be created

  - ### setAutocreateContainerGaps

    public void setAutocreateContainerGaps(boolean autocreatePadding)

    Sets whether or not gaps between the container and the first/last components should automatically be created. The default is false.

    ###### Parameters

    - `autocreatePadding`: @param autocreatePadding whether or not to automatically create gaps between the container and first/last components.

  - ### getHorizontalGroup

    public GroupLayout.Group getHorizontalGroup()

    Returns the `Group` that is responsible for layout along the horizontal axis.

    ###### Returns

    Returns:
      `ParallelGroup` responsible for layout along the horizontal axis.

  - ### setHorizontalGroup

    public void setHorizontalGroup(GroupLayout.Group group)

    Sets the `Group` that is responsible for layout along the horizontal axis.

    ###### Parameters

    - `group`: @param group `Group` responsible for layout along the horizontal axis

    ###### Throws

    - `IllegalArgumentException`: if group is null

  - ### getVerticalGroup

    public GroupLayout.Group getVerticalGroup()

    Returns the `ParallelGroup` that is responsible for layout along the vertical axis.

    ###### Returns

    Returns:
      `ParallelGroup` responsible for layout along the vertical axis.

  - ### setVerticalGroup

    public void setVerticalGroup(GroupLayout.Group group)

    Sets the `Group` that is responsible for layout along the vertical axis.

    ###### Parameters

    - `group`: @param group `Group` responsible for layout along the vertical axis.

    ###### Throws

    - `IllegalArgumentException`: if group is null.

  - ### createSequentialGroup

    public GroupLayout.SequentialGroup createSequentialGroup()

    Creates and returns a `SequentialGroup`.

    ###### Returns

    a new `SequentialGroup`

  - ### createParallelGroup

    public GroupLayout.ParallelGroup createParallelGroup()

    Creates and returns a `ParallelGroup` with a `LEADING` alignment. This is a cover method for the more general `createParallelGroup(int)` method.

    ###### Returns

    a new ParallelGroup

    ###### See also

    - #createParallelGroup(int)

  - ### createParallelGroup

    public GroupLayout.ParallelGroup createParallelGroup(int alignment)

    Creates and returns an `ParallelGroup`. The alignment specifies how children elements should be positioned when the the parallel group is given more space than necessary. For example, if a ParallelGroup with an alignment of TRAILING is given 100 pixels and a child only needs 50 pixels, the child will be positioned at the position 50.

    ###### Parameters

    - `alignment`: @param alignment alignment for the elements of the Group, one of `LEADING`, `TRAILING`, `CENTER` or `BASELINE`.

    ###### Returns

    a new `ParallelGroup`

    ###### Throws

    - `IllegalArgumentException`: @throws IllegalArgumentException if alignment is not one of `LEADING`, `TRAILING`, `CENTER` or `BASELINE`

  - ### createParallelGroup

    public GroupLayout.ParallelGroup createParallelGroup(int alignment, boolean resizable)

    Creates and returns an `ParallelGroup`. The alignment specifies how children elements should be positioned when the the parallel group is given more space than necessary. For example, if a ParallelGroup with an alignment of TRAILING is given 100 pixels and a child only needs 50 pixels, the child will be positioned at the position 50.

    ###### Parameters

    - `alignment`: @param alignment alignment for the elements of the Group, one of `LEADING`, `TRAILING`, `CENTER` or `BASELINE`.

    - `resizable`: @param resizable whether or not the group is resizable. If the group is not resizable the min/max size will be the same as the preferred.

    ###### Returns

    a new `ParallelGroup`

    ###### Throws

    - `IllegalArgumentException`: @throws IllegalArgumentException if alignment is not one of `LEADING`, `TRAILING`, `CENTER` or `BASELINE`

  - ### createBaselineGroup

    public GroupLayout.ParallelGroup createBaselineGroup(boolean resizable, boolean anchorBaselineToTop)

    Creates and returns a `ParallelGroup` that aligns it's elements along the baseline.

    ###### Parameters

    - `resizable`: whether the group is resizable

    - `anchorBaselineToTop`: @param anchorBaselineToTop whether the baseline is anchored to the top or bottom of the group

    ###### Returns

    parallel group

    ###### See also

    - #createBaselineGroup

    - ParallelGroup

  - ### linkSize

    public void linkSize(Component[] components)

    Forces the set of components to have the same size. This can be used multiple times to force any number of components to share the same size.

    Linked Components are not be resizable.

    ###### Parameters

    - `components`: Components to force to have same size.

    ###### Throws

    - `IllegalArgumentException`: @throws IllegalArgumentException if `components` is null, or contains null.

  - ### linkSize

    public void linkSize(Component[] components, int axis)

    Forces the set of components to have the same size. This can be used multiple times to force any number of components to share the same size.

    Linked Components are not be resizable.

    ###### Parameters

    - `components`: Components to force to have same size.

    - `axis`: @param axis Axis to bind size, one of HORIZONTAL, VERTICAL or HORIZONTAL | VERTICAL

    ###### Throws

    - `IllegalArgumentException`: @throws IllegalArgumentException if `components` is null, or contains null.

    - `IllegalArgumentException`: @throws IllegalArgumentException if `axis` does not contain `HORIZONTAL` or `VERTICAL`

  - ### replace

    public void replace(Component existingComponent, Component newComponent)

    Removes an existing component replacing it with the specified component.

    ###### Parameters

    - `existingComponent`: @param existingComponent the Component that should be removed and replaced with newComponent

    - `newComponent`: the Component to put in existingComponents place

    ###### Throws

    - `IllegalArgumentException`: @throws IllegalArgumentException is either of the Components are null or if existingComponent is not being managed by this layout manager

  - ### getLayoutStyle

    public LayoutStyle getLayoutStyle()

    Returns the LayoutStyle instance to use

    ###### Returns

    the LayoutStyle instance to use

  - ### setLayoutStyle

    public void setLayoutStyle(LayoutStyle layoutStyle)

    Sets the LayoutStyle this GroupLayout is to use. A value of null can be used to indicate the shared instance of LayoutStyle should be used.

    ###### Parameters

    - `layoutStyle`: the LayoutStyle to use

  - ### removeLayoutComponent

    public void removeLayoutComponent(Component component)

    Notification that a `Component` has been removed from the parent container. You should not invoke this method directly, instead invoke `removeComponent` on the parent `Container`.

    ###### Parameters

    - `component`: the component to be removed

    ###### See also

    - Container#removeComponent
    Overrides:
      `removeLayoutComponent` in class `Layout`

  - ### getPreferredSize

    public Dimension getPreferredSize(Container parent)

    Returns the preferred size for the specified container.

    ###### Parameters

    - `parent`: the container to return size for

    ###### Throws

    - `IllegalArgumentException`: @throws IllegalArgumentException if `parent` is not the same `Container` that this was created with

    - `IllegalStateException`: @throws IllegalStateException if any of the components added to this layout are not in both a horizontal and vertical group

    ###### See also

    - Container#getPreferredSize
    Specified by:
      `getPreferredSize` in class `Layout`

  - ### layoutContainer

    public void layoutContainer(Container parent)

    Lays out the specified container.

    ###### Parameters

    - `parent`: the container to be laid out

    ###### Throws

    - `IllegalStateException`: @throws IllegalStateException if any of the components added to this layout are not in both a horizontal and vertical group
    Specified by:
      `layoutContainer` in class `Layout`