GridBag Constraints property editor

When you use the UI Designer to create a GridBagLayout container, JBuilder automatically instantiates a GridBagConstraints2 object for each component you add to the container. It uses default constraint values, and/or values calculated about existing components during conversion from another layout (like XYLayout) to GridBagLayout. The GridBag Constraints property editor allows you to edit these constraints.

You can access the GridBag Constraints property editor from two places:

Each constraint in the property editor directly corresponds to a constraint from the GridBagConstraints2.class as specified below.

For more detailed information on GridBagLayout and its constraints, see the GridBagLayout topic in Building Applications with JBuilder.

Grid Position

X and Y

Use the Grid Position constraints X (gridx) and Y (gridy) to specify the grid cell location for the upper left corner of component. This constraint value is an integer representing the cell number in a column or row. For example, gridx=0 is the first column on the left, and gridy=0 is the first row at the top. Therefore, a component with the constraints gridx=0 and gridy=0 is placed in the first cell of the grid (top left).

There is an additional constraint value that can be used for gridx and gridy called RELATIVE (the default value). RELATIVE specifies that the component be placed relative to the previous component as follows:

To specify a RELATIVE value for Grid Position X or Y in the Constraints property editor, enter -1.

Width and Height

Use the Grid Position constraints Width (gridwidth) and Height (gridheight) to specify the number of cells in a row (gridwidth) or column (gridheight) the component uses. This constraint value is an integer representing the number of cells in a column or row, not the number of pixels.

There are two additional constraint values that can be used for gridwidth and gridheight: RELATIVE and REMAINDER.

RELATIVE specifies that this component is the next to last one in the row (gridwidth) or column (gridheight). A component using RELATIVE takes all the remaining cells except the last one. For example, in a row of six columns, if the component starts in the third column, a gridwidth of RELATIVE will make it take up columns three, four, and five.

REMAINDER specifies that this component is the last one in the row (gridwidth) or column (gridheight

External Insets

Use External Insets (insets) to specify (in pixels) the minimum amount of external space (padding) between the component and the edges of its display area. You can specify a value for each edge of the component separately: top, left, bottom, and right.

Size Padding

Size Padding specifies the internal padding for a component. Use Width (ipadx) and Height (ipady) to specify (in pixels) the amount of space to add to the minimum size of the component for internal padding.

The width of the component will be at least its minimum width plus ipadx in pixels. (In spite of the fact that the Javadoc comments say ipadx*2, the actual code only adds it once.) Similarly, the height of the component will be at least the minimum height plus ipady pixels.

Example:

When added to a component that is 30 pixels wide and 20 pixels high:

Width

Width (ipadx) specifies the number of pixels to add to the minimum width of the component.

Height

Height (ipady) specifies the number of pixels to add to the minimum height of the component.

Weight

Use the Weight constraints to specify how to distribute the extra container space vertically (weightx) and horizontally (weighty) when the container is resized. Weights determine what share of extra space each component gets when the container is enlarged beyond its default size.

For example, if you have three components with weights of 0.0, 0.3, and 0.2 respectively, when the container is enlarged, none of the extra space will go to the first component, 3/5 of it will go the second component, and 2/5 of it will go to the third.

Note: If all the components have weights of zero in a single direction, the components will clump together in the center of the container for that dimension and won't expand beyond their preferred size. GridBagLayout puts any extra space between its grid of cells and the edges of the container.

Weight values are of type double and are specified numerically in the range 0.0 to 1.0 inclusive. Zero means the component should not receive any of the extra space, and 1.0 means component gets a full share of the space.

X

The Weight constraint X (weightx) is the vertical weight distribution for a component. The weight of a row is calculated to be the maximum weightx of all the components in the row.

Y

The Weight constraint Y (weighty) is the horizontal weight distribution for a component. The weight of a column is calculated to be the maximum weighty of all the components in the column.

For more details and tips on using Weight constraints, see the GridBagLayout topic in Building Applications with JBuilder.

Anchor

When the component is smaller than its display area, use the anchor constraint to tell the layout manager where to place the component within the area. Anchor only affects the component within its own display area, depending on the fill constraint for the component.

For example, if the fill constraint value for a component is BOTH (fill the display area both horizontally and vertically), the anchor constraint has no effect because the component takes up the entire available area. For the anchor constraint to have an effect, set the fill constraint value to NONE, HORIZONTAL, or VERTICAL.

The values for Anchor are as follows:

NW (NORTHWEST) N (NORTH) NE (NORTHEAST)
W (WEST) C (CENTER) E (EAST)
SW (SOUTHWEST) S (SOUTH) SE (SOUTHEAST)

Fill

When the component's display area is larger than the component's requested size, use the fill constraint to tell the layout manager if the component needs to be resized, and if so, how. As with the anchor constraint, the fill constraint only affects the component within its own display area. Fill tells the layout manager to expand the component to fill the whole area it has been given.

The values for Fill are as follows:

None Don't change the size of the component
Horizontal Only resize the component to fill the area horizontally.
Vertical Only resize the component to fill the area vertically.
Both Resize the component both horizontally and vertically to fill the area completely.