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) 能够以四种方式对齐其子元素。

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

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

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

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

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

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

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

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

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

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

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

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

此布局由以下部分组成。

• 水平轴由一个包含两个并行组的串行组组成。第一个并行组包含标签，第二个并行组包含文本字段。
• 垂直轴由一个包含两个并行组的串行组组成。并行组被配置为沿基线对齐其组件。第一个并行组包含第一个标签和第一个文本字段，第二个并行组包含第二个标签和第二个文本字段。

• 不需要显式地将组件添加到容器；通过使用 Group 的一个 add 方法间接完成此操作。
• 各种 add 方法返回调用者。这使得调用能很方便地进行链接。例如，group.addComponent(label1).addComponent(label2); 等效于 group.addComponent(label1); group.addComponent(label2);。
• Group 没有公共构造方法；请使用 GroupLayout 的创建方法替代。

从以下版本开始：

1.6

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 - 如果 component 为 null

另请参见：

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 - 如果 alignment 为 null

另请参见：

createBaselineGroup(boolean, boolean), GroupLayout.ParallelGroup

createParallelGroup

public GroupLayout.ParallelGroup createParallelGroup(GroupLayout.Alignment alignment,
                                                     boolean resizable)

使用指定的对齐方式和调整大小行为创建并返回一个 ParallelGroup。alignment 参数指定如何确定没有将组填满的子元素的位置。例如，如果对齐方式为 TRAILING 的 ParallelGroup 被给定为 100，而一个子元素只需要 50，则将该子元素放置在位置 50（组件方向从左到右）。

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

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

参数：

alignment - 组元素的对齐方式

resizable - 如果组是可调整大小的，则返回 true；如果组是不可调整大小的，则首选大小用于组的最小大小和最大大小。

返回：

一个新的 ParallelGroup

抛出：

IllegalArgumentException - 如果 alignment 为 null

另请参见：

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 - 如果 components 为 null 或包含 null

另请参见：

linkSize(int,Component[])

linkSize

public void linkSize(int axis,
                     Component... components)

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

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

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

参数：

components - 要具有相同大小的 Component

axis - 沿其链接大小的轴；SwingConstants.HORIZONTAL 或 SwingConstans.VERTICAL 之一

抛出：

IllegalArgumentException - 如果 components 为 null 或包含 null；或者 axis 不是 SwingConstants.HORIZONTAL 或 SwingConstants.VERTICAL

replace

public void replace(Component existingComponent,
                    Component newComponent)

使用新的组件替代现有组件。

参数：

existingComponent - 应该被移除并用 newComponent 来替代的组件

newComponent - 要放入 existingComponent 的位置的组件

抛出：

IllegalArgumentException - 如果任一组件为 null 或者 existingComponent 不受此布局管理器管理

setLayoutStyle

public void setLayoutStyle(LayoutStyle layoutStyle)

设置用于计算组件之间首选间隙的 LayoutStyle。null 值指示应该使用 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 - 应用此 LayoutManager 的 Container

返回：

对齐方式；此实现返回 0.5

抛出：

IllegalArgumentException - 如果 parent 不是创建此 GroupLayout 的相同 Container

getLayoutAlignmentY

public float getLayoutAlignmentY(Container parent)

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

指定者：

接口 LayoutManager2 中的 getLayoutAlignmentY

参数：

parent - 应用此 LayoutManager 的 Container

返回：

对齐方式；此实现返回 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 的字符串表示形式

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