JavaTM Platform
Standard Ed. 6

javax.swing
类 GroupLayout

java.lang.Object
  继承者 javax.swing.GroupLayout
所有已实现的接口:
LayoutManager, LayoutManager2

public class GroupLayout
     
extends Object
implements LayoutManager2

GroupLayout 是一个 LayoutManager,它将组件按层次分组,以决定它们在 Container 中的位置。GroupLayout 主要供生成器使用,但也可以手工编码。分组由 Group 类的实例来完成。GroupLayout 支持两种组。串行组 (sequential group) 按顺序一个接一个地放置其子元素。并行组 (parallel group) 能够以四种方式对齐其子元素。

每个组可以包含任意数量的元素,其中元素有 GroupComponent 或间隙 (gap)。间隙可被视为一个具有最小大小、首选大小和最大大小的不可见组件。此外,GroupLayout 还支持其值取自 LayoutStyle 的首选间隙。

元素类似于一个弹簧。每个元素都有一个范围,由最小大小、首选大小和最大大小指定。间隙的范围由开发人员指定,或者由 LayoutStyle 确定。Component 的范围通过 ComponentgetMinimumSizegetPreferredSizegetMaximumSize 方法确定。此外,添加 Component 时,可以指定使用一个特定范围,而不使用该组件的范围。Group 的范围由组的类型确定。ParallelGroup 的范围是其元素范围的最大值。SequentialGroup 的范围是其元素范围的总和。

GroupLayout 将每个轴 (axis) 单独对待。也就是说,存在一个表示水平轴的组和一个表示垂直轴的组。水平组负责确定沿水平轴的最小大小、首选大小和最大大小,并设置所包含组件的 x 和宽度。垂直组负责确定沿垂直轴的最小大小、首选大小和最大大小,并设置所包含组件的 y 和高度。每个 Component 都必须同时存在于水平组和垂直组中,否则,在布局过程中或者在请求最小大小、首选大小或最大大小时,将抛出 IllegalStateException

下图显示了一个沿水平轴的串行组。该串行组包含三个组件。沿垂直轴使用了一个并行组。

为了强调要单独对待每个轴,该图显示了沿每个轴的每个组和元素的范围。每个组件的范围已被投射到轴上,两个组分别呈现为蓝色(水平)和红色(垂直)。为了便于理解,串行组中的每个元素之间都有一个间隙。

沿水平轴的串行组呈现为蓝色实线。注意,串行组是它所包含的子元素的总和。

沿垂直轴,并行组是每个组件高度的最大值。由于三个组件的高度都相同,所以并行组具有相同的高度。

下图显示了与上图中相同的三个组件,但并行组沿水平轴,串行组沿垂直轴。

由于 c1 在三个组件中最大,所以并行组的大小被确定为 c1。由于 c2c3 小于 c1,所以将根据为组件指定的对齐方式(如果已指定)或并行组的默认对齐方式将它们对齐。在该图中,c2c3 是使用 LEADING 的对齐方式创建的。如果组件的方向是从右到左,那么 c2c3 的位置将在相反的一侧对齐(沿右侧对齐)。

下图显示了沿水平和垂直两个轴的串行组。

GroupLayout 提供在 Component 之间插入间隙的能力。间隙的大小由 LayoutStyle 的实例确定。可以使用 setAutoCreateGaps 方法进行此操作。类似地,可以使用 setAutoCreateContainerGaps 方法在触到父容器边缘的组件和容器之间插入间隙。

以下代码构建了一个面板,该面板由两列构成,第一列中有两个标签,第二列中有两个文本字段:

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

运行代码时,将出现下面的窗口。

此布局由以下部分组成。

在这段代码中,要注意几个问题:

从以下版本开始:
1.6

嵌套类摘要
static class GroupLayout.Alignment
          ParallelGroup 能够对齐其子元素的可能方式的枚举。
 class GroupLayout.Group
          GroupGroupLayout 所支持的以下两种操作提供基础:一个接一个地布置组件(SequentialGroup)或对齐组件(ParallelGroup)。
 class GroupLayout.ParallelGroup
          一个 Group,它对齐其子元素并确定其大小。
 class GroupLayout.SequentialGroup
          一个 Group,它按顺序一个接一个地确定其元素的位置和大小。
 
字段摘要
static int DEFAULT_SIZE
          指示组件或间隙的大小应该用于特定的范围值。
static int PREFERRED_SIZE
          指示组件或间隙的首选大小应该用于特定的范围值。
 
构造方法摘要
GroupLayout(Container host)
          为指定的 Container 创建 GroupLayout
 
方法摘要
 void addLayoutComponent(Component component, Object constraints)
          已将 Component 添加到父容器的通知。
 void addLayoutComponent(String name, Component component)
          已将 Component 添加到父容器的通知。
 GroupLayout.ParallelGroup createBaselineGroup(boolean resizable, boolean anchorBaselineToTop)
          创建并返回一个沿基线对齐其元素的 ParallelGroup
 GroupLayout.ParallelGroup createParallelGroup()
          使用 Alignment.LEADING 的对齐方式创建并返回一个 ParallelGroup
 GroupLayout.ParallelGroup createParallelGroup(GroupLayout.Alignment alignment)
          使用指定的对齐方式创建并返回一个 ParallelGroup
 GroupLayout.ParallelGroup createParallelGroup(GroupLayout.Alignment alignment, boolean resizable)
          使用指定的对齐方式和调整大小行为创建并返回一个 ParallelGroup
 GroupLayout.SequentialGroup createSequentialGroup()
          创建并返回一个 SequentialGroup
 boolean getAutoCreateContainerGaps()
          如果自动创建容器与触到容器边框的组件之间的间隙,则返回 true
 boolean getAutoCreateGaps()
          如果自动创建组件之间的间隙,则返回 true
 boolean getHonorsVisibility()
          返回确定组件的大小和位置时是否要考虑组件的可见性。
 float getLayoutAlignmentX(Container parent)
          返回沿 x 轴的对齐方式。
 float getLayoutAlignmentY(Container parent)
          返回沿 y 轴的对齐方式。
 LayoutStyle getLayoutStyle()
          返回 LayoutStyle,用于计算组件之间的首选间隙。
 void invalidateLayout(Container parent)
          使布局失效,指示如果布局管理器缓存了信息,则应该将其丢弃。
 void layoutContainer(Container parent)
          布置指定的容器。
 void linkSize(Component... components)
          将指定组件强制调整为具有相同的大小,而不管其首选大小、最小大小或最大大小如何。
 void linkSize(int axis, Component... components)
          将指定组件强制调整为沿指定轴具有相同的大小,而不管其首选大小、最小大小或最大大小如何。
 Dimension maximumLayoutSize(Container parent)
          返回指定容器的最大大小。
 Dimension minimumLayoutSize(Container parent)
          返回指定容器的最小大小。
 Dimension preferredLayoutSize(Container parent)
          返回指定容器的首选大小。
 void removeLayoutComponent(Component component)
          已从父容器中移除 Component 的通知。
 void replace(Component existingComponent, Component newComponent)
          使用新的组件替代现有组件。
 void setAutoCreateContainerGaps(boolean autoCreateContainerPadding)
          设置是否应该自动创建容器与触到容器边框的组件之间的间隙。
 void setAutoCreateGaps(boolean autoCreatePadding)
          设置是否将自动创建组件之间的间隙。
 void setHonorsVisibility(boolean honorsVisibility)
          设置确定组件的大小和位置时是否要考虑组件的可见性。
 void setHonorsVisibility(Component component, Boolean honorsVisibility)
          设置确定组件的大小和位置时是否要考虑组件的可见性。
 void setHorizontalGroup(GroupLayout.Group group)
          设置沿水平轴确定组件位置和大小的 Group
 void setLayoutStyle(LayoutStyle layoutStyle)
          设置用于计算组件之间首选间隙的 LayoutStyle
 void setVerticalGroup(GroupLayout.Group group)
          设置沿垂直轴确定组件位置和大小的 Group
 String toString()
          返回此 GroupLayout 的字符串表示形式。
 
从类 java.lang.Object 继承的方法
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

字段详细信息

DEFAULT_SIZE

public static final int DEFAULT_SIZE
指示组件或间隙的大小应该用于特定的范围值。

另请参见:
GroupLayout.Group, 常量字段值

PREFERRED_SIZE

public static final int PREFERRED_SIZE
指示组件或间隙的首选大小应该用于特定的范围值。

另请参见:
GroupLayout.Group, 常量字段值
构造方法详细信息

GroupLayout

public GroupLayout(Container host)
为指定的 Container 创建 GroupLayout

参数:
host - Container,创建的 GroupLayout 将作为其 LayoutManager
抛出:
IllegalArgumentException - 如果 host 为 null
方法详细信息

setHonorsVisibility

public void setHonorsVisibility(boolean honorsVisibility)
设置确定组件的大小和位置时是否要考虑组件的可见性。 true 值指示非可见组件不应该被视为布局的一部分。 false 值指示组件应该被确定位置和大小,而不管其可见性如何。

当组件的可见性是动态调整的并且不想更改周围的组件及其大小时,false 值很有用。

指定的值用于没有指定明确可见性的组件。

默认值为 true

参数:
honorsVisibility - 确定组件的大小和位置时是否要考虑组件的可见性
另请参见:
setHonorsVisibility(Component,Boolean)

getHonorsVisibility

public boolean getHonorsVisibility()
返回确定组件的大小和位置时是否要考虑组件的可见性。

返回:
确定组件的大小和位置时是否要考虑组件的可见性

setHonorsVisibility

public void setHonorsVisibility(Component component,
                                Boolean honorsVisibility)
设置确定组件的大小和位置时是否要考虑组件的可见性。 Boolean.TRUE 值指示如果 component 不可见,则它不应该被视为布局的一部分。 false 值指示 component 应该被确定位置和大小,而不管其可见性如何。 null 值指示应该使用由单参数方法 setHonorsVisibility 指定的值。

如果 component 不是此 GroupLayout 管理的 Container 的子组件,则它将被添加到 Container

参数:
component - 组件
honorsVisibility - 确定大小和位置时是否要考虑 component 的可见性
抛出:
IllegalArgumentException - 如果 componentnull
另请参见:
setHonorsVisibility(Component,Boolean)

setAutoCreateGaps

public void setAutoCreateGaps(boolean autoCreatePadding)
设置是否将自动创建组件之间的间隙。例如,如果设为 true 并且向 SequentialGroup 添加了两个组件,则将自动创建这两个组件之间的间隙。默认值为 false

参数:
autoCreatePadding - 是否自动创建组件之间的间隙

getAutoCreateGaps

public boolean getAutoCreateGaps()
如果自动创建组件之间的间隙,则返回 true

返回:
如果自动创建组件之间的间隙,则返回 true

setAutoCreateContainerGaps

public void setAutoCreateContainerGaps(boolean autoCreateContainerPadding)
设置是否应该自动创建容器与触到容器边框的组件之间的间隙。默认值为 false

参数:
autoCreateContainerPadding - 是否应该自动创建容器与触到容器边框的组件之间的间隙

getAutoCreateContainerGaps

public boolean getAutoCreateContainerGaps()
如果自动创建容器与触到容器边框的组件之间的间隙,则返回 true

返回:
如果自动创建容器与触到容器边框的组件之间的间隙,则返回 true

setHorizontalGroup

public void setHorizontalGroup(GroupLayout.Group group)
设置沿水平轴确定组件位置和大小的 Group

参数:
group - 沿水平轴确定组件位置和大小的 Group
抛出:
IllegalArgumentException - 如果 group 为 null

setVerticalGroup

public void setVerticalGroup(GroupLayout.Group group)
设置沿垂直轴确定组件位置和大小的 Group

参数:
group - 沿垂直轴确定组件位置和大小的 Group
抛出:
IllegalArgumentException - 如果 group 为 null

createSequentialGroup

public GroupLayout.SequentialGroup createSequentialGroup()
创建并返回一个 SequentialGroup

返回:
一个新的 SequentialGroup

createParallelGroup

public GroupLayout.ParallelGroup createParallelGroup()
使用 Alignment.LEADING 的对齐方式创建并返回一个 ParallelGroup。此方法是更常用的 createParallelGroup(Alignment) 方法的覆盖方法。

返回:
一个新的 ParallelGroup
另请参见:
createParallelGroup(Alignment)

createParallelGroup

public GroupLayout.ParallelGroup createParallelGroup(GroupLayout.Alignment alignment)
使用指定的对齐方式创建并返回一个 ParallelGroup。此方法是更常用的 createParallelGroup(Alignment,boolean) 方法(其中第二个参数为 true)的覆盖方法。

参数:
alignment - 组元素的对齐方式
返回:
一个新的 ParallelGroup
抛出:
IllegalArgumentException - 如果 alignmentnull
另请参见:
createBaselineGroup(boolean, boolean), GroupLayout.ParallelGroup

createParallelGroup

public GroupLayout.ParallelGroup createParallelGroup(GroupLayout.Alignment alignment,
                                                     boolean resizable)
使用指定的对齐方式和调整大小行为创建并返回一个 ParallelGroupalignment 参数指定如何确定没有将组填满的子元素的位置。例如,如果对齐方式为 TRAILINGParallelGroup 被给定为 100,而一个子元素只需要 50,则将该子元素放置在位置 50(组件方向从左到右)。

只有在沿垂直轴使用时基线对齐方式才有用。使用沿水平轴的基线对齐方式创建的 ParallelGroup 被视为 LEADING

有关基线组行为的详细信息,请参阅 ParallelGroup

参数:
alignment - 组元素的对齐方式
resizable - 如果组是可调整大小的,则返回 true;如果组是不可调整大小的,则首选大小用于组的最小大小和最大大小。
返回:
一个新的 ParallelGroup
抛出:
IllegalArgumentException - 如果 alignmentnull
另请参见:
createBaselineGroup(boolean, boolean), GroupLayout.ParallelGroup

createBaselineGroup

public GroupLayout.ParallelGroup createBaselineGroup(boolean resizable,
                                                     boolean anchorBaselineToTop)
创建并返回一个沿基线对齐其元素的 ParallelGroup

参数:
resizable - 组是否是可调整大小的
anchorBaselineToTop - 基线是固定在组的顶部还是底部
另请参见:
createBaselineGroup(boolean, boolean), GroupLayout.ParallelGroup

linkSize

public void linkSize(Component... components)
将指定组件强制调整为具有相同的大小,而不管其首选大小、最小大小或最大大小如何。将所有链接组件首选大小中的最大值赋予链接的组件。例如,如果将首选宽度分别为 10 和 20 的两个组件链接起来,则两个组件的宽度都将变为 20。

可以多次使用此方法来将任意数量的组件强制调整为具有相同的大小。

链接的 Component 是不可调整大小的。

参数:
components - 要具有相同大小的 Component
抛出:
IllegalArgumentException - 如果 componentsnull 或包含 null
另请参见:
linkSize(int,Component[])

linkSize

public void linkSize(int axis,
                     Component... components)
将指定组件强制调整为沿指定轴具有相同的大小,而不管其首选大小、最小大小或最大大小如何。将所有链接组件首选大小中的最大值赋予链接的组件。例如,如果沿水平轴将首选宽度分别为 10 和 20 的两个组件链接起来,则两个组件的宽度都将变为 20。

可以多次使用此方法来将任意数量的组件强制调整为具有相同的大小。

链接的 Component 是不可调整大小的。

参数:
components - 要具有相同大小的 Component
axis - 沿其链接大小的轴; SwingConstants.HORIZONTALSwingConstans.VERTICAL 之一
抛出:
IllegalArgumentException - 如果 componentsnull 或包含 null;或者 axis 不是 SwingConstants.HORIZONTALSwingConstants.VERTICAL

replace

public void replace(Component existingComponent,
                    Component newComponent)
使用新的组件替代现有组件。

参数:
existingComponent - 应该被移除并用 newComponent 来替代的组件
newComponent - 要放入 existingComponent 的位置的组件
抛出:
IllegalArgumentException - 如果任一组件为 null 或者 existingComponent 不受此布局管理器管理

setLayoutStyle

public void setLayoutStyle(LayoutStyle layoutStyle)
设置用于计算组件之间首选间隙的 LayoutStylenull 值指示应该使用 LayoutStyle 的共享实例。

参数:
layoutStyle - 要使用的 LayoutStyle
另请参见:
LayoutStyle

getLayoutStyle

public LayoutStyle getLayoutStyle()
返回 LayoutStyle,用于计算组件之间的首选间隙。此方法返回指定给 setLayoutStyle 的值,可以为 null

返回:
用于计算组件之间首选间隙的 LayoutStyle

addLayoutComponent

public void addLayoutComponent(String name,
                               Component component)
已将 Component 添加到父容器的通知。不应该直接调用此方法,而应该使用一个 Group 方法来添加 Component

指定者:
接口 LayoutManager 中的 addLayoutComponent
参数:
name - 要与组件关联的字符串
component - 要添加的 Component

removeLayoutComponent

public void removeLayoutComponent(Component component)
已从父容器中移除 Component 的通知。不应该直接调用此方法,而应该调用父 Container 上的 remove

指定者:
接口 LayoutManager 中的 removeLayoutComponent
参数:
component - 要移除的组件
另请参见:
Component.remove(java.awt.MenuComponent)

preferredLayoutSize

public Dimension preferredLayoutSize(Container parent)
返回指定容器的首选大小。

指定者:
接口 LayoutManager 中的 preferredLayoutSize
参数:
parent - 要返回其首选大小的容器
返回:
parent 的首选大小
抛出:
IllegalArgumentException - 如果 parent 不是创建此 GroupLayout 的相同 Container
IllegalStateException - 如果添加到此布局的任意组件不同时位于水平组和垂直组中
另请参见:
Container.getPreferredSize()

minimumLayoutSize

public Dimension minimumLayoutSize(Container parent)
返回指定容器的最小大小。

指定者:
接口 LayoutManager 中的 minimumLayoutSize
参数:
parent - 要返回其大小的容器
返回:
parent 的最小大小
抛出:
IllegalArgumentException - 如果 parent 不是创建此 GroupLayout 的相同 Container
IllegalStateException - 如果添加到此布局的任意组件不同时位于水平组和垂直组中
另请参见:
Container.getMinimumSize()

layoutContainer

public void layoutContainer(Container parent)
布置指定的容器。

指定者:
接口 LayoutManager 中的 layoutContainer
参数:
parent - 要布置的容器
抛出:
IllegalStateException - 如果添加到此布局的任意组件不同时位于水平组和垂直组中

addLayoutComponent

public void addLayoutComponent(Component component,
                               Object constraints)
已将 Component 添加到父容器的通知。不应该直接调用此方法,而应该使用一个 Group 方法来添加 Component

指定者:
接口 LayoutManager2 中的 addLayoutComponent
参数:
component - 要添加的组件
constraints - 组件放置位置的描述

maximumLayoutSize

public Dimension maximumLayoutSize(Container parent)
返回指定容器的最大大小。

指定者:
接口 LayoutManager2 中的 maximumLayoutSize
参数:
parent - 要返回其大小的容器
返回:
parent 的最大大小
抛出:
IllegalArgumentException - 如果 parent 不是创建此 GroupLayout 的相同 Container
IllegalStateException - 如果添加到此布局的任意组件不同时位于水平组和垂直组中
另请参见:
Container.getMaximumSize()

getLayoutAlignmentX

public float getLayoutAlignmentX(Container parent)
返回沿 x 轴的对齐方式。此方法指出如何相对于其他组件对齐该组件。该值应该是 0 到 1 之间的一个数,其中 0 表示沿原点对齐,1 表示在距原点最远的地方对齐,0.5 表示居中等等。

指定者:
接口 LayoutManager2 中的 getLayoutAlignmentX
参数:
parent - 应用此 LayoutManagerContainer
返回:
对齐方式;此实现返回 0.5
抛出:
IllegalArgumentException - 如果 parent 不是创建此 GroupLayout 的相同 Container

getLayoutAlignmentY

public float getLayoutAlignmentY(Container parent)
返回沿 y 轴的对齐方式。此方法指出如何相对于其他组件对齐该组件。该值应该是 0 到 1 之间的一个数,其中 0 表示沿原点对齐,1 表示在距原点最远的地方对齐,0.5 表示居中等等。

指定者:
接口 LayoutManager2 中的 getLayoutAlignmentY
参数:
parent - 应用此 LayoutManagerContainer
返回:
对齐方式;此实现返回 0.5
抛出:
IllegalArgumentException - 如果 parent 不是创建此 GroupLayout 的相同 Container

invalidateLayout

public void invalidateLayout(Container parent)
使布局失效,指示如果布局管理器缓存了信息,则应该将其丢弃。

指定者:
接口 LayoutManager2 中的 invalidateLayout
参数:
parent - 应用此 LayoutManager 的 Container
抛出:
IllegalArgumentException - 如果 parent 不是创建此 GroupLayout 的相同 Container

toString

public String toString()
返回此 GroupLayout 的字符串表示形式。此方法仅用于调试,对于各个实现,所返回字符串的内容和格式可能有所不同。

覆盖:
Object 中的 toString
返回:
GroupLayout 的字符串表示形式

JavaTM Platform
Standard Ed. 6

提交错误或意见
有关更多的 API 参考资料和开发人员文档,请参阅 Java SE 开发人员文档。该文档包含更详细的、面向开发人员的描述,以及总体概述、术语定义、使用技巧和工作代码示例。

版权所有 2007 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策