org.jdesktop.layout

Class GroupLayout

public class GroupLayout extends Object implements LayoutManager2

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:

   JComponent 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:

There are a couple of things to notice in this code: 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
abstract classGroupLayout.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).
classGroupLayout.ParallelGroup
A Group that lays out its elements on top of each other.
classGroupLayout.SequentialGroup
A Group that lays out its elements sequentially, one after another.
Field Summary
static intBASELINE
Possible alignment type.
static intCENTER
Possible alignment type.
static intDEFAULT_SIZE
Possible value for the add methods that takes a Component.
static intHORIZONTAL
Possible argument when linking sizes of components.
static intLEADING
Possible alignment type.
static intPREFERRED_SIZE
Possible value for the add methods that takes a Component.
static intTRAILING
Possible alignment type.
static intVERTICAL
Possible argument when linking sizes of components.
Constructor Summary
GroupLayout(Container host)
Creates a GroupLayout for the specified JComponent.
Method Summary
voidaddLayoutComponent(String name, Component component)
Notification that a Component has been added to the parent container.
voidaddLayoutComponent(Component component, Object constraints)
Notification that a Component has been added to the parent container.
GroupLayout.ParallelGroupcreateBaselineGroup(boolean resizable, boolean anchorBaselineToTop)
Creates and returns a ParallelGroup that aligns it's elements along the baseline.
GroupLayout.ParallelGroupcreateParallelGroup()
Creates and returns a ParallelGroup with a LEADING alignment.
GroupLayout.ParallelGroupcreateParallelGroup(int alignment)
Creates and returns an ParallelGroup.
GroupLayout.ParallelGroupcreateParallelGroup(int alignment, boolean resizable)
Creates and returns an ParallelGroup.
GroupLayout.SequentialGroupcreateSequentialGroup()
Creates and returns a SequentialGroup.
booleangetAutocreateContainerGaps()
Returns whether or not gaps between the container and the first/last components should automatically be created.
booleangetAutocreateGaps()
Returns true if gaps between components are automatically be created.
booleangetHonorsVisibility()
Returns whether component visiblity is considered when sizing and positioning components.
GroupLayout.GroupgetHorizontalGroup()
Returns the Group that is responsible for layout along the horizontal axis.
floatgetLayoutAlignmentX(Container parent)
Returns the alignment along the x axis.
floatgetLayoutAlignmentY(Container parent)
Returns the alignment along the y axis.
LayoutStylegetLayoutStyle()
Returns the LayoutStyle instance to use
GroupLayout.GroupgetVerticalGroup()
Returns the ParallelGroup that is responsible for layout along the vertical axis.
voidinvalidateLayout(Container parent)
Invalidates the layout, indicating that if the layout manager has cached information it should be discarded.
voidlayoutContainer(Container parent)
Lays out the specified container.
voidlinkSize(Component[] components)
Forces the set of components to have the same size.
voidlinkSize(Component[] components, int axis)
Forces the set of components to have the same size.
DimensionmaximumLayoutSize(Container parent)
Returns the maximum size for the specified container.
DimensionminimumLayoutSize(Container parent)
Returns the minimum size for the specified container.
DimensionpreferredLayoutSize(Container parent)
Returns the preferred size for the specified container.
voidremoveLayoutComponent(Component component)
Notification that a Component has been removed from the parent container.
voidreplace(Component existingComponent, Component newComponent)
Removes an existing component replacing it with the specified component.
voidsetAutocreateContainerGaps(boolean autocreatePadding)
Sets whether or not gaps between the container and the first/last components should automatically be created.
voidsetAutocreateGaps(boolean autocreatePadding)
Sets whether or not a gap between components should automatically be created.
voidsetHonorsVisibility(boolean honorsVisibility)
Sets whether component visiblity is considered when sizing and positioning components.
voidsetHonorsVisibility(Component component, Boolean honorsVisibility)
Sets whether the component's visiblity is considered for sizing and positioning.
voidsetHorizontalGroup(GroupLayout.Group group)
Sets the Group that is responsible for layout along the horizontal axis.
voidsetLayoutStyle(LayoutStyle layoutStyle)
Sets the LayoutStyle this GroupLayout is to use.
voidsetVerticalGroup(GroupLayout.Group group)
Sets the Group that is responsible for layout along the vertical axis.
StringtoString()
Returns a textual description of this GroupLayout.

Field Detail

BASELINE

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

See Also: GroupLayout

CENTER

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

See Also: GroupLayout

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.

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: (java.awt.Component[],int)

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

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.

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

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: (java.awt.Component[],int)

Constructor Detail

GroupLayout

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

Parameters: host the Container to layout

Throws: IllegalArgumentException if host is null

Method Detail

addLayoutComponent

public void addLayoutComponent(String name, Component component)
Notification that a Component has been added to the parent container. Developers should not invoke this method directly, instead you should use one of the Group methods to add a Component.

Parameters: name the string to be associated with the component component the Component to be added

addLayoutComponent

public void addLayoutComponent(Component component, Object constraints)
Notification that a Component has been added to the parent container. You should not invoke this method directly, instead you should use one of the Group methods to add a Component.

Parameters: component The component added constraints Description of where to place the component.

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 whether the baseline is anchored to the top or bottom of the group

See Also: GroupLayout ParallelGroup

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

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

createSequentialGroup

public GroupLayout.SequentialGroup createSequentialGroup()
Creates and returns a SequentialGroup.

Returns: a new SequentialGroup

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

getAutocreateGaps

public boolean getAutocreateGaps()
Returns true if gaps between components are automatically be created.

Returns: true if gaps between components should automatically be created

getHonorsVisibility

public boolean getHonorsVisibility()
Returns whether component visiblity is considered when sizing and positioning components.

Returns: whether component visiblity is considered when sizing and positioning 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.

getLayoutAlignmentX

public float getLayoutAlignmentX(Container parent)
Returns the alignment along the x axis. This specifies how the component would like to be aligned relative to other components. The value should be a number between 0 and 1 where 0 represents alignment along the origin, 1 is aligned the furthest away from the origin, 0.5 is centered, etc.

Parameters: parent Container hosting this LayoutManager

Returns: alignment

Throws: IllegalArgumentException if parent is not the same Container that this was created with

getLayoutAlignmentY

public float getLayoutAlignmentY(Container parent)
Returns the alignment along the y axis. This specifies how the component would like to be aligned relative to other components. The value should be a number between 0 and 1 where 0 represents alignment along the origin, 1 is aligned the furthest away from the origin, 0.5 is centered, etc.

Parameters: parent Container hosting this LayoutManager

Returns: alignment

Throws: IllegalArgumentException if parent is not the same Container that this was created with

getLayoutStyle

public LayoutStyle getLayoutStyle()
Returns the LayoutStyle instance to use

Returns: the LayoutStyle instance to use

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.

invalidateLayout

public void invalidateLayout(Container parent)
Invalidates the layout, indicating that if the layout manager has cached information it should be discarded.

Parameters: parent Container hosting this LayoutManager

Throws: IllegalArgumentException if parent is not the same Container that this was created with

layoutContainer

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

Parameters: parent 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

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

maximumLayoutSize

public Dimension maximumLayoutSize(Container parent)
Returns the maximum size for the specified container.

Parameters: parent the container to return size for

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: java.awt.Container#getMaximumSize

minimumLayoutSize

public Dimension minimumLayoutSize(Container parent)
Returns the minimum size for the specified container.

Parameters: parent the container to return size for

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: java.awt.Container#getMinimumSize

preferredLayoutSize

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

Parameters: parent the container to return size for

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: java.awt.Container#getPreferredSize

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 remove on the parent Container.

Parameters: component the component to be removed

See Also: java.awt.Component#remove

replace

public void replace(Component existingComponent, Component newComponent)
Removes an existing component replacing it with the specified component.

Parameters: existingComponent the Component that should be removed and replaced with newComponent newComponent 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

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 whether or not to automatically create gaps between the container and first/last components.

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 whether or not to automatically created a gap between components and the container

setHonorsVisibility

public void setHonorsVisibility(boolean honorsVisibility)
Sets whether component visiblity 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 whether component visiblity is considered when sizing and positioning components

See Also: setHonorsVisibility

setHonorsVisibility

public void setHonorsVisibility(Component component, Boolean honorsVisibility)
Sets whether the component's visiblity 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 whether component's visiblity should be considered for sizing and positioning

Throws: IllegalArgumentException if component is null

See Also: GroupLayout

setHorizontalGroup

public void setHorizontalGroup(GroupLayout.Group group)
Sets the Group that is responsible for layout along the horizontal axis.

Parameters: group Group responsible for layout along the horizontal axis

Throws: IllegalArgumentException if group is null

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

setVerticalGroup

public void setVerticalGroup(GroupLayout.Group group)
Sets the Group that is responsible for layout along the vertical axis.

Parameters: group Group responsible for layout along the vertical axis.

Throws: IllegalArgumentException if group is null.

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