Grid Layout in Java Swing

Many graphical programs need a row that pairs a short caption with an input box. A common example is a label that says x = followed by a box where the user types a number. On the screen this looks like one line of text. In Swing, however, the way you arrange components decides whether that line can be built with a grid layout at all. A single row that seems to contain two items can be built correctly, but only when you understand the rule the layout imposes on each position.

The natural instinct is to treat a grid as a table where each cell can hold whatever you give it. If the first row needs a label and a text field, you would expect to add both directly to the grid and see them sit side by side. That belief is the misconception this article addresses. Before reading on, make a prediction about what the first cell can hold.

A grid layout divides its container into rows and columns of positions, and it assigns each component to exactly one position. The rule that each position holds exactly one component is what makes the layout predictable. Every component has a known place, and no two components compete for the same place. Because the rule is strict, a row that needs two visual pieces cannot put both pieces into one position. The grid would see two components in one place, which breaks the rule.

The diagram shows how the grid walks through its positions and assigns each one component. Position 1 in row 1 holds one item. In this article that item is a subpanel, which is a container that holds the label and the text field. Position 2 holds a separate single component. Every position is filled by one component, and a second component cannot be assigned to a position that is already occupied.

The solution follows directly from the rule. You create a new panel, add the label and the text field to that panel, and then add that panel to the main panel. The main panel's grid sees only the new panel in the first row position. The label and the text field are both still visible on screen, but they are grouped inside the subpanel instead of competing for the grid cell.

The before side shows two components claiming one position, which the grid rejects. The after side shows one subpanel occupying the position, and the label and text field are both inside it. The grid now sees a single component, which satisfies its rule, while the two pieces remain together as a unit.

Reading the containment structure from the main panel down to the leaf components shows which container is responsible for each component. A leaf component is one that holds nothing else, such as the label or the text field. When a layout does not look the way you expected, tracing this chain is the fastest way to find the problem, because it tells you which container placed each piece.

The same path reading works for any depth of nesting. Each container is responsible for its direct children, so when you check a component you ask which panel holds it and which panel holds that panel, all the way up to the main panel.

Notice that the pattern does not depend on what the components are. Whether the pair is a label and a text field or a caption and a button, the containment structure is the same. One subpanel stands in for the position, and the subpanel holds the pieces that belong together.