LayoutManager
, LayoutManager2
public class GroupLayout extends Object implements LayoutManager2
GroupLayout
is a LayoutManager
that hierarchically groups components in order to position them in a Container
. GroupLayout
is intended for use by builders, but may be hand-coded as well. Grouping is done by instances of the Group
class.
GroupLayout
supports two types of groups. A sequential group positions its child elements sequentially, one after another. A parallel group aligns its child elements in one of four ways. Each group may contain any number of elements, where an element is a Group
, Component
, or gap. A gap can be thought of as an invisible component with a minimum, preferred and maximum size. In addition GroupLayout
supports a preferred gap, whose value comes from LayoutStyle
.
Elements are similar to a spring. Each element has a range as specified by a minimum, preferred and maximum. Gaps have either a developer-specified range, or a range determined by
LayoutStyle
. The range for Component
s is determined from the Component
's getMinimumSize
,
getPreferredSize
and getMaximumSize
methods. In addition, when adding Component
s you may specify a particular range to use instead of that from the component. The range for a
Group
is determined by the type of group. A ParallelGroup
's range is the maximum of the ranges of its elements. A
SequentialGroup
's range is the sum of the ranges of its elements.
GroupLayout
treats each axis independently. That is, there is a group representing the horizontal axis, and a group representing the vertical axis. The horizontal group is responsible for determining the minimum, preferred and maximum size along the horizontal axis as well as setting the x and width of the components contained in it. The vertical group is responsible for determining the minimum, preferred and maximum size along the vertical axis as well as setting the y and height of the components contained in it. Each Component
must exist in both a horizontal and vertical group, otherwise an IllegalStateException
is thrown during layout, or when the minimum, preferred or maximum size is requested.
The following diagram shows a sequential group along the horizontal axis. The sequential group contains three components. A parallel group was used along the vertical axis.
To reinforce that each axis is treated independently the diagram shows the range of each group and element along each axis. The range of each component has been projected onto the axes, and the groups are rendered in blue (horizontal) and red (vertical). For readability there is a gap between each of the elements in the sequential group.
The sequential group along the horizontal axis is rendered as a solid blue line. Notice the sequential group is the sum of the children elements it contains.
Along the vertical axis the parallel group is the maximum of the height of each of the components. As all three components have the same height, the parallel group has the same height.
The following diagram shows the same three components, but with the parallel group along the horizontal axis and the sequential group along the vertical axis.
As c1
is the largest of the three components, the parallel group is sized to c1
. As c2
and c3
are smaller than c1
they are aligned based on the alignment specified for the component (if specified) or the default alignment of the parallel group. In the diagram c2
and c3
were created with an alignment of LEADING
. If the component orientation were right-to-left then c2
and c3
would be positioned on the opposite side.
The following diagram shows a sequential group along both the horizontal and vertical axis.
GroupLayout
provides the ability to insert gaps between Component
s. The size of the gap is determined by an instance of LayoutStyle
. This may be turned on using the setAutoCreateGaps
method. Similarly, you may use the setAutoCreateContainerGaps
method to insert gaps between components that touch the edge of the parent container and the container.
The following builds a panel 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); // Turn on automatically adding gaps between components layout.setAutoCreateGaps(true); // Turn on automatically creating gaps between components that touch // the edge of the container and the container. layout.setAutoCreateContainerGaps(true); // Create a sequential group for the horizontal axis. GroupLayout.SequentialGroup hGroup = layout.createSequentialGroup(); // The sequential group in turn contains two parallel groups. // One parallel group contains the labels, the other the text fields. // Putting the labels in a parallel group along the horizontal axis // positions them at the same x location. // // Variable indentation is used to reinforce the level of grouping. hGroup.addGroup(layout.createParallelGroup(). addComponent(label1).addComponent(label2)); hGroup.addGroup(layout.createParallelGroup(). addComponent(tf1).addComponent(tf2)); layout.setHorizontalGroup(hGroup); // Create a sequential group for the vertical axis. GroupLayout.SequentialGroup vGroup = layout.createSequentialGroup(); // The sequential group contains two parallel groups that align // the contents along the baseline. The first parallel group contains // the first label and text field, and the second parallel group contains // the second label and text field. By using a sequential group // the labels and text fields are positioned vertically after one another. vGroup.addGroup(layout.createParallelGroup(Alignment.BASELINE). addComponent(label1).addComponent(tf1)); vGroup.addGroup(layout.createParallelGroup(Alignment.BASELINE). addComponent(label2).addComponent(tf2)); layout.setVerticalGroup(vGroup);
When run the following is produced.
This layout consists of the following.
add
methods of Group
. add
methods return the caller. This allows for easy chaining of invocations. For example, group.addComponent(label1).addComponent(label2);
is equivalent to group.addComponent(label1); group.addComponent(label2);
. Group
s; instead use the create methods of GroupLayout
. Modifier and Type | Class | Description |
---|---|---|
static enum |
GroupLayout.Alignment |
Enumeration of the possible ways ParallelGroup can align its children. |
class |
GroupLayout.Group |
Group provides the basis for the two types of operations supported by GroupLayout : laying out components one after another (SequentialGroup ) or aligned (ParallelGroup ). |
class |
GroupLayout.ParallelGroup |
A Group that aligns and sizes its children. |
final class |
GroupLayout.SequentialGroup |
A Group that positions and sizes its elements sequentially, one after another. |
Modifier and Type | Field | Description |
---|---|---|
static final int |
DEFAULT_SIZE |
Indicates the size from the component or gap should be used for a particular range value. |
static final int |
PREFERRED_SIZE |
Indicates the preferred size from the component or gap should be used for a particular range value. |
Constructor | Description |
---|---|
GroupLayout |
Creates a GroupLayout for the specified Container . |
Modifier and Type | Method | Description |
---|---|---|
void |
addLayoutComponent |
Notification that a Component has been added to the parent container. |
void |
addLayoutComponent |
Notification that a Component has been added to the parent container. |
GroupLayout.ParallelGroup |
createBaselineGroup |
Creates and returns a ParallelGroup that aligns its elements along the baseline. |
GroupLayout.ParallelGroup |
createParallelGroup() |
Creates and returns a ParallelGroup with an alignment of Alignment.LEADING . |
GroupLayout.ParallelGroup |
createParallelGroup |
Creates and returns a ParallelGroup with the specified alignment. |
GroupLayout.ParallelGroup |
createParallelGroup |
Creates and returns a ParallelGroup with the specified alignment and resize behavior. |
GroupLayout.SequentialGroup |
createSequentialGroup() |
Creates and returns a SequentialGroup . |
boolean |
getAutoCreateContainerGaps() |
Returns true if gaps between the container and components that border the container are automatically created. |
boolean |
getAutoCreateGaps() |
Returns true if gaps between components are automatically created. |
boolean |
getHonorsVisibility() |
Returns whether component visibility is considered when sizing and positioning components. |
float |
getLayoutAlignmentX |
Returns the alignment along the x axis. |
float |
getLayoutAlignmentY |
Returns the alignment along the y axis. |
LayoutStyle |
getLayoutStyle() |
Returns the LayoutStyle used for calculating the preferred gap between components. |
void |
invalidateLayout |
Invalidates the layout, indicating that if the layout manager has cached information it should be discarded. |
void |
layoutContainer |
Lays out the specified container. |
void |
linkSize |
Forces the specified components to have the same size along the specified axis regardless of their preferred, minimum or maximum sizes. |
void |
linkSize |
Forces the specified components to have the same size regardless of their preferred, minimum or maximum sizes. |
Dimension |
maximumLayoutSize |
Returns the maximum size for the specified container. |
Dimension |
minimumLayoutSize |
Returns the minimum size for the specified container. |
Dimension |
preferredLayoutSize |
Returns the preferred size for the specified container. |
void |
removeLayoutComponent |
Notification that a Component has been removed from the parent container. |
void |
replace |
Replaces an existing component with a new one. |
void |
setAutoCreateContainerGaps |
Sets whether a gap between the container and components that touch the border of the container should automatically be created. |
void |
setAutoCreateGaps |
Sets whether a gap between components should automatically be created. |
void |
setHonorsVisibility |
Sets whether component visibility is considered when sizing and positioning components. |
void |
setHonorsVisibility |
Sets whether the component's visibility is considered for sizing and positioning. |
void |
setHorizontalGroup |
Sets the Group that positions and sizes components along the horizontal axis. |
void |
setLayoutStyle |
Sets the LayoutStyle used to calculate the preferred gaps between components. |
void |
setVerticalGroup |
Sets the Group that positions and sizes components along the vertical axis. |
String |
toString() |
Returns a string representation of this GroupLayout . |
public static final int DEFAULT_SIZE
public static final int PREFERRED_SIZE
public GroupLayout(Container host)
GroupLayout
for the specified Container
.host
- the Container
the GroupLayout
is the LayoutManager
forIllegalArgumentException
- if host is null
public void setHonorsVisibility(boolean honorsVisibility)
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 visibility is considered when sizing and positioning componentspublic boolean getHonorsVisibility()
public void setHonorsVisibility(Component component, Boolean honorsVisibility)
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 its 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 visibility of this component
should be considered for sizing and positioningIllegalArgumentException
- if component
is null
public void setAutoCreateGaps(boolean autoCreatePadding)
true
and you add two components to a SequentialGroup
a gap between the two components is automatically be created. The default is false
.autoCreatePadding
- whether a gap between components is automatically createdpublic boolean getAutoCreateGaps()
true
if gaps between components are automatically created.true
if gaps between components are automatically createdpublic void setAutoCreateContainerGaps(boolean autoCreateContainerPadding)
false
.autoCreateContainerPadding
- whether a gap between the container and components that touch the border of the container should automatically be createdpublic boolean getAutoCreateContainerGaps()
true
if gaps between the container and components that border the container are automatically created.true
if gaps between the container and components that border the container are automatically createdpublic void setHorizontalGroup(GroupLayout.Group group)
Group
that positions and sizes components along the horizontal axis.group
- the Group
that positions and sizes components along the horizontal axisIllegalArgumentException
- if group is null
public void setVerticalGroup(GroupLayout.Group group)
Group
that positions and sizes components along the vertical axis.group
- the Group
that positions and sizes components along the vertical axisIllegalArgumentException
- if group is null
public GroupLayout.SequentialGroup createSequentialGroup()
SequentialGroup
.SequentialGroup
public GroupLayout.ParallelGroup createParallelGroup()
ParallelGroup
with an alignment of Alignment.LEADING
. This is a cover method for the more general createParallelGroup(Alignment)
method.ParallelGroup
public GroupLayout.ParallelGroup createParallelGroup(GroupLayout.Alignment alignment)
ParallelGroup
with the specified alignment. This is a cover method for the more general
createParallelGroup(Alignment,boolean)
method with true
supplied for the second argument.alignment
- the alignment for the elements of the groupParallelGroup
IllegalArgumentException
- if alignment
is null
public GroupLayout.ParallelGroup createParallelGroup(GroupLayout.Alignment alignment, boolean resizable)
ParallelGroup
with the specified alignment and resize behavior. The
alignment
argument specifies how children elements are positioned that do not fill the group. For example, if a
ParallelGroup
with an alignment of TRAILING
is given 100 and a child only needs 50, the child is positioned at the position 50 (with a component orientation of left-to-right). Baseline alignment is only useful when used along the vertical axis. A ParallelGroup
created with a baseline alignment along the horizontal axis is treated as LEADING
.
Refer to ParallelGroup
for details on the behavior of baseline groups.
alignment
- the alignment for the elements of the groupresizable
- true
if the group is resizable; if the group is not resizable the preferred size is used for the minimum and maximum size of the groupParallelGroup
IllegalArgumentException
- if alignment
is null
public GroupLayout.ParallelGroup createBaselineGroup(boolean resizable, boolean anchorBaselineToTop)
ParallelGroup
that aligns its elements along the baseline.resizable
- whether the group is resizableanchorBaselineToTop
- whether the baseline is anchored to the top or bottom of the groupParallelGroup
public void linkSize(Component... components)
This can be used multiple times to force any number of components to share the same size.
Linked Components are not be resizable.
components
- the Component
s that are to have the same sizeIllegalArgumentException
- if components
is null
, or contains null
public void linkSize(int axis, Component... components)
This can be used multiple times to force any number of components to share the same size.
Linked Component
s are not be resizable.
axis
- the axis to link the size along; one of SwingConstants.HORIZONTAL
or SwingConstants.VERTICAL
components
- the Component
s that are to have the same sizeIllegalArgumentException
- if components
is null
, or contains null
; or axis
is not SwingConstants.HORIZONTAL
or SwingConstants.VERTICAL
public void replace(Component existingComponent, Component newComponent)
existingComponent
- the component that should be removed and replaced with newComponent
newComponent
- the component to put in existingComponent
's placeIllegalArgumentException
- if either of the components are null
or existingComponent
is not being managed by this layout managerpublic void setLayoutStyle(LayoutStyle layoutStyle)
LayoutStyle
used to calculate the preferred gaps between components. A value of null
indicates the shared instance of LayoutStyle
should be used.layoutStyle
- the LayoutStyle
to usepublic LayoutStyle getLayoutStyle()
LayoutStyle
used for calculating the preferred gap between components. This returns the value specified to setLayoutStyle
, which may be null
.LayoutStyle
used for calculating the preferred gap between componentspublic void addLayoutComponent(String name, Component component)
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
.addLayoutComponent
in interface LayoutManager
name
- the string to be associated with the componentcomponent
- the Component
to be addedpublic void removeLayoutComponent(Component component)
Component
has been removed from the parent container. You should not invoke this method directly, instead invoke remove
on the parent Container
.removeLayoutComponent
in interface LayoutManager
component
- the component to be removedpublic Dimension preferredLayoutSize(Container parent)
preferredLayoutSize
in interface LayoutManager
parent
- the container to return the preferred size forparent
IllegalArgumentException
- if parent
is not the same Container
this was created withIllegalStateException
- if any of the components added to this layout are not in both a horizontal and vertical grouppublic Dimension minimumLayoutSize(Container parent)
minimumLayoutSize
in interface LayoutManager
parent
- the container to return the size forparent
IllegalArgumentException
- if parent
is not the same Container
that this was created withIllegalStateException
- if any of the components added to this layout are not in both a horizontal and vertical grouppublic void layoutContainer(Container parent)
layoutContainer
in interface LayoutManager
parent
- the container to be laid outIllegalStateException
- if any of the components added to this layout are not in both a horizontal and vertical grouppublic void addLayoutComponent(Component component, Object constraints)
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
.addLayoutComponent
in interface LayoutManager2
component
- the component addedconstraints
- description of where to place the componentpublic Dimension maximumLayoutSize(Container parent)
maximumLayoutSize
in interface LayoutManager2
parent
- the container to return the size forparent
IllegalArgumentException
- if parent
is not the same Container
that this was created withIllegalStateException
- if any of the components added to this layout are not in both a horizontal and vertical grouppublic float getLayoutAlignmentX(Container parent)
getLayoutAlignmentX
in interface LayoutManager2
parent
- the Container
hosting this LayoutManager
.5
IllegalArgumentException
- if parent
is not the same Container
that this was created withpublic float getLayoutAlignmentY(Container parent)
getLayoutAlignmentY
in interface LayoutManager2
parent
- the Container
hosting this LayoutManager
.5
IllegalArgumentException
- if parent
is not the same Container
that this was created withpublic void invalidateLayout(Container parent)
invalidateLayout
in interface LayoutManager2
parent
- the Container
hosting this LayoutManagerIllegalArgumentException
- if parent
is not the same Container
that this was created withpublic String toString()
GroupLayout
. This method is intended to be used for debugging purposes, and the content and format of the returned string may vary between implementations.
© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/java.desktop/javax/swing/GroupLayout.html