Class FormBuilder


  • public class FormBuilder
    extends java.lang.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("&Title:")   .xy  (1, 1)
         .add(titleField)  .xywh(3, 1, 3, 1)
         .add("&Price:")   .xy  (1, 3)
         .add(priceField)  .xy  (3, 3)
         .add("&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 "&Save", or "Save &as". To use the ampersand itself duplicate it, for example "Look&&Feel".

    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("&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:
    FormLayout
    • Field Detail

      • LABELED_BY_PROPERTY

        private static final java.lang.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:
        Constant Field Values
      • rowSpecs

        private RowSpec[] rowSpecs
      • panel

        private javax.swing.JPanel panel
      • initialComponent

        private javax.swing.JComponent initialComponent
      • focusTraversalPolicy

        private java.awt.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:
        #setLabelForFeatureEnabled(boolean), #setLabelForFeatureEnabledDefault(boolean)
      • mostRecentlyAddedLabelReference

        private java.lang.ref.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:
        #add(Component, CellConstraints)
    • Constructor Detail

      • FormBuilder

        protected FormBuilder()
    • Method Detail

      • create

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

        public javax.swing.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​(java.lang.String encodedColumnSpecs,
                                   java.lang.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:
        ColumnSpec
      • appendColumns

        public FormBuilder appendColumns​(java.lang.String encodedColumnSpecs,
                                         java.lang.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:
        ColumnSpec
      • rows

        public FormBuilder rows​(java.lang.String encodedRowSpecs,
                                java.lang.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:
        RowSpec
      • appendRows

        public FormBuilder appendRows​(java.lang.String encodedRowSpecs,
                                      java.lang.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:
        RowSpec
      • 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:
        FormLayout.setHonorsVisibility(boolean)
      • honorsVisibility

        public FormBuilder honorsVisibility​(javax.swing.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:
        FormLayout.setHonorsVisibility(Component, Boolean)
      • 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​(javax.swing.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:
        FormDebugPanel
      • name

        public FormBuilder name​(java.lang.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​(java.awt.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:
        JComponent.setBackground(Color)
      • border

        public FormBuilder border​(javax.swing.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:
        padding(EmptyBorder), JComponent.setBorder(Border)
      • border

        @Deprecated
        public FormBuilder border​(java.lang.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:
        Paddings.createPadding(String, Object...)
      • padding

        public FormBuilder padding​(javax.swing.border.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:
        border(javax.swing.border.Border)
      • padding

        public FormBuilder padding​(java.lang.String paddingSpec,
                                   java.lang.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:
        padding(EmptyBorder), Paddings.createPadding(String, Object...)
      • 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:
        JComponent.setOpaque(boolean)
      • initialComponent

        public FormBuilder initialComponent​(javax.swing.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:
        java.lang.NullPointerException - if focusTraversalType is null
        See Also:
        focusTraversalPolicy(FocusTraversalPolicy)
      • focusTraversalPolicy

        public FormBuilder focusTraversalPolicy​(java.awt.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:
        java.lang.NullPointerException - if focusTraversalType is null
        See Also:
        focusTraversalType(FocusTraversalType), Container.setFocusTraversalPolicy(FocusTraversalPolicy), Container.setFocusTraversalPolicyProvider(boolean)
      • focusGroup

        public FormBuilder focusGroup​(javax.swing.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 javax.swing.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:
        build()
      • 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:
        JLabel.setLabelFor(Component)
      • 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(int, int)
      • 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:
        offset(int, int)
      • add

        public FormBuilder.ComponentAdder add​(java.awt.Component c)
        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:
        isLabelForApplicable(JLabel, Component)
      • addRaw

        public FormBuilder.ComponentAdder addRaw​(java.awt.Component c)
        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:
        isLabelForApplicable(JLabel, Component)
      • addScrolled

        public FormBuilder.ComponentAdder addScrolled​(java.awt.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​(javax.swing.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:
        Forms.buttonBar(JComponent...)
      • addBar

        public FormBuilder.ComponentAdder addBar​(javax.swing.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:
        Forms.checkBoxBar(JCheckBox...)
      • addBar

        public FormBuilder.ComponentAdder addBar​(javax.swing.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:
        Forms.radioButtonBar(JRadioButton...)
      • addStack

        public FormBuilder.ComponentAdder addStack​(javax.swing.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:
        Forms.buttonStack(JComponent...)
      • addStack

        public FormBuilder.ComponentAdder addStack​(javax.swing.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:
        Forms.checkBoxStack(JCheckBox...)
      • addStack

        public FormBuilder.ComponentAdder addStack​(javax.swing.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:
        Forms.radioButtonStack(JRadioButton...)
      • add

        public FormBuilder.ViewAdder add​(FormBuilder.FormBuildingView view)
        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​(java.lang.String markedLabelText,
                                              java.lang.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("N&ame:")     .xy(1, 1) // Mnemonic is 'a'
            .add("Save &as:")  .xy(1, 1) // Mnemonic is the second 'a'
            .add("Look&&Feel:").xy(1, 1) // No mnemonic, text is "look&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:
        defaultLabelType(LabelType), MnemonicUtils, String.format(String, Object...)
      • addLabel

        public FormBuilder.ComponentAdder addLabel​(java.lang.String markedText,
                                                   java.lang.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("N&ame:")     .xy(1, 1) // Mnemonic is 'a'
            .addLabel("Save &as:")  .xy(1, 1) // Mnemonic is the second 'a'
            .addLabel("Look&&Feel:").xy(1, 1) // No mnemonic, text is "look&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:
        MnemonicUtils, ComponentFactory, String.format(String, Object...)
      • addROLabel

        public FormBuilder.ComponentAdder addROLabel​(java.lang.String markedText,
                                                     java.lang.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("N&ame:")     .xy(1, 1) // Mnemonic is 'a'
            .addROLabel("Save &as:")  .xy(1, 1) // Mnemonic is the second 'a'
            .addROLabel("Look&&Feel:").xy(1, 1) // No mnemonic, text is "look&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:
        MnemonicUtils, ComponentFactory, String.format(String, Object...)
      • addTitle

        public FormBuilder.ComponentAdder addTitle​(java.lang.String markedText,
                                                   java.lang.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("N&ame")     .xy(1, 1) // Mnemonic is 'a'
            .addTitle("Look&&Feel").xy(1, 1) // No mnemonic, text is Look&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:
        MnemonicUtils, ComponentFactory, String.format(String, Object...)
      • addSeparator

        public FormBuilder.ComponentAdder addSeparator​(java.lang.String markedText,
                                                       java.lang.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("N&ame")     .xyw(1, 1, 3) // Mnemonic is 'a'
            .addSeparator("Look&&Feel").xyw(1, 1, 3) // No mnemonic, text is "look&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:
        MnemonicUtils, ComponentFactory, String.format(String, Object...)
      • add

        public FormBuilder.ComponentAdder add​(javax.swing.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:
        JLabel(Icon)
      • add

        public FormBuilder.ComponentAdder add​(boolean expression,
                                              java.awt.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:
        isLabelForApplicable(JLabel, Component)
      • addRaw

        public FormBuilder.ComponentAdder addRaw​(boolean expression,
                                                 java.awt.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:
        isLabelForApplicable(JLabel, Component)
      • addScrolled

        public FormBuilder.ComponentAdder addScrolled​(boolean expression,
                                                      java.awt.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,
                                                 javax.swing.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:
        Forms.buttonBar(JComponent...)
      • addBar

        public FormBuilder.ComponentAdder addBar​(boolean expression,
                                                 javax.swing.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:
        Forms.checkBoxBar(JCheckBox...)
      • addBar

        public FormBuilder.ComponentAdder addBar​(boolean expression,
                                                 javax.swing.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:
        Forms.radioButtonBar(JRadioButton...)
      • addStack

        public FormBuilder.ComponentAdder addStack​(boolean expression,
                                                   javax.swing.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:
        Forms.buttonStack(JComponent...)
      • addStack

        public FormBuilder.ComponentAdder addStack​(boolean expression,
                                                   javax.swing.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:
        Forms.checkBoxStack(JCheckBox...)
      • addStack

        public FormBuilder.ComponentAdder addStack​(boolean expression,
                                                   javax.swing.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:
        Forms.radioButtonStack(JRadioButton...)
      • 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,
                                              java.lang.String markedLabelText,
                                              java.lang.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, "N&ame:")     .xy(1, 1) // Mnemonic is 'a'
            .add(condition, "Save &as:")  .xy(1, 1) // Mnemonic is the second 'a'
            .add(condition, "Look&&Feel:").xy(1, 1) // No mnemonic, text is "look&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:
        defaultLabelType(LabelType), MnemonicUtils, ComponentFactory, String.format(String, Object...)
      • addLabel

        public FormBuilder.ComponentAdder addLabel​(boolean expression,
                                                   java.lang.String markedText,
                                                   java.lang.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, "N&ame:")     .xy(1, 1) // Mnemonic is 'a'
            .addLabel(condition, "Save &as:")  .xy(1, 1) // Mnemonic is the second 'a'
            .addLabel(condition, "Look&&Feel:").xy(1, 1) // No mnemonic, text is "look&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:
        MnemonicUtils, ComponentFactory, String.format(String, Object...)
      • addROLabel

        public FormBuilder.ComponentAdder addROLabel​(boolean expression,
                                                     java.lang.String markedText,
                                                     java.lang.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, "N&ame:")     .xy(1, 1) // Mnemonic is 'a'
            .addROLabel(condition, "Save &as:")  .xy(1, 1) // Mnemonic is the second 'a'
            .addROLabel(condition, "Look&&Feel:").xy(1, 1) // No mnemonic, text is "look&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:
        MnemonicUtils, ComponentFactory, String.format(String, Object...)
      • addTitle

        public FormBuilder.ComponentAdder addTitle​(boolean expression,
                                                   java.lang.String markedText,
                                                   java.lang.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, "N&ame")     .xy(1, 1) // Mnemonic is 'a'
            .addTitle(condition, "Look&&Feel").xy(1, 1) // No mnemonic, text is Look&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:
        MnemonicUtils, ComponentFactory, String.format(String, Object...)
      • addSeparator

        public FormBuilder.ComponentAdder addSeparator​(boolean expression,
                                                       java.lang.String markedText,
                                                       java.lang.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, "N&ame")     .xyw(1, 1, 3) // Mnemonic is 'a'
            .addSeparator(condition, "Look&&Feel").xyw(1, 1, 3) // No mnemonic, text is "look&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:
        MnemonicUtils, ComponentFactory, String.format(String, Object...)
      • add

        public FormBuilder.ComponentAdder add​(boolean expression,
                                              javax.swing.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:
        JLabel(Icon)
      • getLayoutMap

        protected LayoutMap getLayoutMap()
      • addImpl

        void addImpl​(java.awt.Component component,
                     CellConstraints rawConstraints)
      • manageLabelsAndComponents

        private void manageLabelsAndComponents​(java.awt.Component c)
      • isLabelForApplicable

        private static boolean isLabelForApplicable​(javax.swing.JLabel label,
                                                    java.awt.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​(javax.swing.JLabel label,
                                        java.awt.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 javax.swing.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​(javax.swing.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()