[Chapter 7] 7.7 GridBagConstraints

7.7 GridBagConstraints

GridBagConstraints are the meat behind the GridBagLayout; they specify how to display components. Unlike other layout managers, which have a built-in idea about what to do with their display, the GridBagLayout is a blank slate. The constraints attached to each component tell the layout manager how to build its display.

Every Component added to a GridBagLayout has a GridBagConstraints object associated with it. When an object is first added to the layout, it is given a default set of constraints (described later in this section). Calling setConstraints() (or add(Component, GridBagConstraints)) applies a new set of constraints to the object. Most people create a helper method to make the setConstraints() calls, passing constraint information as parameters. The helper method used in Example 7.2 follows:

public static void addComponent (Container container, Component component,
    int gridx, int gridy, int gridwidth, int gridheight, int fill,
    int anchor) throws AWTException {
    LayoutManager lm = container.getLayout();
    if (!(lm instanceof GridBagLayout)) {
        throw new AWTException ("Invalid layout" + lm);
    } else {
        GridBagConstraints gbc = new GridBagConstraints ();
        gbc.gridx = gridx;
        gbc.gridy = gridy;
        gbc.gridwidth = gridwidth;
        gbc.gridheight = gridheight;
        gbc.fill = fill;
        gbc.anchor = anchor;
        ((GridBagLayout)lm).setConstraints(component, gbc);
        container.add (component);
    }
}

In Java 1.1, you can make this method slightly cleaner by adding the component and applying the constraints in the same call to add(). To do so, replace the lines calling setConstraints() and add() with this line:

        // Java 1.1 only
        container.add(component, gbc);

GridBagConstraints Methods

Constants and variables

public int anchor

The anchor specifies the direction in which the component will drift in the event that it is smaller than the space available for it. CENTER is the default. Others available are NORTH, SOUTH, EAST, WEST, NORTHEAST, NORTHWEST, SOUTHEAST, and SOUTHWEST.

public final static int CENTER public final static int EAST public final static int NORTH public final static int NORTHEAST public final static int NORTHWEST public final static int SOUTH public final static int SOUTHEAST public final static int SOUTHWEST public final static int WEST

Constants used to set the anchor.

public int fill

The value of fill controls the component's resize policy. If fill is NONE (the default), the layout manager tries to give the component its preferred size. If fill is VERTICAL, it resizes in height if additional space is available. If fill is HORIZONTAL, it resizes in width. If fill is BOTH, the layout manager takes advantage of all the space available in either direction. Figure 7.11 demonstrates VERTICAL (A), HORIZONTAL (B), and NONE (C) values; Figure 7.8 demonstrated the use of BOTH.

public final static int NONE public final static int BOTH public final static int HORIZONTAL public final static int VERTICAL

Constants used to set fill.

Figure 7.11: GridBagLayout with fill values of VERTICAL, HORIZONTAL, and NONE

[Graphic: Figure 7-11]

public int gridx public int gridy

The gridx and gridy variables specify the grid position where this component will be placed. (0,0) specifies the cell at the origin of the screen. Table 7.2 shows the gridx and gridy values for the screen in Figure 7.8.

It isn't necessary to set gridx and gridy to a specific location; if you set these fields to RELATIVE (the default), the system calculates the location for you. According to the comments in the source code, if gridx is RELATIVE, the component appears to the right of the last component added to the layout. If gridy is RELATIVE, the component appears below the last component added to the layout. However, this is misleadingly simple. RELATIVE placement works best if you are adding components along a row or a column. In this case, there are four possibilities to consider:

gridx and gridy RELATIVE: components are placed in one row.
gridx RELATIVE, gridy constant: components are placed in one row, each to the right of the previous component.
gridx constant, gridy RELATIVE: components are placed in one column, each below the previous component.
Varying gridx or gridy while setting the other field to RELATIVE appears to start a new row, placing the component as the first element in the row.

public int gridwidth public int gridheight

gridwidth and gridheight set the number of rows (gridwidth) and columns (gridheight) a particular component occupies. If gridwidth or gridheight is set to REMAINDER, the component will be the last element of the row or column occupying any space that's remaining. Table 7.2 shows the gridwidth and gridheight values for the screen in Figure 7.8. For the components in the last column, the gridwidth values could be REMAINDER. Likewise, gridheight could be set to REMAINDER for the components in the last row.

gridwidth and gridheight may also have the value RELATIVE, which forces the component to be the next to last component in the row or column. Looking back to Figure 7.8: if button six has a gridwidth of RELATIVE, button seven won't appear because button five is the last item in the row, and six is already next to last. If button five has a gridheight of RELATIVE, the layout manager will reserve space below it, so the button can be the next to last item in the column.

public final static int RELATIVE

Constant used for gridx and gridy to request relative placement, and by gridheight and gridwidth to specify the next to last component in a column or row. The behavior of RELATIVE placement can be very counter intuitive; in most cases, you will be better off specifying gridx, gridy, gridheight, and gridwidth explicitly.

public final static int REMAINDER

Constant used for gridwidth and gridheight, to specify that a component should fill the rest of the row or column.

Table 7.2: Demonstrating gridx/gridy/gridwidth/gridheight
Component	gridx	gridy	gridwidth	gridheight
One	0	0	1	1
Two	1	0	1	1
Three	2	0	1	1
Four	0	1	2	1
Five	2	1	1	2
Six	0	2	1	1
Seven	1	2	1	3

public Insets insets

The insets field specifies the external padding in pixels around the component (i.e., between the component and the edge of the cell, or cells, allotted to it). An Insets object can specify different padding for the top, bottom, left, and right sides of the component.

public int ipadx public int ipady

ipadx and ipady specify the internal padding within the component. ipadx specifies the extra space to the right and left of the component (so the minimum width increases by 2*ipadx pixels). ipady specifies the extra space above and below the component (so the minimum height increases by 2*ipady pixels).

The difference between insets (external padding) and the ipadx, ipady variables (internal padding) is confusing. The insets don't add space to the component itself; they are external to the component. ipadx and ipady change the component's minimum size, so they do add space to the component itself.

public double weightx public double weighty

The weightx and weighty variables describe how to distribute any additional space within the container. They allow you to control how components grow (or shrink) when the user resizes the container. If weightx is 0, the component won't get any additional space available in its row. If one or more components in a row have weightx values greater than 0, any extra space is distributed proportionally between them. For example, if one component has a weightx value of 1 and the others are all 0, that one component will get all the additional space. If four components in a row each have weightx values of 1 and the other components have weightx values of 0, the four components each get one quarter of the additional space. weighty behaves similarly. Because weightx and weighty control the distribution of extra space in any row or column, setting either for one component may affect the position of other components.

Constructors

public GridBagConstraints (): The constructor creates a GridBagConstraints object in which all the fields have their default values. These defaults are shown in the Table 7.3.

Table 7.3: GridBagConstraints Defaults.
Variable	Value	Description
`anchor`	`CENTER`	If the component is smaller than the space available, it will be centered within its region.
`fill`	`NONE`	The component should not resize itself if extra space is available within its region.
`gridx`	`RELATIVE`	The component associated with this constraint will be positioned relative to the last item added. If all components have `gridx` and `gridy` `RELATIVE`, they will be placed in a single row.
`gridy`	`RELATIVE`	The component associated with this constraint will be positioned relative to the last item added.
`gridwidth`	`1`	The component will occupy a single cell within the layout.
`gridheight`	`1`	The component will occupy a single cell within the layout.
`insets`	`0x0x0x0`	No extra space is added around the edges of the component.
`ipadx`	`0`	There is no internal padding for the component.
`ipady`	`0`	There is no internal padding for the component.
`weightx`	`0`	The component will not get any extra space, if it is available.
`weighty`	`0`	The component will not get any extra space, if it is available.

Miscellaneous methods

public Object clone (): The clone() method creates a clone of the GridBagConstraints so the same GridBagConstraints object can be associated with multiple components.


GridBagLayout		Combining Layouts