Module is.codion.swing.common.ui
Package is.codion.swing.common.ui.component.panel

Interface FormBuilder<B extends FormBuilder<B>>

Type Parameters:
B - the builder type
All Superinterfaces:
ComponentBuilder<JPanel,B>, Supplier<JPanel>
All Known Implementing Classes:
DefaultFormBuilder, EditorComponents.ComponentFactory.AttributeFormBuilder
public interface FormBuilder<B extends FormBuilder<B>> extends ComponentBuilder<JPanel,B>
Builds a form panel, laying out label/input pairs in rows, the label beside its input.

A form is a sequence of rows; a row is either columns(int) label/input pairs or one full-width component, see span(JComponent); the label column of each pair column is as wide as its widest label; the input columns absorb the horizontal slack, equally. Anything beyond that, nesting, percentage widths, per-cell insets, row spans, is not a form but a hand-written GridBagLayout.

A label aligns with the baseline of its input, or with its top in case the input has no baseline, such as a panel, and is hidden along with it. An input stretches to the height of its row, unless its baseline would move along with its height, as with single line inputs, such as text fields, which keep their height.

The form does not grow vertically, extra height staying below the last row, so a component which should absorb the vertical slack, such as a text area, belongs outside the form, in the center of a BorderLayout with the form to the north.

Focus traversal follows the geometry, right then down, which is correct for pair columns. For down then across, lay out one form per column, side by side, each a focus traversal policy provider with a ContainerOrderFocusTraversalPolicy.

See Also:

  • Method Details

    • columns

      B columns(int columns)
      Parameters:
      columns - the number of label/input pairs per row, default 1
      Returns:
      this builder instance
      Throws:
      IllegalArgumentException - in case columns is less than 1

    • labelAlignment

      B labelAlignment(int labelAlignment)
      Parameters:
      labelAlignment - the horizontal alignment of the labels within the label column, SwingConstants.LEADING (default) or SwingConstants.TRAILING
      Returns:
      this builder instance
      Throws:
      IllegalArgumentException - in case of an alignment other than LEADING or TRAILING

    • add

      B add(JComponent component)
      Adds a label/input pair, the label being the one associated with the component via JLabel.setLabelFor(java.awt.Component), if any, otherwise the component occupies the input column alone, the label cell empty.
      Parameters:
      component - the input component
      Returns:
      this builder instance

    • add

      B add(Supplier<? extends JComponent> component)
      Adds a label/input pair, the label being the one associated with the component via JLabel.setLabelFor(java.awt.Component), if any, otherwise the component occupies the input column alone, the label cell empty.
      Parameters:
      component - the input component
      Returns:
      this builder instance

    • add

      B add(JComponent label, JComponent component)
      Adds a label/input pair. A JLabel carrying no association of its own is associated with the component, so that its mnemonic focuses it.
      Parameters:
      label - the label
      component - the input component
      Returns:
      this builder instance

    • add

      B add(Supplier<? extends JComponent> label, Supplier<? extends JComponent> component)
      Adds a label/input pair. A JLabel carrying no association of its own is associated with the component, so that its mnemonic focuses it.
      Parameters:
      label - the label
      component - the input component
      Returns:
      this builder instance

    • span

      B span(JComponent component)
      Adds a component occupying a row of its own. A label associated with the component keeps the label column, the component spanning the rest of the row, otherwise the component spans the full width.
      Parameters:
      component - the component
      Returns:
      this builder instance

    • span

      B span(Supplier<? extends JComponent> component)
      Adds a component occupying a row of its own. A label associated with the component keeps the label column, the component spanning the rest of the row, otherwise the component spans the full width.
      Parameters:
      component - the component
      Returns:
      this builder instance

    • builder

      static <B extends FormBuilder<B>> FormBuilder<B> builder()
      Type Parameters:
      B - the builder type
      Returns:
      a new FormBuilder