Class AbstractFormBuilder

java.lang.Object
com.jgoodies.forms.builder.AbstractFormBuilder
Direct Known Subclasses:
PanelBuilder

public abstract class AbstractFormBuilder extends Object
An abstract class that minimizes the effort required to implement non-visual builders that use the FormLayout.

Builders hide details of the FormLayout and provide convenience behavior that assists you in constructing a form. This class provides a cell cursor that helps you traverse a form while you add components. Also, it offers several methods to append custom and logical columns and rows.

Version:
$Revision: 1.12 $
Author:
Karsten Lentzsch
See Also:
  • Constructor Summary

    Constructors
    Constructor
    Description
    Constructs a AbstractFormBuilder for the given FormLayout and layout container.
  • Method Summary

    Modifier and Type
    Method
    Description
    final Component
    add(Component component)
    Adds a component to the container using the default cell constraints.
    add(Component component, CellConstraints cellConstraints)
    Adds a component to the panel using the given cell constraints.
    final Component
    add(Component component, String encodedCellConstraints)
    Adds a component to the panel using the given encoded cell constraints.
    final void
    Appends the given column specification to the builder's layout.
    final void
    appendColumn(String encodedColumnSpec)
    Appends a column specification to the builder's layout that represents the given string encoding.
    final void
    Appends a glue column.
    final void
    Appends a glue row.
    final void
    Appends a column that is the default gap between a label and its associated component.
    final void
    Appends a row that is the default gap for paragraphs.
    final void
    Appends a column that is the default gap for related components.
    final void
    Appends a row that is the default gap for related components.
    final void
    appendRow(RowSpec rowSpec)
    Appends the given row specification to the builder's layout.
    final void
    appendRow(String encodedRowSpec)
    Appends a row specification to the builder's layout that represents the given string encoding.
    final void
    Appends a column that is the default gap for unrelated components.
    final void
    Appends a row that is the default gap for unrelated components.
    protected final CellConstraints
    Returns the CellConstraints object that is used as a cursor and holds the current column span and row span.
    protected final CellConstraints
    Creates and returns a CellConstraints object at the current cursor position that uses the given column span and is adjusted to the left.
    final int
    Returns the cursor's column.
    final int
    Returns the number of columns in the form.
    protected final int
    Returns the sign (-1 or 1) used to increment the cursor's column when moving to the next column.
    final Container
    Returns the container used to build the form.
    Returns the instance of FormLayout used to build this form.
    protected int
    Returns the index of the leading column.
    final int
    Returns the cursor's row.
    final int
    Returns the number of rows in the form.
    final boolean
    Returns whether this builder fills the form left-to-right or right-to-left.
    final void
    Moves to the next column, does the same as #nextColumn(1).
    final void
    nextColumn(int columns)
    Moves to the next column.
    final void
    Moves to the next line: increases the row and resets the column; does the same as #nextLine(1).
    final void
    nextLine(int lines)
    Moves the cursor down several lines: increases the row by the specified number of lines and sets the cursor to the leading column.
    final void
    Increases the row by one; does the same as #nextRow(1).
    final void
    nextRow(int rows)
    Increases the row by the specified rows.
    final void
    Sets the horizontal and vertical alignment.
    final void
    setBounds(int column, int row, int columnSpan, int rowSpan)
    Sets the cell bounds (location and extent) to the given column, row, column span and row span.
    final void
    setColumn(int column)
    Sets the cursor to the given column.
    final void
    setColumnSpan(int columnSpan)
    Sets the cursor's column span.
    final void
    setExtent(int columnSpan, int rowSpan)
    Sets the cursor's extent to the given column span and row span.
    final void
    Sets the horizontal alignment.
    final void
    setLeftToRight(boolean b)
    Sets the form fill direction to left-to-right or right-to-left.
    final void
    setOrigin(int column, int row)
    Sets the cursor's origin to the given column and row.
    final void
    setRow(int row)
    Sets the cursor to the given row.
    final void
    setRowSpan(int rowSpan)
    Sets the cursor's row span.
    final void
    Sets the vertical alignment.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Constructor Details

    • AbstractFormBuilder

      public AbstractFormBuilder(FormLayout layout, Container container)
      Constructs a AbstractFormBuilder for the given FormLayout and layout container.
      Parameters:
      layout - the FormLayout to use
      container - the layout container
      Throws:
      NullPointerException - if the layout or container is null
  • Method Details

    • getContainer

      public final Container getContainer()
      Returns the container used to build the form.
      Returns:
      the layout container
    • getLayout

      public final FormLayout getLayout()
      Returns the instance of FormLayout used to build this form.
      Returns:
      the FormLayout
    • getColumnCount

      public final int getColumnCount()
      Returns the number of columns in the form.
      Returns:
      the number of columns
    • getRowCount

      public final int getRowCount()
      Returns the number of rows in the form.
      Returns:
      the number of rows
    • isLeftToRight

      public final boolean isLeftToRight()
      Returns whether this builder fills the form left-to-right or right-to-left. The initial value of this property is set during the builder construction from the layout container's componentOrientation property.
      Returns:
      true indicates left-to-right, false indicates right-to-left
      See Also:
    • setLeftToRight

      public final void setLeftToRight(boolean b)
      Sets the form fill direction to left-to-right or right-to-left. The initial value of this property is set during the builder construction from the layout container's componentOrientation property.
      Parameters:
      b - true indicates left-to-right, false right-to-left
      See Also:
    • getColumn

      public final int getColumn()
      Returns the cursor's column.
      Returns:
      the cursor's column
    • setColumn

      public final void setColumn(int column)
      Sets the cursor to the given column.
      Parameters:
      column - the cursor's new column index
    • getRow

      public final int getRow()
      Returns the cursor's row.
      Returns:
      the cursor's row
    • setRow

      public final void setRow(int row)
      Sets the cursor to the given row.
      Parameters:
      row - the cursor's new row index
    • setColumnSpan

      public final void setColumnSpan(int columnSpan)
      Sets the cursor's column span.
      Parameters:
      columnSpan - the cursor's new column span (grid width)
    • setRowSpan

      public final void setRowSpan(int rowSpan)
      Sets the cursor's row span.
      Parameters:
      rowSpan - the cursor's new row span (grid height)
    • setOrigin

      public final void setOrigin(int column, int row)
      Sets the cursor's origin to the given column and row.
      Parameters:
      column - the new column index
      row - the new row index
    • setExtent

      public final void setExtent(int columnSpan, int rowSpan)
      Sets the cursor's extent to the given column span and row span.
      Parameters:
      columnSpan - the new column span (grid width)
      rowSpan - the new row span (grid height)
    • setBounds

      public final void setBounds(int column, int row, int columnSpan, int rowSpan)
      Sets the cell bounds (location and extent) to the given column, row, column span and row span.
      Parameters:
      column - the new column index (grid x)
      row - the new row index (grid y)
      columnSpan - the new column span (grid width)
      rowSpan - the new row span (grid height)
    • nextColumn

      public final void nextColumn()
      Moves to the next column, does the same as #nextColumn(1).
    • nextColumn

      public final void nextColumn(int columns)
      Moves to the next column.
      Parameters:
      columns - number of columns to move
    • nextRow

      public final void nextRow()
      Increases the row by one; does the same as #nextRow(1).
    • nextRow

      public final void nextRow(int rows)
      Increases the row by the specified rows.
      Parameters:
      rows - number of rows to move
    • nextLine

      public final void nextLine()
      Moves to the next line: increases the row and resets the column; does the same as #nextLine(1).
    • nextLine

      public final void nextLine(int lines)
      Moves the cursor down several lines: increases the row by the specified number of lines and sets the cursor to the leading column.
      Parameters:
      lines - number of rows to move
    • setHAlignment

      public final void setHAlignment(CellConstraints.Alignment alignment)
      Sets the horizontal alignment.
      Parameters:
      alignment - the new horizontal alignment
    • setVAlignment

      public final void setVAlignment(CellConstraints.Alignment alignment)
      Sets the vertical alignment.
      Parameters:
      alignment - the new vertical alignment
    • setAlignment

      public final void setAlignment(CellConstraints.Alignment hAlign, CellConstraints.Alignment vAlign)
      Sets the horizontal and vertical alignment.
      Parameters:
      hAlign - the new horizontal alignment
      vAlign - the new vertical alignment
    • appendColumn

      public final void appendColumn(ColumnSpec columnSpec)
      Appends the given column specification to the builder's layout.
      Parameters:
      columnSpec - the column specification object to append
      See Also:
    • appendColumn

      public final void appendColumn(String encodedColumnSpec)
      Appends a column specification to the builder's layout that represents the given string encoding.
      Parameters:
      encodedColumnSpec - the column specification to append in encoded form
      See Also:
    • appendGlueColumn

      public final void appendGlueColumn()
      Appends a glue column.
      See Also:
    • appendLabelComponentsGapColumn

      public final void appendLabelComponentsGapColumn()
      Appends a column that is the default gap between a label and its associated component.
      Since:
      1.0.3
      See Also:
    • appendRelatedComponentsGapColumn

      public final void appendRelatedComponentsGapColumn()
      Appends a column that is the default gap for related components.
      See Also:
    • appendUnrelatedComponentsGapColumn

      public final void appendUnrelatedComponentsGapColumn()
      Appends a column that is the default gap for unrelated components.
      See Also:
    • appendRow

      public final void appendRow(RowSpec rowSpec)
      Appends the given row specification to the builder's layout.
      Parameters:
      rowSpec - the row specification object to append
      See Also:
    • appendRow

      public final void appendRow(String encodedRowSpec)
      Appends a row specification to the builder's layout that represents the given string encoding.
      Parameters:
      encodedRowSpec - the row specification to append in encoded form
      See Also:
    • appendGlueRow

      public final void appendGlueRow()
      Appends a glue row.
      See Also:
    • appendRelatedComponentsGapRow

      public final void appendRelatedComponentsGapRow()
      Appends a row that is the default gap for related components.
      See Also:
    • appendUnrelatedComponentsGapRow

      public final void appendUnrelatedComponentsGapRow()
      Appends a row that is the default gap for unrelated components.
      See Also:
    • appendParagraphGapRow

      public final void appendParagraphGapRow()
      Appends a row that is the default gap for paragraphs.
      Since:
      1.0.3
      See Also:
    • add

      public Component add(Component component, CellConstraints cellConstraints)
      Adds a component to the panel using the given cell constraints.
      Parameters:
      component - the component to add
      cellConstraints - the component's cell constraints
      Returns:
      the added component
    • add

      public final Component add(Component component, String encodedCellConstraints)
      Adds a component to the panel using the given encoded cell constraints.
      Parameters:
      component - the component to add
      encodedCellConstraints - the component's encoded cell constraints
      Returns:
      the added component
    • add

      public final Component add(Component component)
      Adds a component to the container using the default cell constraints. Note that when building from left to right, this method won't adjust the cell constraints if the column span is larger than 1. In this case you should use add(Component, CellConstraints) with a cell constraints object created by createLeftAdjustedConstraints(int).
      Parameters:
      component - the component to add
      Returns:
      the added component
      See Also:
    • cellConstraints

      protected final CellConstraints cellConstraints()
      Returns the CellConstraints object that is used as a cursor and holds the current column span and row span.
      Returns:
      the builder's current CellConstraints object
    • getLeadingColumn

      protected int getLeadingColumn()
      Returns the index of the leading column.

      Subclasses may override this method, for example, if the form has a leading gap column that should not be filled with components.

      Returns:
      the leading column
    • getColumnIncrementSign

      protected final int getColumnIncrementSign()
      Returns the sign (-1 or 1) used to increment the cursor's column when moving to the next column.
      Returns:
      -1 for right-to-left, 1 for left-to-right
    • createLeftAdjustedConstraints

      protected final CellConstraints createLeftAdjustedConstraints(int columnSpan)
      Creates and returns a CellConstraints object at the current cursor position that uses the given column span and is adjusted to the left. Useful when building from right to left.
      Parameters:
      columnSpan - the column span to be used in the constraints
      Returns:
      CellConstraints adjusted to the left hand side