com.jgoodies.forms.builder

Class PanelBuilder

Known Direct Subclasses:
ButtonBarBuilder, ButtonStackBuilder, I15dPanelBuilder

public class PanelBuilder
extends AbstractFormBuilder

An general purpose panel builder that uses the FormLayout to lay out JPanels. It provides convenience methods to set a default border and to add labels, titles and titled separators.

The PanelBuilder is the working horse for layouts when more specialized builders like the ButtonBarBuilder or DefaultFormBuilder are inappropriate.

The Forms tutorial includes several examples that present and compare different style to build with the PanelBuilder: static row numbers vs. row variable, explicit CellConstraints vs. builder cursor, static rows vs. dynamically added rows. Also, you may check out the Tips & Tricks section of the Forms HTML documentation.

The texts used in method #addLabel 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".

Example:
This example creates a panel with 3 columns and 3 rows.

 FormLayout layout = new FormLayout(
      "right:pref, 6dlu, 50dlu, 4dlu, default",  // columns 
      "pref, 3dlu, pref, 3dlu, pref");           // rows

 PanelBuilder builder = new PanelBuilder(layout);
 CellConstraints cc = new CellConstraints();
 builder.addLabel("&Title",      cc.xy  (1, 1));
 builder.add(new JTextField(),   cc.xywh(3, 1, 3, 1));
 builder.addLabel("&Price",      cc.xy  (1, 3));
 builder.add(new JTextField(),   cc.xy  (3, 3));
 builder.addLabel("&Author",     cc.xy  (1, 5));
 builder.add(new JTextField(),   cc.xy  (3, 5));
 builder.add(new JButton("..."), cc.xy  (5, 5));
 return builder.getPanel();
 
Version:
$Revision: 1.14 $
Author:
Karsten Lentzsch
See Also:
ComponentFactory, I15dPanelBuilder, DefaultFormBuilder

Constructor Summary

PanelBuilder(JPanel panel, FormLayout layout)
Deprecated. Replaced by PanelBuilder(FormLayout,JPanel).
PanelBuilder(FormLayout layout)
Constructs an instance of PanelBuilder for the given layout.
PanelBuilder(FormLayout layout, JPanel panel)
Constructs an instance of PanelBuilder for the given FormLayout and layout container.

Method Summary

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, String encodedConstraints)
Adds a textual label to the form using the specified 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.
JComponent
addSeparator(String text)
Adds a titled separator to the form that spans all columns.
JComponent
addSeparator(String text, String encodedConstraints)
Adds a titled separator to the form using the specified constraints.
JComponent
addSeparator(String text, CellConstraints constraints)
Adds a titled separator to the form using the specified constraints.
JComponent
addSeparator(String text, int columnSpan)
Adds a titled separator to the form that spans the specified columns.
JLabel
addTitle(String text)
Adds a title label to the form using the default constraints.
JLabel
addTitle(String text, String encodedConstraints)
Adds a title label to the form using the specified constraints.
JLabel
addTitle(String text, CellConstraints constraints)
Adds a title label to the form using the specified constraints.
protected ComponentFactory
getComponentFactory()
Returns the builder's component factory.
JPanel
getPanel()
Returns the panel used to build the form.
void
setBorder(Border border)
Sets the panel's border.
void
setComponentFactory(ComponentFactory newFactory)
Sets a new component factory.
void
setDefaultDialogBorder()
Sets the default dialog border.

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

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

Constructor Details

PanelBuilder

public PanelBuilder(JPanel panel,
                    FormLayout layout)

Deprecated. Replaced by PanelBuilder(FormLayout,JPanel).

Constructs an instance of PanelBuilder for the given panel and layout.
Parameters:
panel - the layout container to build on
layout - the form layout to use

PanelBuilder

public PanelBuilder(FormLayout layout)
Constructs an instance of PanelBuilder for the given layout. Uses an instance of JPanel as layout container with the given layout as layout manager.
Parameters:
layout - the FormLayout to use

PanelBuilder

public PanelBuilder(FormLayout layout,
                    JPanel panel)
Constructs an instance of PanelBuilder for the given FormLayout and layout container.
Parameters:
layout - the FormLayout to use
panel - the layout container to build on

Method Details

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 using JLabel.setLabelFor(java.awt.Component).

Note: The CellConstraints objects for the label and the component must be different. Cell constraints are implicitly cloned by the FormLayout when added to the container. However, in this case you may be tempted to reuse a CellConstraints object in the same way as with many other builder methods that require a single CellConstraints parameter. The pitfall is that the methods CellConstraints.xy*(...) just set the coordinates but do not create a new instance. And so the second invocation of xy*(...) overrides the settings performed in the first invocation before the object is cloned by the FormLayout.

Wrong:

 CellConstraints cc = new CellConstraints();
 builder.add(
     nameLabel, 
     cc.xy(1, 7),         // will be modified by the code below
     nameField, 
     cc.xy(3, 7)          // sets the single instance to (3, 7)
 );
 
Correct:
 // Using a single CellConstraints instance and cloning
 CellConstraints cc = new CellConstraints();
 builder.add(
     nameLabel, 
     (CellConstraints) cc.xy(1, 7).clone(), // cloned before the next modification 
     nameField, 
     cc.xy(3, 7)                            // sets this instance to (3, 7)
 );
 
 // Using two CellConstraints instances 
 CellConstraints cc1 = new CellConstraints();
 CellConstraints cc2 = new CellConstraints();
 builder.add(
     nameLabel, 
     cc1.xy(1, 7),       // sets instance 1 to (1, 7)
     nameField, 
     cc2.xy(3, 7)        // sets instance 2 to (3, 7)
 );
 
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
See Also:
JLabel.setLabelFor(java.awt.Component), DefaultFormBuilder

addLabel

public final JLabel addLabel(String textWithMnemonic)
Adds a textual label to the form using the default constraints.

 addLabel("Name");       // No Mnemonic
 addLabel("N&ame");      // Mnemonic is 'a'
 addLabel("Look&&Feel"); // No mnemonic, text is "look&feel"
 
Parameters:
textWithMnemonic - the label's text - may contain a mnemonic marker
Returns:
the new label

addLabel

public final JLabel addLabel(String textWithMnemonic,
                             String encodedConstraints)
Adds a textual label to the form using the specified constraints.

 addLabel("Name",       "1, 1"); // No Mnemonic
 addLabel("N&ame",      "1, 1"); // Mnemonic is 'a'
 addLabel("Look&&Feel", "1, 1"); // No mnemonic, text is "look&feel"
 
Parameters:
textWithMnemonic - the label's text - may contain a mnemonic marker
encodedConstraints - a string representation for the constraints
Returns:
the new label

addLabel

public final JLabel addLabel(String textWithMnemonic,
                             CellConstraints constraints)
Adds a textual label to the form using the specified constraints.

 addLabel("Name",       cc.xy(1, 1)); // No Mnemonic
 addLabel("N&ame",      cc.xy(1, 1)); // Mnemonic is 'a'
 addLabel("Look&&Feel", cc.xy(1, 1)); // No mnemonic, text is "look&feel"
 
Parameters:
textWithMnemonic - the label's text - may contain a mnemonic marker
constraints - the label's cell constraints
Returns:
the new label

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 using JLabel.setLabelFor(java.awt.Component).

Note: The CellConstraints objects for the label and the component must be different. Cell constraints are implicitly cloned by the FormLayout when added to the container. However, in this case you may be tempted to reuse a CellConstraints object in the same way as with many other builder methods that require a single CellConstraints parameter. The pitfall is that the methods CellConstraints.xy*(...) just set the coordinates but do not create a new instance. And so the second invocation of xy*(...) overrides the settings performed in the first invocation before the object is cloned by the FormLayout.

Wrong:

 builder.addLabel(
     "&Name:", 
     cc.xy(1, 7),         // will be modified by the code below
     nameField, 
     cc.xy(3, 7)          // sets the single instance to (3, 7)
 );
 
Correct:
 // Using a single CellConstraints instance and cloning
 CellConstraints cc = new CellConstraints();
 builder.addLabel(
     "&Name:", 
     (CellConstraints) cc.xy(1, 7).clone(), // cloned before the next modification 
     nameField, 
     cc.xy(3, 7)                            // sets this instance to (3, 7)
 );
 
 // Using two CellConstraints instances 
 CellConstraints cc1 = new CellConstraints();
 CellConstraints cc2 = new CellConstraints();
 builder.addLabel(
     "&Name:", 
     cc1.xy(1, 7),       // sets instance 1 to (1, 7)
     nameField, 
     cc2.xy(3, 7)        // sets instance 2 to (3, 7)
 );
 
Parameters:
textWithMnemonic - the label's text - may contain a mnemonic marker
labelConstraints - the label's cell constraints
component - the component to add
componentConstraints - the component's cell constraints
Returns:
the added label
See Also:
JLabel.setLabelFor(java.awt.Component), ComponentFactory, DefaultFormBuilder

addSeparator

public final JComponent addSeparator(String text)
Adds a titled separator to the form that spans all columns.
Parameters:
text - the separator titel
Returns:
the added separator

addSeparator

public final JComponent addSeparator(String text,
                                     String encodedConstraints)
Adds a titled separator to the form using the specified constraints.
Parameters:
text - the separator titel
encodedConstraints - a string representation for the constraints
Returns:
the added separator

addSeparator

public final JComponent addSeparator(String text,
                                     CellConstraints constraints)
Adds a titled separator to the form using the specified constraints.
Parameters:
text - the separator title
constraints - the separator's cell constraints
Returns:
the added separator

addSeparator

public final JComponent addSeparator(String text,
                                     int columnSpan)
Adds a titled separator to the form that spans the specified columns.
Parameters:
text - the separator titel
columnSpan - the number of columns the separator spans
Returns:
the added separator

addTitle

public final JLabel addTitle(String text)
Adds a title label to the form using the default constraints.
Parameters:
text - the separator titel
Returns:
the added title label

addTitle

public final JLabel addTitle(String text,
                             String encodedConstraints)
Adds a title label to the form using the specified constraints.
Parameters:
text - the label's text
encodedConstraints - a string representation for the constraints
Returns:
the added title label

addTitle

public final JLabel addTitle(String text,
                             CellConstraints constraints)
Adds a title label to the form using the specified constraints.
Parameters:
text - the label's title text
constraints - the separator's cell constraints
Returns:
the added title label

getComponentFactory

protected final ComponentFactory getComponentFactory()
Returns the builder's component factory. If no factory has been set before, it is lazily initialized using with an instance of DefaultComponentFactory.
Returns:
the component factory

getPanel

public final JPanel getPanel()
Returns the panel used to build the form.
Returns:
the panel used by this builder to build the form

setBorder

public final void setBorder(Border border)
Sets the panel's border.
Parameters:
border - the border to set

setComponentFactory

public final void setComponentFactory(ComponentFactory newFactory)
Sets a new component factory.
Parameters:
newFactory - the component factory to be set

setDefaultDialogBorder

public final void setDefaultDialogBorder()
Sets the default dialog border.

Copyright © 2002-2004 JGoodies Karsten Lentzsch. All Rights Reserved.