[Chapter 7] 7.7 GridBagConstraints
Author: John Zukowski
Date: Thu Jul 31 14:39:46 1997

#

| Chapter 7 Layouts |

## 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

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