Class FormBuilder

java.lang.Object
com.jgoodies.forms.builder.FormBuilder

public class FormBuilder extends Object
An general purpose form builder that uses the FormLayout to lay out and populate JPanels. It provides the following features:
  • Short code, good readability.
  • Layout and panel building in a single class.
  • Layout construction easier to understand (compared to FormLayout constructors).
  • Implicitly creates frequently used components such as labels.
  • Convenience code for adding button bars, radio button groups, etc.
  • Can add components only if a condition evaluates to true.
  • Toolkit-independent code, see focusTraversalType vs. focusTraversalPolicy.
See also the feature overview below.

The FormBuilder is the working horse for forms and panels where more specialized builders such as the ListViewBuilder or the ButtonBarBuilder are inappropriate. Since FormBuilder supports the frequently used methods for setting up and configuring a FormLayout, the vast majority of forms can be built with just the FormBuilder. In other words, you will typically not work with FormLayout instances directly.

Forms are built as a two-step process: first, you setup and configure the layout, then add the components.

Example: (creates a panel with 3 columns and 3 rows)

 return FormBuilder.create()
     .columns("left:pref, $lcgap, 50dlu, $rgap, default")
     .rows("p, $lg, p, $lg, p")
     .padding(Paddings.DIALOG)
 
     .add("invalid input: '&Title':")   .xy  (1, 1)
     .add(titleField)  .xywh(3, 1, 3, 1)
     .add("invalid input: '&Price':")   .xy  (1, 3)
     .add(priceField)  .xy  (3, 3)
     .add("invalid input: '&Author':")  .xy  (1, 5)
     .add(authorField) .xy  (3, 5)
     .add(browseButton).xy  (5, 5)
     .build();
 
FormBuilder provides convenience methods for adding labels, titles, and titled separators. These components will be created by the builder's component factory that can be set via factory(ComponentFactory), and that is by default initialized from FormsSetup.getComponentFactoryDefault().

The text arguments passed to the methods #addLabel, #addTitle, and #addSeparator can contain an optional mnemonic marker. The mnemonic and mnemonic index are indicated by a single ampersand (&). For example "&Saveinvalid input: '&quot', or "Save &asinvalid input: '&quot'. To use the ampersand itself duplicate it, for example "Look&&Feelinvalid input: '&quot'.

Feature Overview:

     .columns("pref, $lcgap, %sdlu, p, p", "50")  // Format string
     .columnGroup(4, 5)                           // Grouping short hand
     .debug(true)                                 // Installs FormDebugPanel
 
     .add("Title:")         .xy(1, 1)             // Implicitly created label
     .add("invalid input: '&Price':")        .xy(1, 1)             // Label with mnemonic
 
     .add(hasCountry, combo).xy(3, 1)             // Conditional adding
 
     .add(aTable)           .xywh(1, 1, 3, 5)    // Auto-wrapped with scrollpane
     .addScrolled(aTextArea).xywh(1, 1, 1, 3)    // scrollpane shorthand
 
     .addBar(newBtn, editBtn, deleteBtn).xy(1, 5) // button bar
     .addBar(landscapeRadio, portraitRadio).xy(1, 1) // Radio button bar
 
Since:
1.9
See Also:
  • Field Details

    • LABELED_BY_PROPERTY

      private static final String LABELED_BY_PROPERTY
      A JComponent client property that is used to determine the label labeling a component. Copied from the JLabel class.
      See Also:
    • layoutMap

      private LayoutMap layoutMap
    • columnSpecs

      private ColumnSpec[] columnSpecs
    • rowSpecs

      private RowSpec[] rowSpecs
    • layout

      private FormLayout layout
    • panel

      private JPanel panel
    • initialComponent

      private JComponent initialComponent
    • focusTraversalType

      private FocusTraversalType focusTraversalType
    • focusTraversalPolicy

      private FocusTraversalPolicy focusTraversalPolicy
    • debug

      private boolean debug
    • offsetX

      private int offsetX
    • offsetY

      private int offsetY
    • labelForFeatureEnabled

      private boolean labelForFeatureEnabled
      The instance value for the setLabelFor feature. Is initialized using the global default.
      See Also:
      • invalid reference
        #setLabelForFeatureEnabled(boolean)
      • invalid reference
        #setLabelForFeatureEnabledDefault(boolean)
    • defaultLabelType

      private FormBuilder.LabelType defaultLabelType
    • factory

      private ComponentFactory factory
    • mostRecentlyAddedLabelReference

      private WeakReference mostRecentlyAddedLabelReference
      Refers to the most recently added label. Used to invoke JLabel.setLabelFor(java.awt.Component) for the next component added to the panel that is applicable for this feature (for example focusable). After the association has been set, the reference will be cleared.
      See Also:
      • invalid reference
        #add(Component, CellConstraints)
  • Constructor Details

    • FormBuilder

      protected FormBuilder()
  • Method Details

    • create

      public static FormBuilder create()
      Creates and return a new FormBuilder instance.
    • build

      public JPanel build()
      Returns the panel used to build the form. Intended to return the panel in build methods.
      Returns:
      the panel used by this builder to build the form
    • layoutMap

      public FormBuilder layoutMap(LayoutMap layoutMap)
      Configures this builder's FormLayout to use the given layout map for expanding layout variables.

      Example:

       return FormBuilder.create()
           .columns("left:pref, $lcgap, 200dlu")
           .rows("p, $lg, p, $lg, p")
           .layoutMap(aCustomLayoutMap)
           ...
       
      Parameters:
      layoutMap - expands layout column and row variables
      Returns:
      a reference to this builder
    • columns

      public FormBuilder columns(String encodedColumnSpecs, Object... args)
      Configures this builder's layout columns using a comma-separated string of column specifications. The string can be a format string and will then use the optional format arguments, see String.format(String, Object...).

      Examples:

       .columns("left:90dlu, 3dlu, 200dlu")
       .columns("left:90dlu, 3dlu, %sdlu", "200")  // Format string
       .columns("$label, $lcgap, 200dlu")          // Layout variables
       
      Parameters:
      encodedColumnSpecs - a comma-separated list of column specifications
      args - optional format arguments
      Returns:
      a reference to this builder
      See Also:
    • appendColumns

      public FormBuilder appendColumns(String encodedColumnSpecs, Object... args)
      Appends the given columns to this builder's layout. The columns to append are provided as a comma-separated string of column specifications. The string can be a format string and will then use the optional format arguments, see String.format(String, Object...).

      Examples:

       .appendColumns("50dlu, 3dlu, 50dlu")
       .appendColumns("%sdlu, 3dlu, %sdlu", "50")    // Format string
       .appendColumns("$button, $rgap, $button")     // Layout variable
       
      Parameters:
      encodedColumnSpecs - a comma-separated list of column specifications
      args - optional format arguments
      Returns:
      a reference to this builder
      See Also:
    • rows

      public FormBuilder rows(String encodedRowSpecs, Object... args)
      Configures this builder's layout rows using a comma-separated string of row specifications.The string can be a format string and will then use the optional format arguments, see String.format(String, Object...).

      Examples:

       .rows("p, 3dlu, p, 14dlu, p")
       .rows("p, 3dlu, p, %sdlu, p", "14")  // Format string
       .rows("p, $pg, p, $pg, p")           // Layout variables
       
      Parameters:
      encodedRowSpecs - a comma-separated list of row specifications
      args - optional format arguments
      Returns:
      a reference to this builder
      See Also:
    • appendRows

      public FormBuilder appendRows(String encodedRowSpecs, Object... args)
      Appends the given rows to this builder's layout. The rows to append are provided as a comma-separated string of row specifications. The string can be a format string and will then use the optional format arguments, see String.format(String, Object...).

      Examples:

       .appendRows("10dlu, p, 3dlu, p")
       .appendRows("%sdlu, p, 3dlu, p", "10")    // Format string
       .appendRows("10dlu, p, $lg,  p")          // Layout variable
       
      Parameters:
      encodedRowSpecs - a comma-separated list of row specifications
      args - optional format arguments
      Returns:
      a reference to this builder
      See Also:
    • columnGroup

      public FormBuilder columnGroup(int... columnIndices)
      Configures this builder's layout to group (make equally wide) the columns with the given indices.

      Examples:

       .columnGroup(3, 5)
       
      Parameters:
      columnIndices - the indices of the columns to group
      Returns:
      a reference to this builder
    • columnGroups

      public FormBuilder columnGroups(int[]... multipleColumnGroups)
      Configures this builder's layout to group (make equally wide) the columns per array of column indices.

      Examples:

       .columnGroups(new int[]{3, 5}, new int[]{7, 9})
       
      Parameters:
      multipleColumnGroups - multiple arrays of column indices
      Returns:
      a reference to this builder
    • rowGroup

      public FormBuilder rowGroup(int... rowIndices)
      Configures this builder's layout to group (make equally high) the rows with the given indices.

      Examples:

       .rowGroup(3, 5)
       
      Parameters:
      rowIndices - the indices of the rows to group
      Returns:
      a reference to this builder
    • rowGroups

      public FormBuilder rowGroups(int[]... multipleRowGroups)
      Configures this builder's layout to group (make equally wide) the rows per array of row indices.

      Examples:

       .rowGroups(new int[]{3, 5}, new int[]{7, 9})
       
      Parameters:
      multipleRowGroups - multiple arrays of row indices
      Returns:
      a reference to this builder
    • honorsVisibility

      public FormBuilder honorsVisibility(boolean b)
      Specifies whether invisible components shall be taken into account by this builder for computing the layout size and setting component bounds. If set to true invisible components will be ignored by the layout. If set to false components will be taken into account regardless of their visibility. Visible components are always used for sizing and positioning.

      The default value for this setting is true. It is useful to set the value to false (in other words to ignore the visibility) if you switch the component visibility dynamically and want the container to retain the size and component positions.

      Parameters:
      b - true to honor the visibility, i.e. to exclude invisible components from the sizing and positioning, false to ignore the visibility, in other words to layout visible and invisible components
      Returns:
      a reference to this builder
      See Also:
    • honorsVisibility

      public FormBuilder honorsVisibility(JComponent c, boolean b)
      Configures how this builder's layout shall handle the visibility of the given component.
      Parameters:
      c - the component to configure
      b - true to use c for layout computations only if visible, false to take c into account even if invisible
      Returns:
      a reference to this builder
      See Also:
    • layout

      public FormBuilder layout(FormLayout layout)
      Sets layout as the layout to use by this builder.
      Parameters:
      layout - the layout to be used by this builder
      Returns:
      a reference to this builder
    • panel

      public FormBuilder panel(JPanel panel)
      Sets panel as the panel that this builder shall work with.
      Parameters:
      panel - the panel to work with
      Returns:
      a reference to this builder
    • debug

      public FormBuilder debug(boolean b)
      Enables or disables the display of layout debug information. If enabled, the layout grid lines will be painted with red lines. By default the debug mode is disabled.
      Parameters:
      b - true to paint grid lines, false to disable it
      Returns:
      a reference to this builder
      See Also:
    • name

      public FormBuilder name(String panelName)
      Sets the name of the panel this builder works with.
      Parameters:
      panelName - the name to set
      Returns:
      a reference to this builder
    • background

      public FormBuilder background(Color background)
      Sets the panel's background color and the panel to be opaque.
      Parameters:
      background - the color to set as new background
      Returns:
      a reference to this builder
      See Also:
    • border

      public FormBuilder border(Border border)
      Sets the panel's border. If you just want to wrap a panel with white space, use padding(EmptyBorder) instead.
      Parameters:
      border - the border to set
      Returns:
      a reference to this builder
      See Also:
    • border

      @Deprecated public FormBuilder border(String paddingSpec)
      Deprecated.
      Sets the panel's padding as an EmptyBorder using the given specification for the top, left, bottom, right margins in DLU. For example "1dlu, 2dlu, 3dlu, 4dlu" sets a padding with 1dlu in the top, 2dlu in the left side, 3dlu at the bottom, and 4dlu in the right hand side.

      Equivalent to setPadding(Paddings.createPadding(paddingSpec)).

      Parameters:
      paddingSpec - describes the top, left, bottom, right margins of the padding (an EmptyBorder) to use
      Returns:
      a reference to this builder
      See Also:
    • padding

      public FormBuilder padding(EmptyBorder padding)
      Sets the panel's padding, an empty border.
      Parameters:
      padding - the white space around this form
      Returns:
      a reference to this builder
      Since:
      1.9
      See Also:
    • padding

      public FormBuilder padding(String paddingSpec, Object... args)
      Sets the panel's padding as an EmptyBorder using the given specification for the top, left, bottom, right margins in DLU. For example "1dlu, 2dlu, 3dlu, 4dlu" sets an empty border with 1dlu in the top, 2dlu in the left side, 3dlu at the bottom, and 4dlu in the right hand side.

      Equivalent to padding(Paddings.createPadding(paddingSpec, args)).

      Parameters:
      paddingSpec - describes the top, left, bottom, right margins of the padding (an EmptyBorder) to use
      args - optional format arguments, used if paddingSpec is a format string
      Returns:
      a reference to this builder
      Since:
      1.9
      See Also:
    • opaque

      public FormBuilder opaque(boolean b)
      Sets the panel's opaque state.
      Parameters:
      b - true for opaque, false for non-opaque
      Returns:
      a reference to this builder
      See Also:
    • initialComponent

      public FormBuilder initialComponent(JComponent initialComponent)
      Sets a component that should receive the focus when a Window is made visible for the first time. For details see FocusTraversalPolicy.getInitialComponent(java.awt.Window).
      Parameters:
      initialComponent - the component that shall receive the focus
      Returns:
      a reference to this builder
    • focusTraversalType

      public FormBuilder focusTraversalType(FocusTraversalType focusTraversalType)
      Sets either a layout or container order focus traversal policy. If the commercial JGContainerOrderFocusTraversalPolicy and JGLayoutFocusTraversalPolicy are in the class path, these will be used. Otherwise the standard Swing ContainerOrderFocusTraversalPolicy and LayoutFocusTraversalPolicy respectively will be used.
      Parameters:
      focusTraversalType - specifies the type: layout or container order
      Returns:
      a reference to this builder
      Throws:
      NullPointerException - if focusTraversalType is null
      See Also:
    • focusTraversalPolicy

      public FormBuilder focusTraversalPolicy(FocusTraversalPolicy policy)
      Sets the panel's focus traversal policy and sets the panel as focus traversal policy provider. You should favor setting the focus traversal policy type over setting a concrete policy, because the type is toolkit-independent and may be reused if your code is transferred to another toolkit.

      A call to this method is only necessary, if you set a custom Swing focus traversal policy other than LayoutFocusTraversalPolicy or ContainerOrderFocusTraversalPolicy (or their commercial replacements JGLayoutFocusTraversalPolicy or JGContainerOrderFocusTraversalPolicy).

      Call to this method are equivalent to:

       builder.getPanel().setFocusTraversalPolicy(policy);
       builder.getPanel().setFocusTraversalPolicyProvider(true);
       
      Parameters:
      policy - the focus traversal policy that will manage keyboard traversal of the children in this builder's panel
      Returns:
      a reference to this builder
      Throws:
      NullPointerException - if focusTraversalType is null
      See Also:
    • focusGroup

      public FormBuilder focusGroup(AbstractButton... buttons)
      Tries to build a focus group for the given buttons. Within a focus group, focus can be transferred from one group member to another using the arrow keys.

      To succeed, the commercial FocusTraversalUtils class must be in the class path. To make focus grouping work, a focus traversal policy must be set that is capable of transferring focus with the arrow keys such as JGContainerOrderFocusTraversalPolicy or JGLayoutFocusTraversalPolicy.

      Parameters:
      buttons - the buttons to be grouped
      Returns:
      a reference to this builder
    • getPanel

      public JPanel getPanel()
      Returns the panel used to build the form. Intended to access panel properties. For returning the built panel use build() instead.
      Returns:
      the panel used by this builder to build the form
      See Also:
    • factory

      public FormBuilder factory(ComponentFactory factory)
      Sets factory as this builder's new component factory that is used when adding implicitly created components such as labels, titles, or titled separators. If not called, the default factory will be used that can be configured via FormsSetup.setComponentFactoryDefault(ComponentFactory).
      Parameters:
      factory - the factory to be used to create components
      Returns:
      a reference to this builder
    • labelForFeatureEnabled

      public FormBuilder labelForFeatureEnabled(boolean b)
      Enables or disables the setLabelFor feature for this builder. If enabled, a label that has just been added by this builder will be set as the label for the next component added by this builder.

      The value is initialized from the global default value FormsSetup.getLabelForFeatureEnabledDefault(). It is globally disabled by default.

      Parameters:
      b - true for enabled, false for disabled
      Returns:
      a reference to this builder
      See Also:
    • offset

      public FormBuilder offset(int offsetX, int offsetY)
      When adding components, the cell constraints origin are moved along the X and Y axis using an offset as specified by offsetX and offsetY respectively.

      This operation is not cumulative. In other words, setting the offset overrides the previously set offset. For example:

       builder
           .offset(0, 2)
           .offset(1, 3)
           .offset(4, 8)
       
      ends with an offset of (4, 8).
      Parameters:
      offsetX - the distance to move cell constraints along the X axis
      offsetY - the distance to move cell constraints along the Y axis
      Returns:
      a reference to this builder
      See Also:
    • translate

      public FormBuilder translate(int dX, int dY)
      Moves the cell constraints offset along the X and Y axis as specified by dx and dy respectively.

      This operation is cumulative for the offset. In other words, every translation is added to all previously set translations. For example:

      builder
           .offset(0, 0)
           .translate(0, 2)
           .translate(1, 3)
           .translate(4, 8)
      ends with an offset of (5, 13).
      Parameters:
      dX - the distance to move the offset along the X axis
      dY - the distance to move the offset along the Y axis
      Returns:
      a reference to this builder
      See Also:
    • defaultLabelType

      public FormBuilder defaultLabelType(FormBuilder.LabelType newValue)
      Sets a new value for the default label type that is used to determine whether add(String, Object...) delegates to addLabel(String, Object...) or addROLabel(String, Object...).
      Parameters:
      newValue - the default label type
      Returns:
      a reference to this builder
    • add

      The first of two steps for adding a component to this builder's panel. This component will be added, once the cell constraints are specified.

      JTables, JLists, and JTrees will be automatically wrapped by a default JScrollPane. If no scroll pane is desired, use addRaw(Component) instead. If a scroll pane is desired for other components (frequent case are JTextAreas) use addScrolled(Component).

       return FormBuilder.create()
          ...
          .add(nameField)   .xy(1, 1)
          .add(countryCombo).xy(3, 3)
          ...
          .build();
       
      If the label-for-feature is enabled, the most recently added label is tracked and associated with the next added component that is applicable for being set as component for the label.
      Parameters:
      c - the component to add; will be wrapped if it is an instance of JTable, JList, or JTree
      Returns:
      the fluent interface part used to set the cell constraints
      See Also:
    • addRaw

      The first of two steps for adding a component to this builder's panel. This component will be added, once the cell constraints are specified.

      Unlike add(Component), this method won't wrap JTables, JLists, and JTrees automatically with a JScrollPane. Useful for tables, list, and trees that either need no scroll pane, or have another kind of decoration.

       return FormBuilder.create()
          ...
          .addRaw(aTreeThatNeedsNoScrollPane).xy(1, 1)
          ...
          .build();
       
      If the label-for-feature is enabled, the most recently added label is tracked and associated with the next added component that is applicable for being set as component for the label.
      Parameters:
      c - the component to add
      Returns:
      the fluent interface part used to set the cell constraints
      See Also:
    • addScrolled

      public FormBuilder.ComponentAdder addScrolled(Component c)
      The first of two steps for adding the given component wrapped with a JScrollPane to this builder's panel. The wrapped component will be added once the cell constraints have been specified. A frequent case for this method are JTextAreas that shall be scrolled.

      The layout is equivalent to:

       return FormBuilder.create()
          ...
          .add(new JScrollPane(c)).xy(..., ...)
          ...
          .build();
       
      Parameters:
      c - the component to be wrapped and added
      Returns:
      the fluent interface part used to set the cell constraints
    • addBar

      public FormBuilder.ComponentAdder addBar(JButton... buttons)
      The first of two steps for adding a button bar to this builder's panel. This bar will be added, once the cell constraints are specified.

      The buttons will be laid out horizontally in a subpanel, where all buttons use the platform's minimum width. If focus grouping is possible, focus can be transferred between buttons using the arrow keys.

       return FormBuilder.create()
          ...
          .addBar(newButton, editButton, deleteButton).xy(1, 9)
          ...
          .build();
       
      Parameters:
      buttons - the buttons to add
      Returns:
      the fluent interface part used to set the cell constraints
      See Also:
    • addBar

      public FormBuilder.ComponentAdder addBar(JCheckBox... checkBoxes)
      The first of two steps for adding a check box bar to this builder's panel. This bar will be added, once the cell constraints are specified.

      The check boxes will be laid out as a row in a subpanel. If focus grouping is possible, focus can be transferred between the check boxes using the arrow keys.

       return FormBuilder.create()
          ...
          .addBar(visibleBox, editableBox, enabledBox).xy(1, 9)
          ...
          .build();
       
      Parameters:
      checkBoxes - the check boxes to add
      Returns:
      the fluent interface part used to set the cell constraints
      See Also:
    • addBar

      public FormBuilder.ComponentAdder addBar(JRadioButton... radioButtons)
      The first of two steps for adding a radio button bar to this builder's panel. This bar will be added, once the cell constraints are specified.

      The radio buttons will be laid out as a row in a subpanel. If focus grouping is possible, focus can be transferred between the radio buttons using the arrow keys. Also, focus will be transferred to/from the selected radio button of the group - if any.

       return FormBuilder.create()
          ...
          .addBar(verticalRadio, horizontalRadio).xy(1, 9)
          ...
          .build();
       
      Parameters:
      radioButtons - the radio buttons to add
      Returns:
      the fluent interface part used to set the cell constraints
      See Also:
    • addStack

      public FormBuilder.ComponentAdder addStack(JButton... buttons)
      The first of two steps for adding a button stack to this builder's panel. This stack will be added, once the cell constraints are specified.

      The buttons will be laid out vertically in a subpanel, where all buttons use the platform's minimum width. If focus grouping is possible, focus can be transferred between buttons using the arrow keys.

       return FormBuilder.create()
          ...
          .addStack(newButton, editButton, deleteButton).xywh(5, 1, 1, 7)
          ...
          .build();
       
      Parameters:
      buttons - the buttons to add
      Returns:
      the fluent interface part used to set the cell constraints
      See Also:
    • addStack

      public FormBuilder.ComponentAdder addStack(JCheckBox... checkBoxes)
      The first of two steps for adding a check box stack to this builder's panel. This stack will be added, once the cell constraints are specified.

      The check boxes will be laid out vertically in a subpanel. If focus grouping is possible, focus can be transferred between the check boxes using the arrow keys.

       return FormBuilder.create()
          ...
          .addStack(visibleBox, editableBox, enabledBox).xywh(5, 1, 1, 7)
          ...
          .build();
       
      Parameters:
      checkBoxes - the check boxes to add
      Returns:
      the fluent interface part used to set the cell constraints
      See Also:
    • addStack

      public FormBuilder.ComponentAdder addStack(JRadioButton... radioButtons)
      The first of two steps for adding a radio button stack to this builder's panel. This stack will be added, once the cell constraints are specified.

      The radio buttons will be laid out vertically in a subpanel. If focus grouping is possible, focus can be transferred between the check boxes using the arrow keys. Also, focus will be transferred to/from the selected radio button of the group - if any.

       return FormBuilder.create()
          ...
          .addStack(verticalRadio, horizontalRadio).xywh(5, 1, 1, 7)
          ...
          .build();
       
      Parameters:
      radioButtons - the radio buttons to add
      Returns:
      the fluent interface part used to set the cell constraints
      See Also:
    • add

      Builds the given view into this FormBuilder's form.

      Note: This is an experimental feature that is not yet part of the public FormBuilder API. It may change without further notice.

      Parameters:
      view - the view to integrate
      Returns:
      the fluent interface part used to set the view's origin
    • add

      public FormBuilder.ComponentAdder add(String markedLabelText, Object... args)
      The first of two steps for adding a textual label to the form. Equivalent to: addLabel(markedLabelText, args) or addROLabel(markedLabelText, args) depending on the current defaultLabelType. The label will be created and added, once the cell constraints are specified.

       return FormBuilder.create()
          ...
          .add("Name:")      .xy(1, 1) // No Mnemonic
          .add("Ninvalid input: '&ame':")     .xy(1, 1) // Mnemonic is 'a'
          .add("Save invalid input: '&as':")  .xy(1, 1) // Mnemonic is the second 'a'
          .add("Lookinvalid input: '&'invalid input: '&Feel':").xy(1, 1) // No mnemonic, text is "lookinvalid input: '&feel'"
          ...
          .build();
       
      Parameters:
      markedLabelText - the text of the label to be added, may contain an ampersand (&) to mark a mnemonic, and it may be a format string
      args - optional format arguments
      Returns:
      the fluent interface part used to set the cell constraints
      See Also:
    • addLabel

      public FormBuilder.ComponentAdder addLabel(String markedText, Object... args)
      The first of two steps for adding a plain label to the form. The label will be created and added, once the cell constraints are specified.
       return FormBuilder.create()
          ...
          .addLabel("Name:")      .xy(1, 1) // No Mnemonic
          .addLabel("Ninvalid input: '&ame':")     .xy(1, 1) // Mnemonic is 'a'
          .addLabel("Save invalid input: '&as':")  .xy(1, 1) // Mnemonic is the second 'a'
          .addLabel("Lookinvalid input: '&'invalid input: '&Feel':").xy(1, 1) // No mnemonic, text is "lookinvalid input: '&feel'"
          ...
          .build();
       
      Parameters:
      markedText - the label's text - may contain an ampersand (&) to mark a mnemonic, and it may be a format string
      args - optional format arguments
      Returns:
      the fluent interface part used to set the cell constraints
      See Also:
    • addROLabel

      public FormBuilder.ComponentAdder addROLabel(String markedText, Object... args)
      The first of two steps for adding a textual label to the form that is intended for labeling read-only components. The label will be created and added, once the cell constraints are specified.

      The read-only labels created by the default component factory are slightly lighter than plain labels. This makes it easier to differ between the labeling text and the text value that is labeled.

       return FormBuilder.create()
          ...
          .addROLabel("Name:")      .xy(1, 1) // No Mnemonic
          .addROLabel("Ninvalid input: '&ame':")     .xy(1, 1) // Mnemonic is 'a'
          .addROLabel("Save invalid input: '&as':")  .xy(1, 1) // Mnemonic is the second 'a'
          .addROLabel("Lookinvalid input: '&'invalid input: '&Feel':").xy(1, 1) // No mnemonic, text is "lookinvalid input: '&feel'"
          ...
          .build();
       
      Parameters:
      markedText - the label's text - may contain an ampersand (&) to mark a mnemonic, and it may be a format string
      args - optional format arguments
      Returns:
      the fluent interface part used to set the cell constraints
      See Also:
    • addTitle

      public FormBuilder.ComponentAdder addTitle(String markedText, Object... args)
      The first of two steps for adding a title label to the form. The title label will be created and added, once the cell constraints are specified.
       return FormBuilder.create()
          ...
          .addTitle("Name")      .xy(1, 1) // No mnemonic
          .addTitle("Ninvalid input: '&ame'")     .xy(1, 1) // Mnemonic is 'a'
          .addTitle("Lookinvalid input: '&'invalid input: '&Feel'").xy(1, 1) // No mnemonic, text is Lookinvalid input: '&Feel'
          ...
          .build();
       
      Parameters:
      markedText - the title label's text - may contain an ampersand (&) to mark a mnemonic, and it may be a format string
      args - optional format arguments
      Returns:
      the fluent interface part used to set the cell constraints
      See Also:
    • addSeparator

      public FormBuilder.ComponentAdder addSeparator(String markedText, Object... args)
      The first of two steps for adding a titled separator to the form. The separator will be created and added, once the cell constraints are specified.
       return FormBuilder.create()
          ...
          .addSeparator("Name")      .xyw(1, 1, 3) // No Mnemonic
          .addSeparator("Ninvalid input: '&ame'")     .xyw(1, 1, 3) // Mnemonic is 'a'
          .addSeparator("Lookinvalid input: '&'invalid input: '&Feel'").xyw(1, 1, 3) // No mnemonic, text is "lookinvalid input: '&feel'"
          ...
          .build();
       
      Parameters:
      markedText - the separator label's text - may contain an ampersand (&) to mark a mnemonic, and it may be a format string
      args - optional format arguments
      Returns:
      the fluent interface part used to set the cell constraints
      See Also:
    • add

      public FormBuilder.ComponentAdder add(Icon image)
      The first of two steps for adding an icon label to the form. The icon label will be added, once the cell constraints are specified. If image is null, nothing will be added.
      Parameters:
      image - the image to be displayed by the added label
      Returns:
      the fluent interface part used to set the cell constraints
      Since:
      1.9
      See Also:
    • add

      public FormBuilder.ComponentAdder add(boolean expression, Component c)
      The first of two steps for conditionally adding a component to the form. The component will be added, once the cell constraints are specified, but only if expression is true.

      JTables, JLists, and JTrees will be automatically wrapped by a default JScrollPane. If no scroll pane is desired, use addRaw(boolean, Component) instead. If a scroll pane is desired for other components (frequent case are JTextAreas) use addScrolled(boolean, Component).

       return FormBuilder.create()
          ...
          .add(nameField)               .xy(1, 1)
          .add(hasCountry, countryCombo).xy(3, 3)
          ...
          .build();
       
      If the label-for-feature is enabled, the most recently added label is tracked and associate with the next added component that is applicable for being set as component for the label.
      Parameters:
      expression - the precondition for adding the component
      c - the component to add
      Returns:
      the fluent interface part used to set the cell constraints
      See Also:
    • addRaw

      public FormBuilder.ComponentAdder addRaw(boolean expression, Component c)
      The first of two steps for conditionally adding a component to the form. This component will be added, once the cell constraints are specified.

      Unlike add(boolean, Component), this method won't wrap JTables, JLists, and JTrees automatically with a JScrollPane. Useful for tables, list, and trees that either need no scroll pane, or have another kind of decoration.

       return FormBuilder.create()
          ...
          .addRaw(showTree, aTreeThatNeedsNoScrollPane).xy(1, 1)
          ...
          .build();
       
      If the label-for-feature is enabled, the most recently added label is tracked and associated with the next added component that is applicable for being set as component for the label.
      Parameters:
      expression - the precondition for adding the component
      c - the component to add
      Returns:
      the fluent interface part used to set the cell constraints
      See Also:
    • addScrolled

      public FormBuilder.ComponentAdder addScrolled(boolean expression, Component c)
      The first of two steps for conditionally adding the given component wrapped with a JScrollPane to this builder's panel. The wrapped component will be added once the cell constraints have been specified. A frequent case for this method are JTextAreas that shall be scrolled.

      The layout is equivalent to:

       return FormBuilder.create()
          ...
          .add(expression, new JScrollPane(c)).xy(..., ...)
          ...
          .build();
       
      Parameters:
      expression - the precondition for adding the component
      c - the component to be wrapped and added
      Returns:
      the fluent interface part used to set the cell constraints
    • addBar

      public FormBuilder.ComponentAdder addBar(boolean expression, JButton... buttons)
      The first of two steps for conditionally adding a button bar to the form. This bar will be added, once the cell constraints are specified.

      The buttons will be laid out horizontally in a subpanel, where all buttons use the platform's minimum width. If focus grouping is possible, focus can be transferred between buttons using the arrow keys.

       return FormBuilder.create()
          ...
          .addBar(!readOnly, newButton, editButton, deleteButton).xy(1, 9)
          ...
          .build();
       
      Parameters:
      expression - the precondition for adding the bar
      buttons - the buttons to add
      Returns:
      the fluent interface part used to set the cell constraints
      See Also:
    • addBar

      public FormBuilder.ComponentAdder addBar(boolean expression, JCheckBox... checkBoxes)
      The first of two steps for conditionally adding a check box bar to the form. This bar will be added, once the cell constraints are specified.

      The check boxes will be laid out as a row in a subpanel. If focus grouping is possible, focus can be transferred between the check boxes using the arrow keys.

       return FormBuilder.create()
          ...
          .addBar(!readOnly, visibleBox, editableBox, enabledBox).xy(1, 9)
          ...
          .build();
       
      Parameters:
      expression - the precondition for adding the bar
      checkBoxes - the check boxes to add
      Returns:
      the fluent interface part used to set the cell constraints
      See Also:
    • addBar

      public FormBuilder.ComponentAdder addBar(boolean expression, JRadioButton... radioButtons)
      The first of two steps for conditionally adding a radio button bar to this builder's panel. This bar will be added, once the cell constraints are specified.

      The radio buttons will be laid out as a row in a subpanel. If focus grouping is possible, focus can be transferred between the radio buttons using the arrow keys. Also, focus will be transferred to/from the selected radio button of the group - if any.

       return FormBuilder.create()
          ...
          .add   ( readOnly, orientationText)               .xy(1, 9)
          .addBar(!readOnly, verticalRadio, horizontalRadio).xy(1, 9)
          ...
          .build();
       
      Parameters:
      expression - the precondition for adding the bar
      radioButtons - the radio buttons to add
      Returns:
      the fluent interface part used to set the cell constraints
      See Also:
    • addStack

      public FormBuilder.ComponentAdder addStack(boolean expression, JButton... buttons)
      The first of two steps for conditionally adding a button stack to this builder's panel. This stack will be added, once the cell constraints are specified.

      The buttons will be laid out vertically in a subpanel, where all buttons use the platform's minimum width. If focus grouping is possible, focus can be transferred between buttons using the arrow keys.

       return FormBuilder.create()
          ...
          .addStack(!readOnly, newButton, editButton, deleteButton).xywh(5, 1, 1, 7)
          ...
          .build();
       
      Parameters:
      expression - the precondition for adding the stack
      buttons - the buttons to add
      Returns:
      the fluent interface part used to set the cell constraints
      See Also:
    • addStack

      public FormBuilder.ComponentAdder addStack(boolean expression, JCheckBox... checkBoxes)
      The first of two steps for conditionally adding a check box stack to this builder's panel. This stack will be added, once the cell constraints are specified.

      The check boxes will be laid out vertically in a subpanel. If focus grouping is possible, focus can be transferred between the check boxes using the arrow keys.

       return FormBuilder.create()
          ...
          .addStack(!readOnly, visibleBox, editableBox, enabledBox).xywh(5, 1, 1, 7)
          ...
          .build();
       
      Parameters:
      expression - the precondition for adding the stack
      checkBoxes - the check boxes to add
      Returns:
      the fluent interface part used to set the cell constraints
      See Also:
    • addStack

      public FormBuilder.ComponentAdder addStack(boolean expression, JRadioButton... radioButtons)
      The first of two steps for conditionally adding a radio button stack to this builder's panel. This stack will be added, once the cell constraints are specified.

      The radio buttons will be laid out vertically in a subpanel. If focus grouping is possible, focus can be transferred between the check boxes using the arrow keys. Also, focus will be transferred to/from the selected radio button of the group - if any.

       return FormBuilder.create()
          ...
          .addStack(!readOnly, verticalRadio, horizontalRadio).xywh(5, 1, 1, 7)
          ...
          .build();
       
      Parameters:
      expression - the precondition for adding the stack
      radioButtons - the radio buttons to add
      Returns:
      the fluent interface part used to set the cell constraints
      See Also:
    • add

      public FormBuilder.ViewAdder add(boolean expression, FormBuilder.FormBuildingView view)
      Builds the given view into this FormBuilder's form, if expression is true.
      Parameters:
      expression - the precondition for adding the view
      view - the view to integrate
      Returns:
      the fluent interface part used to set the view's origin
    • add

      public FormBuilder.ComponentAdder add(boolean expression, String markedLabelText, Object... args)
      The first of two steps for conditionally adding a textual label to the form. Equivalent to: addLabel(expression, markedLabelText, args) or addROLabel(expression, markedLabelText, args) depending on the current defaultLabelType. The label will be created and added, once the cell constraints are specified.

       return FormBuilder.create()
          ...
          .add(condition, "Name:")      .xy(1, 1) // No Mnemonic
          .add(condition, "Ninvalid input: '&ame':")     .xy(1, 1) // Mnemonic is 'a'
          .add(condition, "Save invalid input: '&as':")  .xy(1, 1) // Mnemonic is the second 'a'
          .add(condition, "Lookinvalid input: '&'invalid input: '&Feel':").xy(1, 1) // No mnemonic, text is "lookinvalid input: '&feel'"
          ...
          .build();
       
      Parameters:
      expression - the precondition for adding the label
      markedLabelText - the text of the label to be added, may contain an ampersand (&) to mark a mnemonic, and it may be a format string
      args - optional format arguments
      Returns:
      the fluent interface part used to set the cell constraints
      See Also:
    • addLabel

      public FormBuilder.ComponentAdder addLabel(boolean expression, String markedText, Object... args)
      The first of two steps for conditionally adding a plain label to the form. The label will be created and added, once the cell constraints are specified.
       return FormBuilder.create()
          ...
          .addLabel(condition, "Name:")      .xy(1, 1) // No Mnemonic
          .addLabel(condition, "Ninvalid input: '&ame':")     .xy(1, 1) // Mnemonic is 'a'
          .addLabel(condition, "Save invalid input: '&as':")  .xy(1, 1) // Mnemonic is the second 'a'
          .addLabel(condition, "Lookinvalid input: '&'invalid input: '&Feel':").xy(1, 1) // No mnemonic, text is "lookinvalid input: '&feel'"
          ...
          .build();
       
      Parameters:
      expression - the precondition for adding the label
      markedText - the label's text - may contain an ampersand (&) to mark a mnemonic, and it may be a format string
      args - optional format arguments
      Returns:
      the fluent interface part used to set the cell constraints
      See Also:
    • addROLabel

      public FormBuilder.ComponentAdder addROLabel(boolean expression, String markedText, Object... args)
      The first of two steps for conditionally adding a textual label to the form that is intended for labeling read-only components. The label will be created and added, once the cell constraints are specified.

      The read-only labels created by the default component factory are slightly lighter than plain labels. This makes it easier to differ between the labeling text and the text value that is labeled.

       return FormBuilder.create()
          ...
          .addROLabel(condition, "Name:")      .xy(1, 1) // No Mnemonic
          .addROLabel(condition, "Ninvalid input: '&ame':")     .xy(1, 1) // Mnemonic is 'a'
          .addROLabel(condition, "Save invalid input: '&as':")  .xy(1, 1) // Mnemonic is the second 'a'
          .addROLabel(condition, "Lookinvalid input: '&'invalid input: '&Feel':").xy(1, 1) // No mnemonic, text is "lookinvalid input: '&feel'"
          ...
          .build();
       
      Parameters:
      expression - the precondition for adding the read-only label
      markedText - the label's text - may contain an ampersand (&) to mark a mnemonic, and it may be a format string
      args - optional format arguments
      Returns:
      the fluent interface part used to set the cell constraints
      See Also:
    • addTitle

      public FormBuilder.ComponentAdder addTitle(boolean expression, String markedText, Object... args)
      The first of two steps for conditionally adding a title label to the form. The title label will be created and added, once the cell constraints are specified.
       return FormBuilder.create()
          ...
          .addTitle(condition, "Name")      .xy(1, 1) // No mnemonic
          .addTitle(condition, "Ninvalid input: '&ame'")     .xy(1, 1) // Mnemonic is 'a'
          .addTitle(condition, "Lookinvalid input: '&'invalid input: '&Feel'").xy(1, 1) // No mnemonic, text is Lookinvalid input: '&Feel'
          ...
          .build();
       
      Parameters:
      expression - the precondition for adding the title
      markedText - the title label's text - may contain an ampersand (&) to mark a mnemonic, and it may be a format string
      args - optional format arguments
      Returns:
      the fluent interface part used to set the cell constraints
      See Also:
    • addSeparator

      public FormBuilder.ComponentAdder addSeparator(boolean expression, String markedText, Object... args)
      The first of two steps for conditionally adding a titled separator to the form. The separator will be created and added, once the cell constraints are specified.
       return FormBuilder.create()
          ...
          .addSeparator(condition, "Name")      .xyw(1, 1, 3) // No Mnemonic
          .addSeparator(condition, "Ninvalid input: '&ame'")     .xyw(1, 1, 3) // Mnemonic is 'a'
          .addSeparator(condition, "Lookinvalid input: '&'invalid input: '&Feel'").xyw(1, 1, 3) // No mnemonic, text is "lookinvalid input: '&feel'"
          ...
          .build();
       
      Parameters:
      expression - the precondition for adding the separator
      markedText - the separator label's text - may contain an ampersand (&) to mark a mnemonic, and it may be a format string
      args - optional format arguments
      Returns:
      the fluent interface part used to set the cell constraints
      See Also:
    • add

      public FormBuilder.ComponentAdder add(boolean expression, Icon image)
      The first of two steps for conditionally adding an icon label to the form. The icon label will be added, once the cell constraints are specified. If image is null, nothing will be added.
      Parameters:
      expression - the precondition for adding the icon
      image - the image to be displayed by the added label
      Returns:
      the fluent interface part used to set the cell constraints
      Since:
      1.9
      See Also:
    • getLayoutMap

      protected LayoutMap getLayoutMap()
    • getLayout

      protected FormLayout getLayout()
    • getFactory

      protected ComponentFactory getFactory()
    • addImpl

      protected FormBuilder.ComponentAdder addImpl(Component c)
    • addImpl

      void addImpl(Component component, CellConstraints rawConstraints)
    • manageLabelsAndComponents

      private void manageLabelsAndComponents(Component c)
    • isLabelForApplicable

      private static boolean isLabelForApplicable(JLabel label, Component component)
      Checks and answers whether the given component shall be set as component for a previously added label using JLabel.setLabelFor(Component). This default implementation checks whether the component is focusable, and - if a JComponent - whether it is already labeled by a JLabel. Subclasses may override.
      Parameters:
      label - the candidate for labeling component
      component - the component that could be labeled by label
      Returns:
      true if focusable, false otherwise
    • setLabelFor

      private static void setLabelFor(JLabel label, Component component)
      Sets label as labeling label for component or an appropriate child. In case of a JScrollPane as given component, this default implementation labels the view of the scroll pane's viewport.
      Parameters:
      label - the labeling label
      component - the component to be labeled, or the parent of the labeled component
    • getMostRecentlyAddedLabel

      private JLabel getMostRecentlyAddedLabel()
      Returns the most recently added JLabel that has a mnemonic set - if any, null, if none has been set, or if it has been cleared after setting an association before, or if it has been cleared by the garbage collector.
      Returns:
      the most recently added JLabel that has a mnemonic set and has not been associated with a component applicable for this feature. null otherwise.
    • setMostRecentlyAddedLabel

      private void setMostRecentlyAddedLabel(JLabel label)
      Sets the given label as most recently added label using a weak reference.
      Parameters:
      label - the label to be set
    • clearMostRecentlyAddedLabel

      private void clearMostRecentlyAddedLabel()
      Clears the reference to the most recently added mnemonic label.
    • isLeftToRight

      private boolean isLeftToRight()
    • checkValidFocusTraversalSetup

      private void checkValidFocusTraversalSetup()
      Checks that if the API user has set a focus traversal policy, no focus traversal type and no initial component has been set.
    • setupFocusTraversalPolicyAndProvider

      private void setupFocusTraversalPolicyAndProvider()