com.jgoodies.forms.builder
Class AbstractFormBuilder

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

Direct Known Subclasses:

PanelBuilder

public abstract class AbstractFormBuilder
extends java.lang.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: 54721 $

Author:

Karsten Lentzsch

See Also:

ButtonBarBuilder, ButtonStackBuilder, PanelBuilder, I15dPanelBuilder, DefaultFormBuilder

Field Summary

private java.awt.Container	container Holds the layout container that we are building.
private CellConstraints	currentCellConstraints Holds an instance of CellConstraints that will be used to specify the location, extent and alignments of the component to be added next.
private FormLayout	layout Holds the instance of FormLayout that is used to specifiy, fill and layout this form.
private boolean	leftToRight Specifies if we fill the grid from left to right or right to left.

Constructor Summary

AbstractFormBuilder(java.awt.Container container, FormLayout layout)
Deprecated. Replaced by AbstractFormBuilder(FormLayout, Container).

AbstractFormBuilder(FormLayout layout, java.awt.Container container)
Constructs an instance of AbstractFormBuilder for the given FormLayout and layout container.

Method Summary

java.awt.Component	add(java.awt.Component component) Adds a component to the container using the default cell constraints.
java.awt.Component	add(java.awt.Component component, CellConstraints cellConstraints) Adds a component to the panel using the given cell constraints.
java.awt.Component	add(java.awt.Component component, java.lang.String encodedCellConstraints) Adds a component to the panel using the given encoded cell constraints.
void	appendColumn(ColumnSpec columnSpec) Appends the given column specification to the builder's layout.
void	appendColumn(java.lang.String encodedColumnSpec) Appends a column specification to the builder's layout that represents the given string encoding.
void	appendGlueColumn() Appends a glue column.
void	appendGlueRow() Appends a glue row.
void	appendLabelComponentsGapColumn() Appends a column that is the default gap between a label and its associated component.
void	appendParagraphGapRow() Appends a row that is the default gap for paragraphs.
void	appendRelatedComponentsGapColumn() Appends a column that is the default gap for related components.
void	appendRelatedComponentsGapRow() Appends a row that is the default gap for related components.
void	appendRow(RowSpec rowSpec) Appends the given row specification to the builder's layout.
void	appendRow(java.lang.String encodedRowSpec) Appends a row specification to the builder's layout that represents the given string encoding.
void	appendUnrelatedComponentsGapColumn() Appends a column that is the default gap for unrelated components.
void	appendUnrelatedComponentsGapRow() Appends a row that is the default gap for unrelated components.
protected CellConstraints	cellConstraints() Returns the CellConstraints object that is used as a cursor and holds the current column span and row span.
protected 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.
int	getColumn() Returns the cursor's column.
int	getColumnCount() Returns the number of columns in the form.
protected int	getColumnIncrementSign() Returns the sign (-1 or 1) used to increment the cursor's column when moving to the next column.
java.awt.Container	getContainer() Returns the container used to build the form.
FormLayout	getLayout() Returns the instance of FormLayout used to build this form.
protected int	getLeadingColumn() Returns the index of the leading column.
int	getRow() Returns the cursor's row.
int	getRowCount() Returns the number of rows in the form.
boolean	isLeftToRight() Returns whether this builder fills the form left-to-right or right-to-left.
void	nextColumn() Moves to the next column, does the same as #nextColumn(1).
void	nextColumn(int columns) Moves to the next column.
void	nextLine() Moves to the next line: increases the row and resets the column; does the same as #nextLine(1).
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.
void	nextRow() Increases the row by one; does the same as #nextRow(1).
void	nextRow(int rows) Increases the row by the specified rows.
void	setAlignment(CellConstraints.Alignment hAlign, CellConstraints.Alignment vAlign) Sets the horizontal and vertical alignment.
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.
void	setColumn(int column) Sets the cursor to the given column.
void	setColumnSpan(int columnSpan) Sets the cursor's column span.
void	setExtent(int columnSpan, int rowSpan) Sets the cursor's extent to the given column span and row span.
void	setHAlignment(CellConstraints.Alignment alignment) Sets the horizontal alignment.
void	setLeftToRight(boolean b) Sets the form fill direction to left-to-right or right-to-left.
void	setOrigin(int column, int row) Sets the cursor's origin to the given column and row.
void	setRow(int row) Sets the cursor to the given row.
void	setRowSpan(int rowSpan) Sets the cursor's row span.
void	setVAlignment(CellConstraints.Alignment alignment) Sets the vertical alignment.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

container

private final java.awt.Container container

Holds the layout container that we are building.

layout

private final FormLayout layout

Holds the instance of FormLayout that is used to specifiy, fill and layout this form.

currentCellConstraints

private CellConstraints currentCellConstraints

Holds an instance of CellConstraints that will be used to specify the location, extent and alignments of the component to be added next.

leftToRight

private boolean leftToRight

Specifies if we fill the grid from left to right or right to left. This value is initialized during the construction from the layout container's component orientation.

See Also:

isLeftToRight(), setLeftToRight(boolean), ComponentOrientation

Constructor Detail

AbstractFormBuilder

public AbstractFormBuilder(FormLayout layout,
                           java.awt.Container container)

Constructs an instance of AbstractFormBuilder for the given FormLayout and layout container.

Parameters:

layout - the FormLayout to use

container - the layout container

Throws:

java.lang.NullPointerException - if the layout or container is null

AbstractFormBuilder

public AbstractFormBuilder(java.awt.Container container,
                           FormLayout layout)

Deprecated. Replaced by AbstractFormBuilder(FormLayout, Container).

Constructs an instance of AbstractFormBuilder for the given container and form layout.

Parameters:

container - the layout container

layout - the FormLayout to use

Method Detail

getContainer

public final java.awt.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(boolean), ComponentOrientation

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:

isLeftToRight(), ComponentOrientation

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(String)

appendColumn

public final void appendColumn(java.lang.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:

appendColumn(ColumnSpec)

appendGlueColumn

public final void appendGlueColumn()

Appends a glue column.

See Also:

appendLabelComponentsGapColumn(), appendRelatedComponentsGapColumn(), appendUnrelatedComponentsGapColumn()

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:

appendGlueColumn(), appendRelatedComponentsGapColumn(), appendUnrelatedComponentsGapColumn()

appendRelatedComponentsGapColumn

public final void appendRelatedComponentsGapColumn()

Appends a column that is the default gap for related components.

See Also:

appendGlueColumn(), appendLabelComponentsGapColumn(), appendUnrelatedComponentsGapColumn()

appendUnrelatedComponentsGapColumn

public final void appendUnrelatedComponentsGapColumn()

Appends a column that is the default gap for unrelated components.

See Also:

appendGlueColumn(), appendLabelComponentsGapColumn(), appendRelatedComponentsGapColumn()

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(String)

appendRow

public final void appendRow(java.lang.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:

appendRow(RowSpec)

appendGlueRow

public final void appendGlueRow()

Appends a glue row.

See Also:

appendRelatedComponentsGapRow(), appendUnrelatedComponentsGapRow(), appendParagraphGapRow()

appendRelatedComponentsGapRow

public final void appendRelatedComponentsGapRow()

Appends a row that is the default gap for related components.

See Also:

appendGlueRow(), appendUnrelatedComponentsGapRow(), appendParagraphGapRow()

appendUnrelatedComponentsGapRow

public final void appendUnrelatedComponentsGapRow()

Appends a row that is the default gap for unrelated components.

See Also:

appendGlueRow(), appendRelatedComponentsGapRow(), appendParagraphGapRow()

appendParagraphGapRow

public final void appendParagraphGapRow()

Appends a row that is the default gap for paragraphs.

Since:

1.0.3

See Also:

appendGlueRow(), appendRelatedComponentsGapRow(), appendUnrelatedComponentsGapRow()

add

public final java.awt.Component add(java.awt.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 java.awt.Component add(java.awt.Component component,
                                    java.lang.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 java.awt.Component add(java.awt.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:

add(Component, CellConstraints), createLeftAdjustedConstraints(int)

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