com.jgoodies.forms.builder
Class PanelBuilder

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

Direct Known Subclasses:

I15dPanelBuilder

public class PanelBuilder
extends AbstractFormBuilder

An general purpose panel builder that uses the FormLayoutJPanels. It provides convenience method to set a default border and to add labels, titles and titled separators.

ButtonBarBuilder or DefaultFormBuilder#addLabel #addTitle, and #addSeparator can contai an optional mnemonic marker. The mnemonic and mnemonic inde are indicated by a single ampersand (&). For exampl "&Save", or "Save &as" To use the ampersand itself duplicate it, for exampl "Look&&Feel".

Example:

Version:

$Revision: 1.21 $

Author:

Karsten Lentzsch

See Also:

ComponentFactory, I15dPanelBuilder, DefaultFormBuilder

Field Summary

Fields inherited from class com.jgoodies.forms.builder.AbstractBuilder

currentCellConstraints

Constructor Summary

PanelBuilder(FormLayout layout)
Constructs a PanelBuilder for the give layout.

PanelBuilder(FormLayout layout, JPanel panel)
Constructs a PanelBuilder for the give FormLayout and layout container.

Method Summary

Component	add(Component component, CellConstraints cellConstraints) Adds a component to the panel using the given cell constraints.
JLabel	add(JLabel label, CellConstraints labelConstraints, Component component, CellConstraints componentConstraints) Adds a label and component to the panel using the given cell constraints.
JLabel	addLabel(String textWithMnemonic) Adds a textual label to the form using the default constraints.
JLabel	addLabel(String textWithMnemonic, CellConstraints constraints) Adds a textual label to the form using the specified constraints.
JLabel	addLabel(String textWithMnemonic, CellConstraints labelConstraints, Component component, CellConstraints componentConstraints) Adds a label and component to the panel using the given cell constraints.
JLabel	addLabel(String textWithMnemonic, String encodedConstraints) Adds a textual label to the form using the specified constraints.
JLabel	addROLabel(String textWithMnemonic) Adds a textual label intended for labeling read-only component to the form using the default constraints.
JLabel	addROLabel(String textWithMnemonic, CellConstraints constraints) Adds a textual label intended for labeling read-only component to the form using the specified constraints.
JLabel	addROLabel(String textWithMnemonic, CellConstraints labelConstraints, Component component, CellConstraints componentConstraints) Adds a label and component to the panel using the given cell constraints.
JLabel	addROLabel(String textWithMnemonic, String encodedConstraints) Adds a textual label intended for labeling read-only component to the form using the specified constraints.
JComponent	addSeparator(String textWithMnemonic) Adds a titled separator to the form that spans all columns.
JComponent	addSeparator(String textWithMnemonic, CellConstraints constraints) Adds a titled separator to the form using the specified constraints.
JComponent	addSeparator(String textWithMnemonic, int columnSpan) Adds a titled separator to the form that spans the specified columns.
JComponent	addSeparator(String textWithMnemonic, String encodedConstraints) Adds a titled separator to the form using the specified constraints.
JLabel	addTitle(String textWithMnemonic) Adds a title label to the form using the default constraints.
JLabel	addTitle(String textWithMnemonic, CellConstraints constraints) Adds a title label to the form using the specified constraints.
JLabel	addTitle(String textWithMnemonic, String encodedConstraints) Adds a title label to the form using the specified constraints.
PanelBuilder	background(Color background) Sets the panel's background color and the panel to be opaque.
PanelBuilder	border(Border border) Sets the panel's border.
PanelBuilder	border(String emptyBorderSpec) Sets the panel's border as an EmptyBorder using the given specificatio for the top, left, bottom, right in DLU.
JPanel	build() Returns the panel used to build the form.
PanelBuilder	focusTraversal(FocusTraversalPolicy policy) Sets the panel's focus traversal policy and sets the pane as focus traversal policy provider.
static boolean	getLabelForFeatureEnabledDefault() Returns the global default for the enablement of the setLabelFor feature.
static boolean	getOpaqueDefault()
JPanel	getPanel() Returns the panel used to build the form.
protected boolean	isLabelForApplicable(JLabel label, Component component) Checks and answers whether the given component shall be se as component for a previously added label usin JLabel.setLabelFor(Component).
PanelBuilder	labelForFeatureEnabled(boolean b) Enables or disables the setLabelFor feature for this PanelBuilder.
PanelBuilder	opaque(boolean b) Sets the panel's opaque state.
void	setBorder(Border border) Deprecated. Replaced by border(Border)
void	setDefaultDialogBorder() Deprecated. Replaced by #border(Borders.DIALOG)
protected void	setLabelFor(JLabel label, Component component) Sets label as labeling label for component or a appropriate child.
static void	setLabelForFeatureEnabledDefault(boolean b) Sets the default value for the setLabelFor feature enablement.
void	setOpaque(boolean b) Deprecated. Replaced by opaque(boolean)
static void	setOpaqueDefault(boolean b) Sets the global default value for a builder's opaque stat that can be overridden per builder.

Methods inherited from class com.jgoodies.forms.builder.AbstractFormBuilder

add, add, appendColumn, appendColumn, appendGlueColumn, appendGlueRow, appendLabelComponentsGapColumn, appendParagraphGapRow, appendRelatedComponentsGapColumn, appendRelatedComponentsGapRow, appendRow, appendRow, appendUnrelatedComponentsGapColumn, appendUnrelatedComponentsGapRow, cellConstraints, createLeftAdjustedConstraints, getColumn, getColumnIncrementSign, getLeadingColumn, getRow, isLeftToRight, nextColumn, nextColumn, nextLine, nextLine, nextRow, nextRow, setAlignment, setBounds, setColumn, setColumnSpan, setExtent, setHAlignment, setLeftToRight, setOrigin, setRow, setRowSpan, setVAlignment

Methods inherited from class com.jgoodies.forms.builder.AbstractBuilder

createComponentFactory, getColumnCount, getComponentFactory, getComponentFactoryDefault, getContainer, getLayout, getRowCount, setComponentFactory, setComponentFactoryDefault

Methods inherited from class java.lang.Object

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

Constructor Detail

PanelBuilder

public PanelBuilder(FormLayout layout)

Constructs a PanelBuilder for the give layout. Uses an instance of JPanel as layout containe with the given layout as layout manager.

Parameters:

layout - the FormLayout to use

Throws:

NullPointerException - if layout is null

PanelBuilder

public PanelBuilder(FormLayout layout,
                    JPanel panel)

Constructs a PanelBuilder for the give FormLayout and layout container.

Parameters:

layout - the FormLayout to use

panel - the layout container to build on

Throws:

NullPointerException - if layout or container is null

Method Detail

getLabelForFeatureEnabledDefault

public static boolean getLabelForFeatureEnabledDefault()

Returns the global default for the enablement of the setLabelFor feature This can be overridden per PanelBuilder usin labelForFeatureEnabled(boolean) The feature is globally disabled by default.

Returns:

true for globally enabled, false for globally disabled

setLabelForFeatureEnabledDefault

public static void setLabelForFeatureEnabledDefault(boolean b)

Sets the default value for the setLabelFor feature enablement This can be overridden per PanelBuilder usin labelForFeatureEnabled(boolean) The default value is used to set the initial PanelBuilde setting for this feature The feature is globally disabled by default.

Parameters:

b - true for globally enabled, false for globally disabled

getOpaqueDefault

public static boolean getOpaqueDefault()

Returns:

the global default value for a builder's opaque stat that can be overridden per builder

Since:

1.6

setOpaqueDefault

public static void setOpaqueDefault(boolean b)

Sets the global default value for a builder's opaque stat that can be overridden per builder Since the Forms 1.6, the default value is false in other words, panels will not be opaque.

Parameters:

b - the new value

Since:

1.6

getPanel

public final JPanel getPanel()

Returns the panel used to build the form Intended to access panel properties. For returning the built panel you should use build().

Returns:

the panel used by this builder to build the form

background

public PanelBuilder background(Color background)

Sets the panel's background color and the panel to be opaque.

Parameters:

background - the color to set as new background

Since:

1.6

See Also:

JComponent.setBackground(Color)

border

public PanelBuilder border(Border border)

Sets the panel's border.

Parameters:

border - the border to set

Since:

1.6

See Also:

JComponent.setBorder(Border)

border

public PanelBuilder border(String emptyBorderSpec)

Sets the panel's border as an EmptyBorder using the given specificatio for the top, left, bottom, right in DLU. For exampl "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 han side.

setBorder(Borders.createEmptyBorder(emptyBorderSpec)).

Parameters:

emptyBorderSpec - describes the top, left, bottom, right size of the EmptyBorder to create

Since:

1.6

See Also:

Borders.createEmptyBorder(String)

opaque

public PanelBuilder opaque(boolean b)

Sets the panel's opaque state.

Parameters:

b - true for opaque, false for non-opaque

Since:

1.6

See Also:

JComponent.setOpaque(boolean)

focusTraversal

public PanelBuilder focusTraversal(FocusTraversalPolicy policy)

Sets the panel's focus traversal policy and sets the pane as focus traversal policy provider. Hence, this call is equivalent to

Parameters:
policy - the focus traversal policy that will manag
        keyboard traversal of the children in this builder's panel
Since:
  
1.7
See Also:
Container.setFocusTraversalPolicy(FocusTraversalPolicy), 
Container.setFocusTraversalPolicyProvider(boolean)

labelForFeatureEnabled

public PanelBuilder labelForFeatureEnabled(boolean b)

Enables or disables the setLabelFor feature for this PanelBuilder The value is initialized from the global default valu getLabelForFeatureEnabledDefault(). It is globally disable by default.

Parameters:

b - true for enabled, false for disabled

setBorder

@Deprecated
public void setBorder(Border border)

Deprecated. Replaced by border(Border)

Sets the panel's border.

Parameters:

border - the border to set

See Also:

JComponent.setBorder(Border)

setDefaultDialogBorder

@Deprecated
public void setDefaultDialogBorder()

Deprecated. Replaced by #border(Borders.DIALOG)

Sets the default dialog border.

See Also:

Borders

setOpaque

@Deprecated
public void setOpaque(boolean b)

Deprecated. Replaced by opaque(boolean)

Sets the panel's opaque state.

Parameters:

b - true for opaque, false for non-opaque

Since:

1.1

See Also:

JComponent.setOpaque(boolean)

build

public final 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

Since:

1.6

addLabel

public final JLabel addLabel(String textWithMnemonic)

Adds a textual label to the form using the default constraints.

Parameters:

textWithMnemonic - the label's text may contain an ampersand (&) to mark a mnemonic

Returns:

the new label

See Also:

ComponentFactory

addLabel

public final JLabel addLabel(String textWithMnemonic,
                             CellConstraints constraints)

Adds a textual label to the form using the specified constraints.

Parameters:

textWithMnemonic - the label's text may contain an ampersand (&) to mark a mnemonic

constraints - the label's cell constraints

Returns:

the new label

See Also:

ComponentFactory

addLabel

public final JLabel addLabel(String textWithMnemonic,
                             String encodedConstraints)

Adds a textual label to the form using the specified constraints.

Parameters:

textWithMnemonic - the label's text may contain an ampersand (&) to mark a mnemonic

encodedConstraints - a string representation for the constraints

Returns:

the new label

See Also:

ComponentFactory

addLabel

public final JLabel addLabel(String textWithMnemonic,
                             CellConstraints labelConstraints,
                             Component component,
                             CellConstraints componentConstraints)

Adds a label and component to the panel using the given cell constraints Sets the given label as the component label usin JLabel.setLabelFor(java.awt.Component).

Note: The CellConstraints objects for the labe and the component must be different. Cell constraints are implicitl cloned by the FormLayout when added to the container However, in this case you may be tempted to reuse CellConstraints object in the same way as with many othe builder methods that require a single CellConstraintsCellConstraints.xy*(...)not create a new instance And so the second invocation of xy*(...) override the settings performed in the first invocation before the objec is cloned by the FormLayout.

Wrong:

Correct:


Parameters:
textWithMnemonic - the label's text 
     may contain an ampersand (&) to mark a mnemonic
labelConstraints - the label's cell constraints
component - the component to add
componentConstraints - the component's cell constraints
Returns:
the added label
Throws:
IllegalArgumentException - if the same cell constraints instanc
     is used for the label and the component
See Also:
JLabel.setLabelFor(java.awt.Component), 
ComponentFactory, 
DefaultFormBuilder

addROLabel

public final JLabel addROLabel(String textWithMnemonic)

Adds a textual label intended for labeling read-only component to the form using the default constraints.

Parameters:

textWithMnemonic - the label's text may contain an ampersand (&) to mark a mnemonic

Returns:

the new label

Since:

1.3

addROLabel

public final JLabel addROLabel(String textWithMnemonic,
                               CellConstraints constraints)

Adds a textual label intended for labeling read-only component to the form using the specified constraints.

Parameters:

textWithMnemonic - the label's text may contain an ampersand (&) to mark a mnemonic

constraints - the label's cell constraints

Returns:

the new label

Since:

1.3

addROLabel

public final JLabel addROLabel(String textWithMnemonic,
                               String encodedConstraints)

Adds a textual label intended for labeling read-only component to the form using the specified constraints.

Parameters:

textWithMnemonic - the label's text may contain an ampersand (&) to mark a mnemonic

encodedConstraints - a string representation for the constraints

Returns:

the new label

Since:

1.3

addROLabel

public final JLabel addROLabel(String textWithMnemonic,
                               CellConstraints labelConstraints,
                               Component component,
                               CellConstraints componentConstraints)

Adds a label and component to the panel using the given cell constraints Sets the given label as the component label usin JLabel.setLabelFor(java.awt.Component).

Note: The CellConstraints objects for the labe and the component must be different. Cell constraints are implicitl cloned by the FormLayout when added to the container However, in this case you may be tempted to reuse CellConstraints object in the same way as with many othe builder methods that require a single CellConstraintsCellConstraints.xy*(...)not create a new instance And so the second invocation of xy*(...) override the settings performed in the first invocation before the objec is cloned by the FormLayout.

Wrong:

Correct:


Parameters:
textWithMnemonic - the label's text 
     may contain an ampersand (&) to mark a mnemonic
labelConstraints - the label's cell constraints
component - the component to add
componentConstraints - the component's cell constraints
Returns:
the added label
Throws:
IllegalArgumentException - if the same cell constraints instanc
     is used for the label and the component
Since:
  
1.3
See Also:
JLabel.setLabelFor(java.awt.Component), 
DefaultFormBuilder

addTitle

public final JLabel addTitle(String textWithMnemonic)

Adds a title label to the form using the default constraints.

Parameters:

textWithMnemonic - the title label's text may contain an ampersand (&) to mark a mnemonic

Returns:

the added title label

See Also:

ComponentFactory

addTitle

public final JLabel addTitle(String textWithMnemonic,
                             CellConstraints constraints)

Adds a title label to the form using the specified constraints.

Parameters:

textWithMnemonic - the title label's text may contain an ampersand (&) to mark a mnemonic

constraints - the separator's cell constraints

Returns:

the added title label

See Also:

ComponentFactory

addTitle

public final JLabel addTitle(String textWithMnemonic,
                             String encodedConstraints)

Adds a title label to the form using the specified constraints.

Parameters:

textWithMnemonic - the title label's text may contain an ampersand (&) to mark a mnemonic

encodedConstraints - a string representation for the constraints

Returns:

the added title label

See Also:

ComponentFactory

addSeparator

public final JComponent addSeparator(String textWithMnemonic)

Adds a titled separator to the form that spans all columns.

Parameters:

textWithMnemonic - the separator label's text may contain an ampersand (&) to mark a mnemonic

Returns:

the added separator

addSeparator

public final JComponent addSeparator(String textWithMnemonic,
                                     CellConstraints constraints)

Adds a titled separator to the form using the specified constraints.

Parameters:

textWithMnemonic - the separator label's text may contain an ampersand (&) to mark a mnemonic

constraints - the separator's cell constraints

Returns:

the added separator

addSeparator

public final JComponent addSeparator(String textWithMnemonic,
                                     String encodedConstraints)

Adds a titled separator to the form using the specified constraints.

Parameters:

textWithMnemonic - the separator label's text may contain an ampersand (&) to mark a mnemonic

encodedConstraints - a string representation for the constraints

Returns:

the added separator

addSeparator

public final JComponent addSeparator(String textWithMnemonic,
                                     int columnSpan)

Adds a titled separator to the form that spans the specified columns.

Parameters:

textWithMnemonic - the separator label's text may contain an ampersand (&) to mark a mnemonic

columnSpan - the number of columns the separator spans

Returns:

the added separator

add

public final JLabel add(JLabel label,
                        CellConstraints labelConstraints,
                        Component component,
                        CellConstraints componentConstraints)

Adds a label and component to the panel using the given cell constraints Sets the given label as the component label usin JLabel.setLabelFor(java.awt.Component).

Note: The CellConstraints objects for the labe and the component must be different. Cell constraints are implicitl cloned by the FormLayout when added to the container However, in this case you may be tempted to reuse CellConstraints object in the same way as with many othe builder methods that require a single CellConstraintsCellConstraints.xy*(...)not create a new instance And so the second invocation of xy*(...) override the settings performed in the first invocation before the objec is cloned by the FormLayout.

Wrong:

Correct:


Parameters:
label - the label to add
labelConstraints - the label's cell constraints
component - the component to add
componentConstraints - the component's cell constraints
Returns:
the added label
Throws:
IllegalArgumentException - if the same cell constraints instanc
     is used for the label and the component
See Also:
JLabel.setLabelFor(java.awt.Component), 
DefaultFormBuilder

add

public Component add(Component component,
                     CellConstraints cellConstraints)

Adds a component to the panel using the given cell constraints In addition to the superclass behavior, this implementatio tracks the most recently added label, and associates it wit the next added component that is applicable for being set as componen for the label.

Overrides:

add in class AbstractFormBuilder

Parameters:

component - the component to add

cellConstraints - the component's cell constraints

Returns:

the added component

See Also:

isLabelForApplicable(JLabel, Component)

isLabelForApplicable

protected boolean isLabelForApplicable(JLabel label,
                                       Component component)

Checks and answers whether the given component shall be se as component for a previously added label usin 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

protected void setLabelFor(JLabel label,
                           Component component)

Sets label as labeling label for component or a appropriate child. In case of a JScrollPane as given component this default implementation labels the view of the scroll pane' viewport.

Parameters:

label - the labeling label

component - the component to be labeled, or the parent o the labeled component