Module java.desktop
Package java.awt

Class GridBagLayout

java.lang.Object
java.awt.GridBagLayout
所有已实现的接口:
LayoutManager, LayoutManager2, Serializable
public class GridBagLayout extends Object implements LayoutManager2, Serializable
GridBagLayout类是一个灵活的布局管理器，可以垂直、水平或沿其基线对齐组件，而无需组件具有相同的大小。每个GridBagLayout对象维护一个动态的矩形单元格网格，每个组件占用一个或多个单元格，称为其显示区域。

每个由GridBagLayout管理的组件都与一个GridBagConstraints实例相关联。约束对象指定组件的显示区域应位于网格上的位置以及组件应如何在其显示区域内定位。除了其约束对象外，GridBagLayout还考虑每个组件的最小和首选大小，以确定组件的大小。

网格的整体方向取决于容器的ComponentOrientation属性。对于水平从左到右的方向，网格坐标（0,0）位于容器的左上角，其中x向右增加，y向下增加。对于水平从右到左的方向，网格坐标（0,0）位于容器的右上角，其中x向左增加，y向下增加。

要有效使用网格包布局，必须自定义与其组件关联的一个或多个GridBagConstraints对象。通过设置其一个或多个实例变量来自定义GridBagConstraints对象：

GridBagConstraints.gridx，GridBagConstraints.gridy
指定包含组件显示区域前角的单元格，其中网格原点处的单元格地址为gridx = 0，gridy = 0。对于水平从左到右的布局，组件的前角是其左上角。对于水平从右到左的布局，组件的前角是其右上角。使用GridBagConstraints.RELATIVE（默认值）指定组件紧跟在此组件之前添加到容器的组件之后（对于gridx沿x轴或gridy沿y轴）的位置。
GridBagConstraints.gridwidth，GridBagConstraints.gridheight
指定组件显示区域中的行数（对于gridwidth）或列数（对于gridheight）。默认值为1。使用GridBagConstraints.REMAINDER指定组件的显示区域将从gridx到行中的最后一个单元格（对于gridwidth）或从gridy到列中的最后一个单元格（对于gridheight）。使用GridBagConstraints.RELATIVE指定组件的显示区域将从gridx到其行中倒数第二个单元格（对于gridwidth）或从gridy到其列中倒数第二个单元格（对于gridheight）。
GridBagConstraints.fill
当组件的显示区域大于组件的请求大小时，用于确定是否（以及如何）调整组件大小。可能的值为GridBagConstraints.NONE（默认值），GridBagConstraints.HORIZONTAL（使组件足够宽以水平填充其显示区域，但不更改其高度），GridBagConstraints.VERTICAL（使组件足够高以垂直填充其显示区域，但不更改其宽度）和GridBagConstraints.BOTH（使组件完全填充其显示区域）。
GridBagConstraints.ipadx，GridBagConstraints.ipady
指定布局内组件的内部填充，要增加组件的最小大小多少。组件的宽度至少为其最小宽度加上ipadx像素。类似地，组件的高度至少为最小高度加上ipady像素。
GridBagConstraints.insets
指定组件的外部填充，即组件与其显示区域边缘之间的最小空间量。
GridBagConstraints.anchor
指定组件在其显示区域中的位置。有三种可能的值：绝对值、方向相关值和基线相关值。方向相关值相对于容器的ComponentOrientation属性进行解释，而绝对值则不是。基线相关值是相对于基线计算的。有效值为：
  • 绝对值：
    • GridBagConstraints.NORTH
    • GridBagConstraints.SOUTH
    • GridBagConstraints.WEST
    • GridBagConstraints.EAST
    • GridBagConstraints.NORTHWEST
    • GridBagConstraints.NORTHEAST
    • GridBagConstraints.SOUTHWEST
    • GridBagConstraints.SOUTHEAST
    • GridBagConstraints.CENTER（默认值）
  • 方向相关值：
    • GridBagConstraints.PAGE_START
    • GridBagConstraints.PAGE_END
    • GridBagConstraints.LINE_START
    • GridBagConstraints.LINE_END
    • GridBagConstraints.FIRST_LINE_START
    • GridBagConstraints.FIRST_LINE_END
    • GridBagConstraints.LAST_LINE_START
    • GridBagConstraints.LAST_LINE_END
  • 基线相关值：
    • GridBagConstraints.BASELINE
    • GridBagConstraints.BASELINE_LEADING
    • GridBagConstraints.BASELINE_TRAILING
    • GridBagConstraints.ABOVE_BASELINE
    • GridBagConstraints.ABOVE_BASELINE_LEADING
    • GridBagConstraints.ABOVE_BASELINE_TRAILING
    • GridBagConstraints.BELOW_BASELINE
    • GridBagConstraints.BELOW_BASELINE_LEADING
    • GridBagConstraints.BELOW_BASELINE_TRAILING
GridBagConstraints.weightx，GridBagConstraints.weighty
用于确定如何分配空间，这对于指定调整大小行为很重要。除非在行（weightx）和列（weighty）中至少为一个组件指定权重，否则所有组件都会聚集在容器的中心。这是因为当权重为零（默认值）时，GridBagLayout对象将任何额外空间放置在其单元格网格和容器边缘之间。

每行可能有一个基线；基线由该行中具有有效基线并沿基线对齐的组件确定（组件的锚值为 BASELINE、BASELINE_LEADING或BASELINE_TRAILING之一）。如果该行中没有组件具有有效基线，则该行没有基线。

如果组件跨越多行，则将其对齐到起始行的基线（如果基线调整行为为 CONSTANT_ASCENT）或结束行的基线（如果基线调整行为为CONSTANT_DESCENT）。组件对齐到的行称为主导行。

以下图显示了一个基线布局，并包括跨越多行的组件：

以下文本描述此图形（图1）。

此布局由三个组件组成：
  • 从第0行开始到第1行结束的面板。该面板具有CONSTANT_DESCENT的基线调整行为，并具有BASELINE的锚点。由于基线调整行为为CONSTANT_DESCENT，面板的主导行为第1行。
  • 两个按钮，每个按钮具有CENTER_OFFSET的基线调整行为和BASELINE的锚点。
因为第二个按钮和面板共享相同的主导行，它们都沿其基线对齐。

使用基线相关值之一定位的组件在调整大小时与使用绝对值或方向相关值定位时的方式不同。组件如何更改取决于主导行的基线如何更改。如果具有相同主导行的任何组件具有CONSTANT_DESCENT的基线调整行为，则基线将锚定在显示区域的底部，否则基线将锚定在显示区域的顶部。以下规则规定了调整大小的行为：

  • 位于基线上方的可调整大小组件只能增长到基线的高度。例如，如果基线在100处并锚定在顶部，位于基线上方的可调整大小组件永远不会增长超过100个单位。
  • 类似地，位于基线下方的可调整大小组件只能增长到显示高度与基线之间的差值。
  • 具有OTHER基线调整行为的位于基线上的组件仅在调整大小时调整，如果调整后的大小的基线适合于显示区域。如果基线不适合于显示区域，则不会调整组件的大小。
  • 位于基线上但没有OTHER基线调整行为的组件只能增长到显示高度 - 基线 + 组件的基线。
如果将组件沿基线定位，但组件没有有效基线，则它将在其空间中垂直居中。类似地，如果将组件相对于基线定位，并且该行中没有组件具有有效基线，则组件将垂直居中。

以下图显示了由网格包布局管理的十个组件（所有按钮）。图2显示了水平从左到右容器的布局，图3显示了水平从右到左容器的布局。

前文描述了此图形（图2）

图2：水平，从左到右

前文描述了此图形（图3）

图3：水平，从右到左


每个十个组件都有其关联的GridBagConstraints对象的fill字段设置为GridBagConstraints.BOTH。此外，这些组件具有以下非默认约束：

  • 按钮1，按钮2，按钮3：weightx = 1.0
  • 按钮4：weightx = 1.0，gridwidth = GridBagConstraints.REMAINDER
  • 按钮5：gridwidth = GridBagConstraints.REMAINDER
  • 按钮6：gridwidth = GridBagConstraints.RELATIVE
  • 按钮7：gridwidth = GridBagConstraints.REMAINDER
  • 按钮8：gridheight = 2，weighty = 1.0
  • 按钮9，按钮10：gridwidth = GridBagConstraints.REMAINDER

这里是实现上述示例的代码：

 import java.awt.*;
 import java.util.*;
 import java.applet.Applet;

 public class GridBagEx1 extends Applet {

     protected void makebutton(String name,
                               GridBagLayout gridbag,
                               GridBagConstraints c) {
         Button button = new Button(name);
         gridbag.setConstraints(button, c);
         add(button);
     }

     public void init() {
         GridBagLayout gridbag = new GridBagLayout();
         GridBagConstraints c = new GridBagConstraints();

         setFont(new Font("SansSerif", Font.PLAIN, 14));
         setLayout(gridbag);

         c.fill = GridBagConstraints.BOTH;
         c.weightx = 1.0;
         makebutton("按钮1", gridbag, c);
         makebutton("按钮2", gridbag, c);
         makebutton("按钮3", gridbag, c);

         c.gridwidth = GridBagConstraints.REMAINDER; //结束行
         makebutton("按钮4", gridbag, c);

         c.weightx = 0.0;                //重置为默认值
         makebutton("按钮5", gridbag, c); //另一行

         c.gridwidth = GridBagConstraints.RELATIVE; //行中倒数第二个
         makebutton("按钮6", gridbag, c);

         c.gridwidth = GridBagConstraints.REMAINDER; //结束行
         makebutton("按钮7", gridbag, c);

         c.gridwidth = 1;                //重置为默认值
         c.gridheight = 2;
         c.weighty = 1.0;
         makebutton("按钮8", gridbag, c);

         c.weighty = 0.0;                //重置为默认值
         c.gridwidth = GridBagConstraints.REMAINDER; //结束行
         c.gridheight = 1;               //重置为默认值
         makebutton("按钮9", gridbag, c);
         makebutton("按钮10", gridbag, c);

         setSize(300, 100);
     }

     public static void main(String args[]) {
         Frame f = new Frame("GridBag布局示例");
         GridBagEx1 ex1 = new GridBagEx1();

         ex1.init();

         f.add("Center", ex1);
         f.pack();
         f.setSize(f.getPreferredSize());
         f.show();
     }
 }
自 JDK 版本:
1.0
参见:

  • Field Details

    • MAXGRIDSIZE

      protected static final int MAXGRIDSIZE
      此字段不再用于保留数组，并保留以确保向后兼容性。以前，这是 GridBag 布局可以布局的最大网格位置数（水平和垂直）。当前实现不对网格的大小施加任何限制。
      参见:

    • MINSIZE

      protected static final int MINSIZE
      GridBag 布局可以布局的最小网格。
      参见:

    • PREFERREDSIZE

      protected static final int PREFERREDSIZE
      GridBag 布局可以布局的首选网格大小。
      参见:

    • comptable

      protected Hashtable<Component,GridBagConstraints> comptable
      此哈希表维护组件与其 GridBag 约束之间的关联。 comptable 中的键是组件，值是 GridBagConstraints 的实例。
      参见:

    • defaultConstraints

      protected GridBagConstraints defaultConstraints
      此字段保存一个包含默认值的 GridBag 约束实例，因此如果组件没有与其关联的 GridBag 约束，则该组件将被分配一个 defaultConstraints 的副本。
      参见:

    • layoutInfo

      protected GridBagLayoutInfo layoutInfo
      此字段保存 GridBag 的布局信息。此字段中的信息基于对 GridBag 的最近验证。如果 layoutInfo 为 null，则表示 GridBag 中没有组件，或者如果有组件，则它们尚未验证。
      参见:

    • columnWidths

      public int[] columnWidths
      此字段保存列最小宽度的覆盖。如果此字段非 null，则在计算所有最小列宽度后将值应用于 GridBag。如果 columnWidths 的元素多于列数，则将添加列以匹配 columnWidth 中元素的数量。
      参见:

    • rowHeights

      public int[] rowHeights
      此字段保存行最小高度的覆盖。如果此字段非 null，则在计算所有最小行高度后将值应用于 GridBag。如果 rowHeights 的元素多于行数，则将添加行以匹配 rowHeights 中元素的数量。
      参见:

    • columnWeights

      public double[] columnWeights
      此字段保存列权重的覆盖。如果此字段非 null，则在计算所有列权重后将值应用于 GridBag。如果 columnWeights[i] > 列 i 的权重，则列 i 将被分配 columnWeights[i] 中的权重。如果 columnWeights 的元素多于列数，则多余的元素将被忽略 - 它们不会导致创建更多列。

    • rowWeights

      public double[] rowWeights
      此字段保存行权重的覆盖。如果此字段非 null，则在计算所有行权重后将值应用于 GridBag。如果 rowWeights[i] > 行 i 的权重，则行 i 将被分配 rowWeights[i] 中的权重。如果 rowWeights 的元素多于行数，则多余的元素将被忽略 - 它们不会导致创建更多行。

  • Constructor Details

    • GridBagLayout

      public GridBagLayout()
      创建一个 GridBag 布局管理器。

  • Method Details

    • setConstraints

      public void setConstraints(Component comp, GridBagConstraints constraints)
      在此布局中为指定的组件设置约束。
      参数:
      comp - 要修改的组件
      constraints - 要应用的约束

    • getConstraints

      public GridBagConstraints getConstraints(Component comp)
      获取指定组件的约束。返回实际 GridBagConstraints 对象的副本。
      参数:
      comp - 要查询的组件
      返回:
      此 GridBag 布局中指定组件的约束；返回实际约束对象的副本

    • lookupConstraints

      protected GridBagConstraints lookupConstraints(Component comp)
      检索指定组件的约束。返回值不是副本，而是布局机制使用的实际 GridBagConstraints 对象。

      如果 comp 不在 GridBagLayout 中，则返回一组默认的 GridBagConstraints。无效的 comp 值为 null，将返回 null。

      参数:
      comp - 要查询的组件
      返回:
      指定组件的约束

    • getLayoutOrigin

      public Point getLayoutOrigin()
      确定布局区域的原点，在目标容器的图形坐标空间中。该值表示布局区域左上角的像素坐标，不考虑容器的ComponentOrientation值。这与由单元格坐标（0,0）给出的网格原点不同。大多数应用程序不直接调用此方法。
      返回：
      单元格在布局网格左上角的图形原点
      自：
      1.1
      另请参见：

    • getLayoutDimensions

      public int[][] getLayoutDimensions()
      确定布局网格的列宽和行高。

      大多数应用程序不直接调用此方法。

      返回：
      包含布局列宽和布局行高的两个数组的数组
      自：
      1.1

    • getLayoutWeights

      public double[][] getLayoutWeights()
      确定布局网格的列和行的权重。权重用于计算给定列或行在布局有额外空间可填充时拉伸多少。

      大多数应用程序不直接调用此方法。

      返回：
      包含布局列的水平权重和布局行的垂直权重的两个数组的数组
      自：
      1.1

    • location

      public Point location(int x, int y)
      确定布局网格中包含由(x, y)指定的点的单元格。每个单元格由其列索引（从0到列数减1）和行索引（从0到行数减1）标识。

      如果(x, y)点位于网格之外，则使用以下规则。如果x位于从左到右的容器的布局左侧或从右到左的容器的布局右侧，则将列索引返回为零。如果x位于从左到右容器的布局右侧或从右到左容器的布局左侧，则将列索引返回为列数。如果y位于布局上方，则将行索引返回为零，如果y位于布局下方，则将行索引返回为行数。容器的方向由其ComponentOrientation属性确定。

      参数：
      x - 点的x坐标
      y - 点的y坐标
      返回：
      指示布局网格中包含点（x, y）的单元格的索引对
      自：
      1.1
      另请参见：

    • addLayoutComponent

      public void addLayoutComponent(String name, Component comp)
      无效果，因为此布局管理器不使用每个组件的字符串。
      指定者：
      addLayoutComponent 在接口 LayoutManager
      参数：
      name - 与组件关联的字符串
      comp - 要添加的组件

    • addLayoutComponent

      public void addLayoutComponent(Component comp, Object constraints)
      将指定的组件添加到布局中，使用指定的constraints对象。请注意，约束是可变的，因此在缓存时会进行克隆。
      指定者：
      addLayoutComponent 在接口 LayoutManager2
      参数：
      comp - 要添加的组件
      constraints - 确定如何将组件添加到布局的对象
      抛出：
      IllegalArgumentException - 如果constraints不是GridBagConstraint

    • removeLayoutComponent

      public void removeLayoutComponent(Component comp)
      从此布局中删除指定的组件。

      大多数应用程序不直接调用此方法。

      指定者：
      removeLayoutComponent 在接口 LayoutManager
      参数：
      comp - 要移除的组件。
      另请参见：

    • preferredLayoutSize

      public Dimension preferredLayoutSize(Container parent)
      使用此网格包布局确定parent容器的首选大小。

      大多数应用程序不直接调用此方法。

      指定者：
      preferredLayoutSize 在接口 LayoutManager
      参数：
      parent - 要进行布局的容器
      返回：
      parent容器的首选大小
      另请参见：

    • minimumLayoutSize

      public Dimension minimumLayoutSize(Container parent)
      使用此网格包布局确定parent容器的最小大小。

      大多数应用程序不直接调用此方法。

      指定者：
      minimumLayoutSize 在接口 LayoutManager
      参数：
      parent - 要进行布局的容器
      返回：
      parent容器的最小大小
      另请参见：

    • maximumLayoutSize

      public Dimension maximumLayoutSize(Container target)
      返回指定目标容器中组件的最大尺寸。
      指定者：
      maximumLayoutSize 在接口 LayoutManager2
      参数：
      target - 需要进行布局的容器
      返回：
      此布局的最大尺寸
      另请参见：

    • getLayoutAlignmentX

      public float getLayoutAlignmentX(Container parent)
      返回沿x轴的对齐方式。这指定组件希望相对于其他组件对齐的方式。该值应为0到1之间的数字，其中0表示沿原点对齐，1表示与原点最远的对齐，0.5表示居中，依此类推。
      指定者：
      getLayoutAlignmentX 在接口 LayoutManager2
      参数：
      parent - 目标容器
      返回：
      值0.5f表示居中

    • getLayoutAlignmentY

      public float getLayoutAlignmentY(Container parent)
      返回沿y轴的对齐方式。这指定组件希望相对于其他组件对齐的方式。该值应为0到1之间的数字，其中0表示沿原点对齐，1表示与原点最远的对齐，0.5表示居中，依此类推。
      指定者：
      getLayoutAlignmentY 在接口 LayoutManager2
      参数：
      parent - 目标容器
      返回：
      值0.5f表示居中

    • invalidateLayout

      public void invalidateLayout(Container target)
      使布局无效，表示如果布局管理器缓存了信息，则应将其丢弃。
      指定者：
      invalidateLayout 在接口 LayoutManager2
      参数：
      target - 目标容器

    • layoutContainer

      public void layoutContainer(Container parent)
      使用此网格包布局对指定的容器进行布局。此方法重新塑造指定容器中的组件，以满足此GridBagLayout对象的约束。

      大多数应用程序不直接调用此方法。

      指定者：
      layoutContainer 在接口 LayoutManager
      参数：
      parent - 要进行布局的容器
      另请参见：

    • toString

      public String toString()
      返回此网格包布局值的字符串表示形式。
      覆盖：
      toString 在类 Object
      返回：
      此网格包布局的字符串表示形式。

    • getLayoutInfo

      protected GridBagLayoutInfo getLayoutInfo(Container parent, int sizeflag)
      填充当前管理的子组件集合的GridBagLayoutInfo实例。这需要通过子组件集合进行三次遍历：
      1. 确定布局网格的尺寸。
      2. 确定组件占据的单元格。
      3. 在行/列之间分配权重和最小尺寸。
      当首次遇到子组件时，还会缓存所有子组件的最小尺寸（因此后续循环不需要再次查询）。

      此方法应仅在GridBagLayout内部使用。

      参数：
      parent - 布局容器
      sizeflag - 可选为PREFERREDSIZE或MINSIZE
      返回值：
      子组件集合的GridBagLayoutInfo实例
      自版本：
      1.4

    • GetLayoutInfo

      protected GridBagLayoutInfo GetLayoutInfo(Container parent, int sizeflag)
      此方法已过时，仅供向后兼容使用；新代码应调用getLayoutInfo。填充当前管理的子组件集合的GridBagLayoutInfo实例。此方法与getLayoutInfo相同；有关详细信息，请参阅getLayoutInfo的描述。
      参数：
      parent - 布局容器
      sizeflag - 可选为PREFERREDSIZE或MINSIZE
      返回值：
      子组件集合的GridBagLayoutInfo实例

    • adjustForGravity

      protected void adjustForGravity(GridBagConstraints constraints, Rectangle r)
      根据约束几何和填充，调整x、y、宽度和高度字段的正确值。此方法应仅在GridBagLayout内部使用。
      参数：
      constraints - 要应用的约束
      r - 要调整的Rectangle
      自版本：
      1.4

    • AdjustForGravity

      protected void AdjustForGravity(GridBagConstraints constraints, Rectangle r)
      根据约束几何和填充，调整x、y、宽度和高度字段的正确值。

      此方法已过时，仅供向后兼容使用；新代码应调用adjustForGravity。此方法与adjustForGravity相同

      参数：
      constraints - 要应用的约束
      r - 要调整的Rectangle

    • getMinSize

      protected Dimension getMinSize(Container parent, GridBagLayoutInfo info)
      根据getLayoutInfo的信息，计算父容器的最小尺寸。此方法应仅在GridBagLayout内部使用。
      参数：
      parent - 布局容器
      info - 此父容器的布局信息
      返回值：
      包含最小尺寸的Dimension对象
      自版本：
      1.4

    • GetMinSize

      protected Dimension GetMinSize(Container parent, GridBagLayoutInfo info)
      此方法已过时，仅供向后兼容使用；新代码应调用getMinSize。此方法与getMinSize相同
      参数：
      parent - 布局容器
      info - 此父容器的布局信息
      返回值：
      包含最小尺寸的Dimension对象

    • arrangeGrid

      protected void arrangeGrid(Container parent)
      布局网格。此方法应仅在GridBagLayout内部使用。
      参数：
      parent - 布局容器
      自版本：
      1.4

    • ArrangeGrid

      protected void ArrangeGrid(Container parent)
      此方法已过时，仅供向后兼容使用；新代码应调用arrangeGrid。此方法与arrangeGrid相同
      参数：
      parent - 布局容器