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:
- 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.
BASELINE
public static final int BASELINE
Possible alignment type. Indicates the elements should aligned along
their baseline.
CENTER
public static final int CENTER
Possible alignment type. Indicates the elements should centered in
the spaced provided.
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.
linkSize(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.
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.
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.
linkSize(java.awt.Component[],int)
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
.
component
- The component addedconstraints
- Description of where to place the component.
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
.
name
- the string to be associated with the componentcomponent
- the Component
to be added
createBaselineGroup
public GroupLayout.ParallelGroup createBaselineGroup(boolean resizable,
boolean anchorBaselineToTop)
Creates and returns a ParallelGroup
that aligns it's
elements along the baseline.
resizable
- whether the group is resizableanchorBaselineToTop
- whether the baseline is anchored to
the top or bottom of the group
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.
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.
alignment
- alignment for the elements of the Group, 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.
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.
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.
- 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.
- true if gaps between components should automatically be created
getHonorsVisibility
public boolean getHonorsVisibility()
Returns whether component visiblity is considered when sizing and
positioning components.
- 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.
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.
parent
- Container hosting this LayoutManager
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.
parent
- Container hosting this LayoutManager
getLayoutStyle
public LayoutStyle getLayoutStyle()
Returns the LayoutStyle instance to use
- the LayoutStyle instance to use
getVerticalGroup
public GroupLayout.Group getVerticalGroup()
Returns the ParallelGroup
that is responsible for
layout along the vertical axis.
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.
parent
- Container hosting this LayoutManager
layoutContainer
public void layoutContainer(Container parent)
Lays out the specified container.
parent
- the container to be laid out
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.
components
- Components to force to have same size.
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.
components
- Components to force to have same size.axis
- Axis to bind size, one of HORIZONTAL, VERTICAL or
HORIZONTAL | VERTICAL
maximumLayoutSize
public Dimension maximumLayoutSize(Container parent)
Returns the maximum size for the specified container.
parent
- the container to return size for
java.awt.Container.getMaximumSize
minimumLayoutSize
public Dimension minimumLayoutSize(Container parent)
Returns the minimum size for the specified container.
parent
- the container to return size for
java.awt.Container.getMinimumSize
preferredLayoutSize
public Dimension preferredLayoutSize(Container parent)
Returns the preferred size for the specified container.
parent
- the container to return size for
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
.
component
- the component to be removed
java.awt.Component.remove
replace
public void replace(Component existingComponent,
Component newComponent)
Removes an existing component replacing it with the specified component.
existingComponent
- the Component that should be removed and
replaced with newComponentnewComponent
- the Component to put in existingComponents place
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.
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.
autocreatePadding
- whether or not to automatically created a gap
between components and the container
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
.
component
- the componenthonorsVisibility
- whether component
's visiblity should be
considered for sizing and positioning
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
.
honorsVisibility
- whether component visiblity is considered when
sizing and positioning components
setHorizontalGroup
public void setHorizontalGroup(GroupLayout.Group group)
Sets the Group
that is responsible for
layout along the horizontal axis.
group
- Group
responsible for layout along
the horizontal axis
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.
layoutStyle
- the LayoutStyle to use
setVerticalGroup
public void setVerticalGroup(GroupLayout.Group group)
Sets the Group
that is responsible for
layout along the vertical axis.
group
- Group
responsible for layout along
the vertical axis.
toString
public String toString()
Returns a textual description of this GroupLayout. The return value
is intended for debugging purposes only.
- textual description of this GroupLayout