The JavaTM Tutorial

| Start of Tutorial > Start of Trail > Start of Lesson | Search Feedback Form

Trail: Creating a GUI with JFC/Swing
Lesson: Laying Out Components Within a Container

## How to Use GridBagLayout: Specifying Constraints

> The following code is typical of what goes in a container that uses a `GridBagLayout`. You'll see a more detailed example in the next section.

> >     GridBagLayout gridbag = new GridBagLayout();
> >     GridBagConstraints c = new GridBagConstraints();

> >     JPanel pane = new JPanel();
> >     pane.setLayout(gridbag);

> >     //For each component to be added to this container:
> >     //...Create the component...
> >     //...Set instance variables in the GridBagConstraints instance...
> >     gridbag.setConstraints(theComponent, c);
> >     pane.add(theComponent);

> As you might have guessed from the above example, you can reuse the same `GridBagConstraints` instance for multiple components, even if the components have different constraints. The `GridBagLayout` extracts the constraint values and doesn't use the `GridBagConstraints` again. You must be careful, however, to reset the `GridBagConstraints` instance variables to their default values when necessary.

> You can set the following `GridBagConstraints` instance variables:

> `gridx`, `gridy`
>   Specify the row and column at the upper left of the component. The leftmost column has address `gridx=0` and the top row has address `gridy=0`. Use `GridBagConstraints.RELATIVE` (the default value) to specify that the component be placed just to the right of (for `gridx`) or just below (for `gridy`) the component that was added to the container just before this component was added. We recommend specifying the `gridx` and `gridy` values for each component; this tends to result in more predictable layouts.

> `gridwidth`, `gridheight`
>   Specify the number of columns (for `gridwidth`) or rows (for `gridheight`) in the component's display area. These constraints specify the number of cells the component uses, not the number of pixels it uses. The default value is 1. Use `GridBagConstraints.REMAINDER` to specify that the component be the last one in its row (for `gridwidth`) or column (for `gridheight`). Use `GridBagConstraints.RELATIVE` to specify that the component be the next to last one in its row (for `gridwidth`) or column (for `gridheight`).

>   Note: `GridBagLayout` doesn't allow components to span multiple rows unless the component is in the leftmost column or you've specified positive `gridx` and `gridy` values for the component.

> `fill`
>   Used when the component's display area is larger than the component's requested size to determine whether and how to resize the component. Valid values (defined as `GridBagConstraints` constants) are `NONE` (the default), `HORIZONTAL` (make the component wide enough to fill its display area horizontally, but don't change its height), `VERTICAL` (make the component tall enough to fill its display area vertically, but don't change its width), and `BOTH` (make the component fill its display area entirely).

> `ipadx`, `ipady`
>   Specifies the internal padding: how much to add to the minimum size of the component. The default value is zero. The width of the component will be at least its minimum width plus `ipadx*2` pixels, since the padding applies to both sides of the component. Similarly, the height of the component will be at least its minimum height plus `ipady*2` pixels.

> `insets`
>   Specifies the external padding of the component -- the minimum amount of space between the component and the edges of its display area. The value is specified as an `Insets` object. By default, each component has no external padding.

> `anchor`
>   Used when the component is smaller than its display area to determine where (within the area) to place the component. Valid values (defined as `GridBagConstraints` constants) are `CENTER` (the default), `NORTH`, `NORTHEAST`, `EAST`, `SOUTHEAST`, `SOUTH`, `SOUTHWEST`, `WEST`, and `NORTHWEST`.

> `weightx`, `weighty`
>   Specifying weights is an art that can have a significant impact on the appearance of the components a `GridBagLayout` controls. Weights are used to determine how to distribute space among columns (`weightx`) and among rows (`weighty`); this is important for specifying resizing behavior.

>   Unless you specify at least one nonzero value for `weightx` or `weighty`, all the components clump together in the center of their container. This is because when the weight is 0.0 (the default), the `GridBagLayout` puts any extra space between its grid of cells and the edges of the container.

>   Generally weights are specified with 0.0 and 1.0 as the extremes: the numbers in between are used as necessary. Larger numbers indicate that the component's row or column should get more space. For each column, the weight is related to the highest `weightx` specified for a component within that column, with each multicolumn component's weight being split somehow between the columns the component is in. Similarly, each row's weight is related to the highest `weighty` specified for a component within that row. Extra space tends to go toward the rightmost column and bottom row.

> The next section discusses constraints in depth, in the context of explaining how the example program works.

| Start of Tutorial > Start of Trail > Start of Lesson | Search Feedback Form