Package org.jdesktop.layout
Class GroupLayout
java.lang.Object
org.jdesktop.layout.GroupLayout
- All Implemented Interfaces:
LayoutManager
,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:
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.
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. |
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.
- 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 ofGroups
return themselves. This allows for easy chaining of invocations. For example,group.add(label1).add(label2);
is equivalent togroup.add(label1);group.add(label2);
. - There are no public constructors for the Groups, instead
use the create methods of
GroupLayout
.
setAutocreateGaps()
method. Similarly you can use
the setAutocreateContainerGaps()
method to insert gaps
between the components and the container.-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionclass
Group provides for commonality between the two types of operations supported byGroupLayout
: laying out components one after another (SequentialGroup
) or layout on top of each other (ParallelGroup
).class
AGroup
that lays out its elements on top of each other.class
AGroup
that lays out its elements sequentially, one after another. -
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final int
Possible alignment type.static final int
Possible alignment type.static final int
Possible value for the add methods that takes a Component.static final int
Possible argument when linking sizes of components.static final int
Possible alignment type.static final int
Possible value for the add methods that takes a Component.static final int
Possible alignment type.static final int
Possible argument when linking sizes of components. -
Constructor Summary
ConstructorsConstructorDescriptionGroupLayout
(Container host) Creates a GroupLayout for the specified JComponent. -
Method Summary
Modifier and TypeMethodDescriptionvoid
addLayoutComponent
(Component component, Object constraints) Notification that aComponent
has been added to the parent container.void
addLayoutComponent
(String name, Component component) Notification that aComponent
has been added to the parent container.createBaselineGroup
(boolean resizable, boolean anchorBaselineToTop) Creates and returns aParallelGroup
that aligns it's elements along the baseline.Creates and returns aParallelGroup
with aLEADING
alignment.createParallelGroup
(int alignment) Creates and returns anParallelGroup
.createParallelGroup
(int alignment, boolean resizable) Creates and returns anParallelGroup
.Creates and returns aSequentialGroup
.boolean
Returns whether or not gaps between the container and the first/last components should automatically be created.boolean
Returns true if gaps between components are automatically be created.boolean
Returns whether component visiblity is considered when sizing and positioning components.Returns theGroup
that is responsible for layout along the horizontal axis.float
getLayoutAlignmentX
(Container parent) Returns the alignment along the x axis.float
getLayoutAlignmentY
(Container parent) Returns the alignment along the y axis.Returns the LayoutStyle instance to useReturns theParallelGroup
that is responsible for layout along the vertical axis.void
invalidateLayout
(Container parent) Invalidates the layout, indicating that if the layout manager has cached information it should be discarded.void
layoutContainer
(Container parent) Lays out the specified container.void
Forces the set of components to have the same size.void
Forces the set of components to have the same size.maximumLayoutSize
(Container parent) Returns the maximum size for the specified container.minimumLayoutSize
(Container parent) Returns the minimum size for the specified container.preferredLayoutSize
(Container parent) Returns the preferred size for the specified container.void
removeLayoutComponent
(Component component) Notification that aComponent
has been removed from the parent container.void
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 visiblity is considered when sizing and positioning components.void
setHonorsVisibility
(Component component, Boolean honorsVisibility) Sets whether the component's visiblity is considered for sizing and positioning.void
Sets theGroup
that is responsible for layout along the horizontal axis.void
setLayoutStyle
(LayoutStyle layoutStyle) Sets the LayoutStyle this GroupLayout is to use.void
Sets theGroup
that is responsible for layout along the vertical axis.toString()
Returns a textual description of this GroupLayout.
-
Field Details
-
HORIZONTAL
public static final int HORIZONTALPossible argument when linking sizes of components. Specifies the the two component should share the same size along the horizontal axis. -
VERTICAL
public static final int VERTICALPossible argument when linking sizes of components. Specifies the the two component should share the same size along the vertical axis. -
LEADING
public static final int LEADINGPossible 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. -
TRAILING
public static final int TRAILINGPossible 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. -
CENTER
public static final int CENTERPossible alignment type. Indicates the elements should centered in the spaced provided. -
BASELINE
public static final int BASELINEPossible alignment type. Indicates the elements should aligned along their baseline. -
DEFAULT_SIZE
public static final int DEFAULT_SIZEPossible value for the add methods that takes a Component. Indicates the size from the component should be used.- See Also:
-
PREFERRED_SIZE
public static final int PREFERRED_SIZEPossible value for the add methods that takes a Component. Indicates the preferred size should be used.- See Also:
-
-
Constructor Details
-
GroupLayout
Creates a GroupLayout for the specified JComponent.- Parameters:
host
- the Container to layout- Throws:
IllegalArgumentException
- if host is null
-
-
Method Details
-
setHonorsVisibility
public void setHonorsVisibility(boolean honorsVisibility) Sets whether component visiblity is considered when sizing and positioning components. A value oftrue
indicates that non-visible components should not be treated as part of the layout. A value offalse
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:
-
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
-
setHonorsVisibility
Sets whether the component's visiblity is considered for sizing and positioning. A value ofBoolean.TRUE
indicates that ifcomponent
is not visible it should not be treated as part of the layout. A value offalse
indicates thatcomponent
is positioned and sized regardless of it's visibility. A value ofnull
indicates the value specified by the single argument methodsetHonorsVisibility
should be used.If
component
is not a child of theContainer
thisGroupLayout
is managing, it will be added to theContainer
.- Parameters:
component
- the componenthonorsVisibility
- whethercomponent
's visiblity should be considered for sizing and positioning- Throws:
IllegalArgumentException
- ifcomponent
isnull
- See Also:
-
toString
Returns a textual description of this GroupLayout. The return value is intended for debugging purposes only. -
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 aSequentialGroup
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
-
getAutocreateGaps
public boolean getAutocreateGaps()Returns true if gaps between components are automatically be created.- Returns:
- true if gaps between 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
- whether or not to automatically create gaps between the container and first/last components.
-
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
-
setHorizontalGroup
Sets theGroup
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
-
getHorizontalGroup
Returns theGroup
that is responsible for layout along the horizontal axis.- Returns:
ParallelGroup
responsible for layout along the horizontal axis.
-
setVerticalGroup
Sets theGroup
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.
-
getVerticalGroup
Returns theParallelGroup
that is responsible for layout along the vertical axis.- Returns:
ParallelGroup
responsible for layout along the vertical axis.
-
createSequentialGroup
Creates and returns aSequentialGroup
.- Returns:
- a new
SequentialGroup
-
createParallelGroup
Creates and returns aParallelGroup
with aLEADING
alignment. This is a cover method for the more generalcreateParallelGroup(int)
method.- Returns:
- a new ParallelGroup
- See Also:
-
createParallelGroup
Creates and returns anParallelGroup
. 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 ofLEADING
,TRAILING
,CENTER
orBASELINE
.- Returns:
- a new
ParallelGroup
- Throws:
IllegalArgumentException
- if alignment is not one ofLEADING
,TRAILING
,CENTER
orBASELINE
-
createParallelGroup
Creates and returns anParallelGroup
. 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 ofLEADING
,TRAILING
,CENTER
orBASELINE
.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 ofLEADING
,TRAILING
,CENTER
orBASELINE
-
createBaselineGroup
public GroupLayout.ParallelGroup createBaselineGroup(boolean resizable, boolean anchorBaselineToTop) Creates and returns aParallelGroup
that aligns it's elements along the baseline.- Parameters:
resizable
- whether the group is resizableanchorBaselineToTop
- whether the baseline is anchored to the top or bottom of the group- See Also:
-
linkSize
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
- ifcomponents
is null, or contains null.
-
linkSize
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
- ifcomponents
is null, or contains null.IllegalArgumentException
- ifaxis
does not containHORIZONTAL
orVERTICAL
-
replace
Removes an existing component replacing it with the specified component.- Parameters:
existingComponent
- the Component that should be removed and replaced with newComponentnewComponent
- 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
-
setLayoutStyle
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
-
getLayoutStyle
Returns the LayoutStyle instance to use- Returns:
- the LayoutStyle instance to use
-
addLayoutComponent
Notification that aComponent
has been added to the parent container. Developers should not invoke this method directly, instead you should use one of theGroup
methods to add aComponent
.- Specified by:
addLayoutComponent
in interfaceLayoutManager
- Parameters:
name
- the string to be associated with the componentcomponent
- theComponent
to be added
-
removeLayoutComponent
Notification that aComponent
has been removed from the parent container. You should not invoke this method directly, instead invokeremove
on the parentContainer
.- Specified by:
removeLayoutComponent
in interfaceLayoutManager
- Parameters:
component
- the component to be removed- See Also:
-
preferredLayoutSize
Returns the preferred size for the specified container.- Specified by:
preferredLayoutSize
in interfaceLayoutManager
- Parameters:
parent
- the container to return size for- Throws:
IllegalArgumentException
- ifparent
is not the sameContainer
that this was created withIllegalStateException
- if any of the components added to this layout are not in both a horizontal and vertical group- See Also:
-
minimumLayoutSize
Returns the minimum size for the specified container.- Specified by:
minimumLayoutSize
in interfaceLayoutManager
- Parameters:
parent
- the container to return size for- Throws:
IllegalArgumentException
- ifparent
is not the sameContainer
that this was created withIllegalStateException
- if any of the components added to this layout are not in both a horizontal and vertical group- See Also:
-
layoutContainer
Lays out the specified container.- Specified by:
layoutContainer
in interfaceLayoutManager
- 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
-
addLayoutComponent
Notification that aComponent
has been added to the parent container. You should not invoke this method directly, instead you should use one of theGroup
methods to add aComponent
.- Specified by:
addLayoutComponent
in interfaceLayoutManager2
- Parameters:
component
- The component addedconstraints
- Description of where to place the component.
-
maximumLayoutSize
Returns the maximum size for the specified container.- Specified by:
maximumLayoutSize
in interfaceLayoutManager2
- Parameters:
parent
- the container to return size for- Throws:
IllegalArgumentException
- ifparent
is not the sameContainer
that this was created withIllegalStateException
- if any of the components added to this layout are not in both a horizontal and vertical group- See Also:
-
getLayoutAlignmentX
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.- Specified by:
getLayoutAlignmentX
in interfaceLayoutManager2
- Parameters:
parent
- Container hosting this LayoutManager- Returns:
- alignment
- Throws:
IllegalArgumentException
- ifparent
is not the sameContainer
that this was created with
-
getLayoutAlignmentY
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.- Specified by:
getLayoutAlignmentY
in interfaceLayoutManager2
- Parameters:
parent
- Container hosting this LayoutManager- Returns:
- alignment
- Throws:
IllegalArgumentException
- ifparent
is not the sameContainer
that this was created with
-
invalidateLayout
Invalidates the layout, indicating that if the layout manager has cached information it should be discarded.- Specified by:
invalidateLayout
in interfaceLayoutManager2
- Parameters:
parent
- Container hosting this LayoutManager- Throws:
IllegalArgumentException
- ifparent
is not the sameContainer
that this was created with
-