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

The extra value lies in the #append methods that append gap rows and component rows if necessary and then add the given components. They are built upon the superclass behavior #appendRow and the set of #add methods. A set of component appenders allows to add a textual label and associated component in a single step.

This builder can map resource keys to internationalized (i15d) texts when creating text labels, titles and titled separators. Therefore you must specify a ResourceBundle in the constructor. The builder methods throw an IllegalStateException if one of the mapping builder methods is invoked and no bundle has been set.

You can configure the build process by setting a leading column, enabling the row grouping and by modifying the gaps between normal lines and between paragraphs. The leading column will be honored if the cursor proceeds to the next row. All appended components start in the specified lead column, except appended separators that span all columns.

It is temptive to use the DefaultFormBuilder all the time and to let it add rows automatically. Use a simpler style if it increases the code readability. Explicit row specifications and cell constraints make your layout easier to understand - but harder to maintain. See also the accompanying tutorial sources and the Tips & Tricks that are part of the Forms documentation.

Sometimes a form consists of many standardized rows but has a few rows that require a customization. The DefaultFormBuilder can do everything that the superclasses com.jgoodies.forms.builder.AbstractFormBuilder and com.jgoodies.forms.builder.PanelBuilder can do; among other things: appending new rows and moving the cursor. Again, ask yourself if the DefaultFormBuilder is the appropriate builder. As a rule of thumb you should have more components than builder commands. There are different ways to add custom rows. Find below example code that presents and compares the pros and cons of three approaches.

The texts used in methods #append(String, ...) and #appendTitle(String) as well as the localized texts used in methods #appendI15d and #appendI15dTitle 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:

 public void build() {
 FormLayout layout = new FormLayout("right:max(40dlu;pref), 3dlu, 80dlu, 7dlu, " // 1st major colum
 + "right:max(40dlu;pref), 3dlu, 80dlu", // 2nd major column
 ""); // add rows dynamically
 DefaultFormBuilder builder = new DefaultFormBuilder(layout);
 builder.setDefaultDialogBorder();
 builder.appendSeparator("Flange");
 builder.append("Identifier", identifierField);
 builder.nextLine();
 builder.append("PTI [kW]", new JTextField());
 builder.append("Power [kW]", new JTextField());
 builder.append("s [mm]", new JTextField());
 builder.nextLine();
 builder.appendSeparator("Diameters");
 builder.append("da [mm]", new JTextField());
 builder.append("di [mm]", new JTextField());
 builder.append("da2 [mm]", new JTextField());
 builder.append("di2 [mm]", new JTextField());
 builder.append("R [mm]", new JTextField());
 builder.append("D [mm]", new JTextField());
 builder.appendSeparator("Criteria");
 builder.append("Location", buildLocationComboBox());
 builder.append("k-factor", new JTextField());
 builder.appendSeparator("Bolts");
 builder.append("Material", ViewerUIFactory.buildMaterialComboBox());
 builder.nextLine();
 builder.append("Numbers", new JTextField());
 builder.nextLine();
 builder.append("ds [mm]", new JTextField());
 }
 

Custom Row Example:

 public JComponent buildPanel() {
 initComponents();
 FormLayout layout = new FormLayout("right:pref, 3dlu, default:grow", "");
 DefaultFormBuilder builder = new DefaultFormBuilder(layout);
 builder.setDefaultDialogBorder();
 builder.setRowGroupingEnabled(true);
 CellConstraints cc = new CellConstraints();
 // In this approach, we add a gap and a custom row.
 // The advantage of this approach is, that we can express
 // the row spec and comment area cell constraints freely.
 // The disadvantage is the misalignment of the leading label.
 // Also the row's height may be inconsistent with other rows. 
 builder.appendSeparator("Single Custom Row");
 builder.append("Name", name1Field);
 builder.appendRow(builder.getLineGapSpec());
 builder.appendRow(new RowSpec("top:31dlu")); // Assumes line is 14, gap is 3
 builder.nextLine(2);
 builder.append("Comment");
 builder.add(new JScrollPane(comment1Area), cc.xy(builder.getColumn(), builder.getRow(), "fill, fill"));
 builder.nextLine();
 // In this approach, we append a standard row with gap before it.
 // The advantage is, that the leading label is aligned well.
 // The disadvantage is that the comment area now spans
 // multiple cells and is slightly less flexible.
 // Also the row's height may be inconsistent with other rows. 
 builder.appendSeparator("Standard + Custom Row");
 builder.append("Name", name2Field);
 builder.append("Comment");
 builder.appendRow(new RowSpec("17dlu")); // Assumes line is 14, gap is 3
 builder.add(new JScrollPane(comment2Area), cc.xywh(builder.getColumn(), builder.getRow(), 1, 2));
 builder.nextLine(2);
 // In this approach, we append two standard rows with associated gaps.
 // The advantage is, that the leading label is aligned well, 
 // and the height is consistent with other rows.
 // The disadvantage is that the comment area now spans
 // multiple cells and is slightly less flexible.
 builder.appendSeparator("Two Standard Rows");
 builder.append("Name", name3Field);
 builder.append("Comment");
 builder.nextLine();
 builder.append("");
 builder.nextRow(-2);
 builder.add(new JScrollPane(comment3Area), cc.xywh(builder.getColumn(), builder.getRow(), 1, 3));
 return builder.getPanel();
 }
 

TODO: Consider adding a method for appending a component that spans the remaining columns in the current row. Method name candidates are #appendFullSpan and #appendRemaining.
author:
   Karsten Lentzsch
version:
   $Revision: 1.2 $
since:
   1.0.3
See Also:   com.jgoodies.forms.builder.AbstractFormBuilder
See Also:   com.jgoodies.forms.factories.FormFactory
See Also:   com.jgoodies.forms.layout.FormLayout

The created label is labelling the given component; so the component gets the focus if the (optional) label mnemonic is pressed.
Parameters:
  textWithMnemonic - the label's text - may mark a mnemonic
Parameters:
  c - the component to add
Parameters:
  columnSpan - number of columns the component shall span the added label
See Also:   JLabel.setLabelFor(java.awt.Component)

Examples:

 builder.setLineGapSize(Sizes.ZERO);
 builder.setLineGapSize(Sizes.DLUY9);
 builder.setLineGapSize(Sizes.pixel(1));
 

Examples:

 builder.setParagraphGapSize(Sizes.DLUY14);
 builder.setParagraphGapSize(Sizes.dluY(22));
 builder.setParagraphGapSize(Sizes.pixel(42));