Java Doc for PanelBuilder.java in  » Swing-Library » jgoodies-forms » com » jgoodies » forms » builder » Java Source Code / Java DocumentationJava Source Code and Java Documentation

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

Note: The CellConstraints objects for the label and the component must be different.

Note: The CellConstraints objects for the label and the component must be different.

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)
 );
 

 // 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)
 );
 

 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"
 

 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"
 

 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"
 

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:",            // 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)
 );
 

 // 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)
 );
 

 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"
 

 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"
 

 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"
 

 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"
 

 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
 

 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
 

 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