:: Tutorial :: Building ::

Layout managers have been designed to talk to a container, not a human. The Forms framework separates concerns: the layout task from the layout specification and the panel building process. Therefore Forms provies a set of non-visual builder classes that assist you in building panels and that can shield you from details of the layout manager.

When constructing a panel you talk to a builder which in turn talks to the layout manager. This leads to a smaller layout manager API and to more flexibility. The builders that ship with the Forms can create frequently used components, provide a cursor to keep track of the grid location where the next component will be added, and they can assist you in style guide compliance.

It is recommended to have the JGoodies Forms Demo open on your screen!

Plain Building

You can use the pure FormLayout without any builders. It is good style to use a builder, because you often write less code and so increase the code readability.

PanelBuilder

The PanelBuilder is a general purpose builder for many types of Swing panels. It is recommend for building panels that cannot be build well with a specialized builder like the ButtonBarBuilder or DefaultFormBuilder. Typically you specify the columns and rows before you add the components. If the panel has many rows, consider using a row variable to address the current row.

Row Counter

If your layout has rows, hard-coded row numbers become difficult to maintain - at least if you often add and remove rows. You can introduce a variable to track the current row. Since this style makes the code harder to understand, you should use row variables judiscously.

Dynamic Rows

Almost always columns should be defined statically; they describe the essence of form-oriented grids. In contrast, forms have often quite simple row structures: just a sequence of component rows and gap rows like pref, 3dlu, pref, 3dlu, pref, ... In this case you may consider creating the rows dynamically. Use this style judicously, because it makes the layout harder to understand for other readers.

DefaultFormBuilder

The DefaultFormBuilder builds consistent forms quickly. It combines frequently used panel building steps: add a new row, add a label, proceed to the next data column, then add a component. Typically you specify the columns statically and use the builder's #append methods to create the rows on-the-fly. This saves a lot of code and works well with a large set of editors and viewers. However, use this builder only if appropriate; your code should not be cluttered by builder commands.

Custom Rows and DefaultFormBuilder

All builders allow to append rows dynamically. If you create rows dynamically with the DefaultFormBuilder there are basically three ways to add custom rows. Such rows are required for components that grow or that are larger than the default rows. You can add: 1) a single custom row (plus gap before), 2) a standard row plus custom row, or 3) multiple standard rows. These approaches differ in the way, labels and components will be aligned, and in the flexibility available for the alignment in the custom row.

Indent Column and DefaultFormBuilder

It is good design practice to indicate panel sections with a leading indent for all component rows, not the separators. The DefaultFormBuilder provides a method #setLeadingColumnOffset(int) that allows to specify that the components added by the builder should leave out the first offset columns - which is often 1.

Debugging a Panel Layout

The classes FormDebugPanel and FormDebugUtils can help you debug a panel layout implementation. The debug panel paints lines to mark the columns and rows. The debug utils print detailed information about the column and row specifications, column and row groups, component constraints and the grid bounds. The printed information 'unfold' all implicit specifications for column and row specifications, and default alignments that have been applied to individual cells.

ButtonBarBuilder

The ButtonBarBuilder builds consistent button bars that comply with style guides. It ensures minimum widths, uses logical gaps for related and unrelated buttons, and allows to add gridded and ungridded buttons - with default or narrow margins.

ButtonStackBuilder

The ButtonStackBuilder builds consistent button stacks that comply with style guides. It ensures minimum widths, uses logical gaps for related and unrelated buttons, and allows to add gridded and ungridded buttons - with default or narrow margins.