|
Java™ Platform Standard Ed. 6 |
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
java.lang.Objectjavax.swing.GroupLayout
public class GroupLayout
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 Components is determined from
the Component's getMinimumSize, getPreferredSize and getMaximumSize methods. In addition,
when adding Components 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
Components. 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);.
Groups; instead
use the create methods of GroupLayout.
| Nested Class Summary | |
|---|---|
static class |
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 it's children. |
class |
GroupLayout.SequentialGroup
A Group that positions and sizes its elements
sequentially, one after another. |
| Field Summary | |
|---|---|
static int |
DEFAULT_SIZE
Indicates the size from the component or gap should be used for a particular range value. |
static int |
PREFERRED_SIZE
Indicates the preferred size from the component or gap should be used for a particular range value. |
| Constructor Summary | |
|---|---|
GroupLayout(Container host)
Creates a GroupLayout for the specified Container. |
|
| Method Summary | |
|---|---|
void |
addLayoutComponent(Component component,
Object constraints)
Notification that a Component has been added to
the parent container. |
void |
addLayoutComponent(String name,
Component component)
Notification that a Component has been added to
the parent container. |
GroupLayout.ParallelGroup |
createBaselineGroup(boolean resizable,
boolean anchorBaselineToTop)
Creates and returns a ParallelGroup that aligns it's
elements along the baseline. |
GroupLayout.ParallelGroup |
createParallelGroup()
Creates and returns a ParallelGroup with an alignment of
Alignment.LEADING. |
GroupLayout.ParallelGroup |
createParallelGroup(GroupLayout.Alignment alignment)
Creates and returns a ParallelGroup with the specified
alignment. |
GroupLayout.ParallelGroup |
createParallelGroup(GroupLayout.Alignment alignment,
boolean resizable)
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 visiblity is considered when sizing and positioning components. |
float |
getLayoutAlignmentX(Container parent)
Returns the alignment along the x axis. |
float |
getLayoutAlignmentY(Container parent)
Returns the alignment along the y axis. |
LayoutStyle |
getLayoutStyle()
Returns the LayoutStyle used for calculating the preferred
gap between components. |
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 |
linkSize(Component... components)
Forces the specified components to have the same size regardless of their preferred, minimum or maximum sizes. |
void |
linkSize(int axis,
Component... components)
Forces the specified components to have the same size along the specified axis regardless of their preferred, minimum or maximum sizes. |
Dimension |
maximumLayoutSize(Container parent)
Returns the maximum size for the specified container. |
Dimension |
minimumLayoutSize(Container parent)
Returns the minimum size for the specified container. |
Dimension |
preferredLayoutSize(Container parent)
Returns the preferred size for the specified container. |
void |
removeLayoutComponent(Component component)
Notification that a Component has been removed from
the parent container. |
void |
replace(Component existingComponent,
Component newComponent)
Replaces an existing component with a new one. |
void |
setAutoCreateContainerGaps(boolean autoCreateContainerPadding)
Sets whether a gap between the container and components that touch the border of the container should automatically be created. |
void |
setAutoCreateGaps(boolean autoCreatePadding)
Sets whether 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 |
setHorizontalGroup(GroupLayout.Group group)
Sets the Group that positions and sizes
components along the horizontal axis. |
void |
setLayoutStyle(LayoutStyle layoutStyle)
Sets the LayoutStyle used to calculate the preferred
gaps between components. |
void |
setVerticalGroup(GroupLayout.Group group)
Sets the Group that positions and sizes
components along the vertical axis. |
String |
toString()
Returns a string representation of this GroupLayout. |
| Methods inherited from class java.lang.Object |
|---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait |
| Field Detail |
|---|
public static final int DEFAULT_SIZE
GroupLayout.Group,
Constant Field Valuespublic static final int PREFERRED_SIZE
GroupLayout.Group,
Constant Field Values| Constructor Detail |
|---|
public GroupLayout(Container host)
GroupLayout for the specified Container.
host - the Container the GroupLayout is
the LayoutManager for
IllegalArgumentException - if host is null| Method Detail |
|---|
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 visiblity is considered when
sizing and positioning componentssetHonorsVisibility(Component,Boolean)public 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 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 managine, it will be added to the
Container.
component - the componenthonorsVisibility - whether component's visiblity should be
considered for sizing and positioning
IllegalArgumentException - if component is nullsetHonorsVisibility(Component,Boolean)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 axis
IllegalArgumentException - if group is nullpublic 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 axis
IllegalArgumentException - if group is nullpublic GroupLayout.SequentialGroup createSequentialGroup()
SequentialGroup.
SequentialGrouppublic GroupLayout.ParallelGroup createParallelGroup()
ParallelGroup with an alignment of
Alignment.LEADING. This is a cover method for the more
general createParallelGroup(Alignment) method.
ParallelGroupcreateParallelGroup(Alignment)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 group
ParallelGroup
IllegalArgumentException - if alignment is nullcreateBaselineGroup(boolean, boolean),
GroupLayout.ParallelGroup
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 group
ParallelGroup
IllegalArgumentException - if alignment is nullcreateBaselineGroup(boolean, boolean),
GroupLayout.ParallelGroup
public GroupLayout.ParallelGroup createBaselineGroup(boolean resizable,
boolean anchorBaselineToTop)
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 groupcreateBaselineGroup(boolean, boolean),
GroupLayout.ParallelGrouppublic 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 Components that are to have the same size
IllegalArgumentException - if components is
null, or contains nulllinkSize(int,Component[])
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 Components are not be resizable.
components - the Components that are to have the same sizeaxis - the axis to link the size along; one of
SwingConstants.HORIZONTAL or
SwingConstans.VERTICAL
IllegalArgumentException - 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 newComponentnewComponent - the component to put in
existingComponent's place
IllegalArgumentException - 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 useLayoutStylepublic 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 components
public 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 LayoutManagername - 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 LayoutManagercomponent - the component to be removedComponent.remove(java.awt.MenuComponent)public Dimension preferredLayoutSize(Container parent)
preferredLayoutSize in interface LayoutManagerparent - the container to return the preferred size for
parent
IllegalArgumentException - if parent is not
the same Container this was created with
IllegalStateException - if any of the components added to
this layout are not in both a horizontal and vertical groupContainer.getPreferredSize()public Dimension minimumLayoutSize(Container parent)
minimumLayoutSize in interface LayoutManagerparent - the container to return the size for
parent
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 groupContainer.getMinimumSize()public void layoutContainer(Container parent)
layoutContainer in interface LayoutManagerparent - the container to be laid out
IllegalStateException - if any of the components added to
this layout are not in both a horizontal and vertical group
public 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 LayoutManager2component - the component addedconstraints - description of where to place the componentpublic Dimension maximumLayoutSize(Container parent)
maximumLayoutSize in interface LayoutManager2parent - the container to return the size for
parent
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 groupContainer.getMaximumSize()public float getLayoutAlignmentX(Container parent)
getLayoutAlignmentX in interface LayoutManager2parent - 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 LayoutManager2parent - 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 LayoutManager2parent - the Container hosting this LayoutManager
IllegalArgumentException - 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.
toString in class ObjectGroupLayout
|
Java™ Platform Standard Ed. 6 |
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
Copyright 2006 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms. Also see the documentation redistribution policy.