com.jgoodies.forms.builder

Class PanelBuilder

public class PanelBuilder extends AbstractFormBuilder

An general purpose panel builder that uses the {@link 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 {@link ButtonBarBuilder} or {@link 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 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".

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.5 $

Author: Karsten Lentzsch

See Also: ComponentFactory I15dPanelBuilder DefaultFormBuilder

Constructor Summary
PanelBuilder(FormLayout layout)
Constructs a PanelBuilder for the given layout.
PanelBuilder(FormLayout layout, JPanel panel)
Constructs a PanelBuilder for the given FormLayout and layout container.
Method Summary
JLabeladd(JLabel label, CellConstraints labelConstraints, Component component, CellConstraints componentConstraints)
Adds a label and component to the panel using the given cell constraints.
JLabeladdLabel(String textWithMnemonic)
Adds a textual label to the form using the default constraints.

 addLabel("Name");       // No Mnemonic
 addLabel("N&ame");      // Mnemonic is 'a'
 addLabel("Save &as");   // Mnemonic is the second 'a'
 addLabel("Look&&Feel"); // No mnemonic, text is "look&feel"
 
JLabeladdLabel(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("Save &as",   cc.xy(1, 1)); // Mnemonic is the second 'a'
 addLabel("Look&&Feel", cc.xy(1, 1)); // No mnemonic, text is "look&feel"
 
JLabeladdLabel(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("Save &as",   "1, 1"); // Mnemonic is the second 'a'
 addLabel("Look&&Feel", "1, 1"); // No mnemonic, text is "look&feel"
 
JLabeladdLabel(String textWithMnemonic, CellConstraints labelConstraints, Component component, CellConstraints componentConstraints)
Adds a label and component to the panel using the given cell constraints.
JComponentaddSeparator(String textWithMnemonic)
Adds a titled separator to the form that spans all columns.

 addSeparator("Name");       // No Mnemonic
 addSeparator("N&ame");      // Mnemonic is 'a'
 addSeparator("Save &as");   // Mnemonic is the second 'a'
 addSeparator("Look&&Feel"); // No mnemonic, text is "look&feel"
 
JComponentaddSeparator(String textWithMnemonic, CellConstraints constraints)
Adds a titled separator to the form using the specified constraints.

 addSeparator("Name",       cc.xy(1, 1)); // No Mnemonic
 addSeparator("N&ame",      cc.xy(1, 1)); // Mnemonic is 'a'
 addSeparator("Save &as",   cc.xy(1, 1)); // Mnemonic is the second 'a'
 addSeparator("Look&&Feel", cc.xy(1, 1)); // No mnemonic, text is "look&feel"
 
JComponentaddSeparator(String textWithMnemonic, String encodedConstraints)
Adds a titled separator to the form using the specified constraints.

 addSeparator("Name",       "1, 1"); // No Mnemonic
 addSeparator("N&ame",      "1, 1"); // Mnemonic is 'a'
 addSeparator("Save &as",   "1, 1"); // Mnemonic is the second 'a'
 addSeparator("Look&&Feel", "1, 1"); // No mnemonic, text is "look&feel"
 
JComponentaddSeparator(String textWithMnemonic, int columnSpan)
Adds a titled separator to the form that spans the specified columns.

 addSeparator("Name",       3); // No Mnemonic
 addSeparator("N&ame",      3); // Mnemonic is 'a'
 addSeparator("Save &as",   3); // Mnemonic is the second 'a'
 addSeparator("Look&&Feel", 3); // No mnemonic, text is "look&feel"
 
JLabeladdTitle(String textWithMnemonic)
Adds a title label to the form using the default constraints.

 addTitle("Name");       // No mnemonic
 addTitle("N&ame");      // Mnemonic is 'a'
 addTitle("Save &as");   // Mnemonic is the second 'a'
 addTitle("Look&&Feel"); // No mnemonic, text is Look&Feel
 
JLabeladdTitle(String textWithMnemonic, CellConstraints constraints)
Adds a title label to the form using the specified constraints.

 addTitle("Name",       cc.xy(1, 1)); // No mnemonic
 addTitle("N&ame",      cc.xy(1, 1)); // Mnemonic is 'a'
 addTitle("Save &as",   cc.xy(1, 1)); // Mnemonic is the second 'a'
 addTitle("Look&&Feel", cc.xy(1, 1)); // No mnemonic, text is Look&Feel
 
JLabeladdTitle(String textWithMnemonic, String encodedConstraints)
Adds a title label to the form using the specified constraints.

 addTitle("Name",       "1, 1"); // No mnemonic
 addTitle("N&ame",      "1, 1"); // Mnemonic is 'a'
 addTitle("Save &as",   "1, 1"); // Mnemonic is the second 'a'
 addTitle("Look&&Feel", "1, 1"); // No mnemonic, text is Look&Feel
 
ComponentFactorygetComponentFactory()
Returns the builder's component factory.
JPanelgetPanel()
Returns the panel used to build the form.
voidsetBackground(Color background)
Sets the panel's background color.
voidsetBorder(Border border)
Sets the panel's border.
voidsetComponentFactory(ComponentFactory newFactory)
Sets a new component factory.
voidsetDefaultDialogBorder()
Sets the default dialog border.
voidsetOpaque(boolean b)
Sets the panel's opaque state.

Constructor Detail

PanelBuilder

public PanelBuilder(FormLayout layout)
Constructs a 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 a PanelBuilder for the given FormLayout and layout container.

Parameters: layout the FormLayout to use panel the layout container to build on

Method Detail

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 {@link JLabel#setLabelFor(java.awt.Component)}.

Note: The {@link 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

Throws: IllegalArgumentException if the same cell constraints instance is used for the label and the component

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("Save &as");   // Mnemonic is the second 'a'
 addLabel("Look&&Feel"); // No mnemonic, text is "look&feel"
 

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.

 addLabel("Name",       cc.xy(1, 1)); // No Mnemonic
 addLabel("N&ame",      cc.xy(1, 1)); // Mnemonic is 'a'
 addLabel("Save &as",   cc.xy(1, 1)); // Mnemonic is the second 'a'
 addLabel("Look&&Feel", cc.xy(1, 1)); // No mnemonic, text is "look&feel"
 

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.

 addLabel("Name",       "1, 1"); // No Mnemonic
 addLabel("N&ame",      "1, 1"); // Mnemonic is 'a'
 addLabel("Save &as",   "1, 1"); // Mnemonic is the second 'a'
 addLabel("Look&&Feel", "1, 1"); // No mnemonic, text is "look&feel"
 

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 using {@link JLabel#setLabelFor(java.awt.Component)}.

Note: The {@link 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:",            // Mnemonic is 'N'
     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:",           // Mnemonic is 'N'
     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 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 instance is used for the label and the component

See Also: JLabel#setLabelFor(java.awt.Component) ComponentFactory DefaultFormBuilder

addSeparator

public final JComponent addSeparator(String textWithMnemonic)
Adds a titled separator to the form that spans all columns.

 addSeparator("Name");       // No Mnemonic
 addSeparator("N&ame");      // Mnemonic is 'a'
 addSeparator("Save &as");   // Mnemonic is the second 'a'
 addSeparator("Look&&Feel"); // No mnemonic, text is "look&feel"
 

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.

 addSeparator("Name",       cc.xy(1, 1)); // No Mnemonic
 addSeparator("N&ame",      cc.xy(1, 1)); // Mnemonic is 'a'
 addSeparator("Save &as",   cc.xy(1, 1)); // Mnemonic is the second 'a'
 addSeparator("Look&&Feel", cc.xy(1, 1)); // No mnemonic, text is "look&feel"
 

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.

 addSeparator("Name",       "1, 1"); // No Mnemonic
 addSeparator("N&ame",      "1, 1"); // Mnemonic is 'a'
 addSeparator("Save &as",   "1, 1"); // Mnemonic is the second 'a'
 addSeparator("Look&&Feel", "1, 1"); // No mnemonic, text is "look&feel"
 

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.

 addSeparator("Name",       3); // No Mnemonic
 addSeparator("N&ame",      3); // Mnemonic is 'a'
 addSeparator("Save &as",   3); // Mnemonic is the second 'a'
 addSeparator("Look&&Feel", 3); // No mnemonic, text is "look&feel"
 

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

addTitle

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

 addTitle("Name");       // No mnemonic
 addTitle("N&ame");      // Mnemonic is 'a'
 addTitle("Save &as");   // Mnemonic is the second 'a'
 addTitle("Look&&Feel"); // No mnemonic, text is Look&Feel
 

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.

 addTitle("Name",       cc.xy(1, 1)); // No mnemonic
 addTitle("N&ame",      cc.xy(1, 1)); // Mnemonic is 'a'
 addTitle("Save &as",   cc.xy(1, 1)); // Mnemonic is the second 'a'
 addTitle("Look&&Feel", cc.xy(1, 1)); // No mnemonic, text is Look&Feel
 

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.

 addTitle("Name",       "1, 1"); // No mnemonic
 addTitle("N&ame",      "1, 1"); // Mnemonic is 'a'
 addTitle("Save &as",   "1, 1"); // Mnemonic is the second 'a'
 addTitle("Look&&Feel", "1, 1"); // No mnemonic, text is Look&Feel
 

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

getComponentFactory

public 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 {@link com.jgoodies.forms.factories.DefaultComponentFactory}.

Returns: the component factory

See Also: setComponentFactory

getPanel

public final JPanel getPanel()
Returns the panel used to build the form.

Returns: the panel used by this builder to build the form

setBackground

public final void setBackground(Color background)
Sets the panel's background color.

Parameters: background the color to set as new background

Since: 1.1

See Also: JComponent#setBackground(Color)

setBorder

public final void setBorder(Border border)
Sets the panel's border.

Parameters: border the border to set

See Also: JComponent#setBorder(Border)

setComponentFactory

public final void setComponentFactory(ComponentFactory newFactory)
Sets a new component factory.

Parameters: newFactory the component factory to be set

See Also: getComponentFactory

setDefaultDialogBorder

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

See Also: Borders

setOpaque

public final void setOpaque(boolean b)
Sets the panel's opaque state.

Parameters: b true for opaque, false for non-opaque

Since: 1.1

See Also: JComponent#setOpaque(boolean)

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