public class GroupLayout

  1. Object
  2. Layout
  3. GroupLayout

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 = new Container();
  Label label1 = new Label("First Name");
  Label label2 = new Label("Last Name");
  TextField tf1 = new TextField();
  TextField tf2 = new TextField();
  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 types

class GroupLayout.GroupGroup 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.SequentialGroupA Group that lays out its elements sequentially, one after another.
class GroupLayout.ParallelGroupA Group that lays out its elements on top of each other.

Fields

public static final int NORTH = 1Compass-direction North (up).
public static final int EAST = 3Compass-direction east (right).
public static final int SOUTH = 5Compass-direction south (down).
public static final int WEST = 7Compass-direction west (left).
public static final int HORIZONTAL = 1Possible argument when linking sizes of components.
public static final int VERTICAL = 2Possible argument when linking sizes of components.
public static final int LEADING = 1Possible alignment type.
public static final int TRAILING = 2Possible alignment type.
public static final int CENTER = 4Possible alignment type.
public static final int BASELINE = 3Possible alignment type.
public static final int DEFAULT_SIZE = -1Possible value for the add methods that takes a Component.
public static final int PREFERRED_SIZE = -2Possible value for the add methods that takes a Component.

Constructors

public GroupLayout(Container host)Creates a GroupLayout for the specified Container.

Methods

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

Inherited methods

From Layout

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

From Object

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

Field details

NORTH

public static final int NORTH = 1
Compass-direction North (up).

EAST

public static final int EAST = 3
Compass-direction east (right).

SOUTH

public static final int SOUTH = 5
Compass-direction south (down).

WEST

public static final int WEST = 7
Compass-direction west (left).

HORIZONTAL

public static final int HORIZONTAL = 1
Possible argument when linking sizes of components. Specifies the the two component should share the same size along the horizontal axis.

See also

VERTICAL

public static final int VERTICAL = 2
Possible argument when linking sizes of components. Specifies the the two component should share the same size along the vertical axis.

See also

LEADING

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

TRAILING

public static final int TRAILING = 2
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

CENTER

public static final int CENTER = 4
Possible alignment type. Indicates the elements should centered in the spaced provided.

See also

BASELINE

public static final int BASELINE = 3
Possible alignment type. Indicates the elements should aligned along their baseline.

See also

DEFAULT_SIZE

public static final int DEFAULT_SIZE = -1
Possible value for the add methods that takes a Component. Indicates the size from the component should be used.

PREFERRED_SIZE

public static final int PREFERRED_SIZE = -2
Possible value for the add methods that takes a Component. Indicates the preferred size should be used.

Constructor details

GroupLayout

public GroupLayout(Container host)
Creates a GroupLayout for the specified Container.

Parameters

host Container
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

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 boolean
whether component visibility is considered when sizing and positioning components

See also

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 Component
the component
honorsVisibility Boolean
whether component’s visibility should be considered for sizing and positioning

Throws

IllegalArgumentException
if component is null

See also

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

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

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

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

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

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 int
alignment for the elements of the Group, one of LEADING, TRAILING, CENTER or BASELINE.

Returns

a new ParallelGroup

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 int
alignment for the elements of the Group, one of LEADING, TRAILING, CENTER or BASELINE.
resizable boolean
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
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 boolean
whether the group is resizable
anchorBaselineToTop boolean
whether the baseline is anchored to the top or bottom of the group

Returns

parallel group

See also

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 Component[]
Components to force to have same size.

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 Component[]
Components to force to have same size.
axis int
Axis to bind size, one of HORIZONTAL, VERTICAL or HORIZONTAL | VERTICAL

Throws

IllegalArgumentException
if components is null, or contains null.
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 Component
the Component that should be removed and replaced with newComponent
newComponent Component
the Component to put in existingComponents place

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 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 Component
the component to be removed

See also

getPreferredSize

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

Parameters

parent Container
the container to return size for

Returns

the container preferred size

Throws

IllegalArgumentException
if parent is not the same Container that this was created with
IllegalStateException
if any of the components added to this layout are not in both a horizontal and vertical group

See also

layoutContainer

public void layoutContainer(Container parent)
Lays out the specified container.

Parameters

parent Container
the container to be laid out

Throws

IllegalStateException
if any of the components added to this layout are not in both a horizontal and vertical group