Logo Search packages:      
Sourcecode: libjgoodies-forms-java version File versions  Download package

com::jgoodies::forms::builder::DefaultFormBuilder Class Reference

Inheritance diagram for com::jgoodies::forms::builder::DefaultFormBuilder:

com::jgoodies::forms::builder::I15dPanelBuilder com::jgoodies::forms::builder::PanelBuilder com::jgoodies::forms::builder::AbstractFormBuilder

List of all members.


Detailed Description

Provides a means to build form-oriented panels quickly and consistently using the FormLayout. This builder combines frequently used panel building steps: add a new row, add a label, proceed to the next data column, then add a component.

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&quot, or "Save &as&quot. To use the ampersand itself, duplicate it, for example "Look&&Feel&quot.

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.9
Since:
1.0.3
See also:
com.jgoodies.forms.builder.AbstractFormBuilder

com.jgoodies.forms.factories.FormFactory

com.jgoodies.forms.layout.FormLayout

Definition at line 218 of file DefaultFormBuilder.java.


Public Member Functions

final Component add (Component component)
final Component add (Component component, String encodedCellConstraints)
final Component add (Component component, CellConstraints cellConstraints)
final JLabel add (JLabel label, CellConstraints labelConstraints, Component component, CellConstraints componentConstraints)
final JLabel add15dTitle (String resourceKey, String encodedConstraints)
final JLabel addI15dLabel (String resourceKey, CellConstraints labelConstraints, Component component, CellConstraints componentConstraints)
final JLabel addI15dLabel (String resourceKey, String encodedConstraints)
final JLabel addI15dLabel (String resourceKey, CellConstraints constraints)
final JComponent addI15dSeparator (String resourceKey, String encodedConstraints)
final JComponent addI15dSeparator (String resourceKey, CellConstraints constraints)
final JLabel addI15dTitle (String resourceKey, CellConstraints constraints)
final JLabel addLabel (String textWithMnemonic, CellConstraints labelConstraints, Component component, CellConstraints componentConstraints)
final JLabel addLabel (String textWithMnemonic)
final JLabel addLabel (String textWithMnemonic, String encodedConstraints)
final JLabel addLabel (String textWithMnemonic, CellConstraints constraints)
final JComponent addSeparator (String text)
final JComponent addSeparator (String text, int columnSpan)
final JComponent addSeparator (String text, String encodedConstraints)
final JComponent addSeparator (String text, CellConstraints constraints)
final JLabel addTitle (String text)
final JLabel addTitle (String text, String encodedConstraints)
final JLabel addTitle (String text, CellConstraints constraints)
JLabel append (String textWithMnemonic, Component c1, Component c2, Component c3, Component c4)
JLabel append (String textWithMnemonic, Component c1, Component c2, Component c3)
void append (String textWithMnemonic, Component c1, Component c2, int colSpan)
JLabel append (String textWithMnemonic, Component c1, Component c2)
JLabel append (String textWithMnemonic, Component c, int columnSpan)
JLabel append (String textWithMnemonic, Component component)
JLabel append (String textWithMnemonic)
void append (Component c1, Component c2, Component c3)
void append (Component c1, Component c2)
void append (Component component, int columnSpan)
void append (Component component)
final void appendColumn (String encodedColumnSpec)
final void appendColumn (ColumnSpec columnSpec)
final void appendGlueColumn ()
final void appendGlueRow ()
JLabel appendI15d (String resourceKey, Component c1, Component c2, Component c3, Component c4)
JLabel appendI15d (String resourceKey, Component c1, Component c2, Component c3)
JLabel appendI15d (String resourceKey, Component c1, Component c2, int colSpan)
JLabel appendI15d (String resourceKey, Component c1, Component c2)
JLabel appendI15d (String resourceKey, Component component, boolean nextLine)
JLabel appendI15d (String resourceKey, Component component)
JLabel appendI15d (String resourceKey, Component c, int columnSpan)
JLabel appendI15d (String resourceKey)
void appendI15dSeparator (String resourceKey)
JLabel appendI15dTitle (String resourceKey)
final void appendLabelComponentsGapColumn ()
final void appendParagraphGapRow ()
final void appendRelatedComponentsGapColumn ()
final void appendRelatedComponentsGapRow ()
final void appendRow (String encodedRowSpec)
final void appendRow (RowSpec rowSpec)
JComponent appendSeparator (String text)
JComponent appendSeparator ()
JLabel appendTitle (String textWithMnemonic)
final void appendUnrelatedComponentsGapColumn ()
final void appendUnrelatedComponentsGapRow ()
 DefaultFormBuilder (JPanel panel, FormLayout layout, ResourceBundle bundle)
 DefaultFormBuilder (JPanel panel, FormLayout layout)
 DefaultFormBuilder (FormLayout layout, ResourceBundle bundle, JPanel panel)
 DefaultFormBuilder (FormLayout layout, ResourceBundle bundle)
 DefaultFormBuilder (FormLayout layout, JPanel panel)
 DefaultFormBuilder (FormLayout layout)
final int getColumn ()
final int getColumnCount ()
final Container getContainer ()
final FormLayout getLayout ()
int getLeadingColumnOffset ()
RowSpec getLineGapSpec ()
final JPanel getPanel ()
final int getRow ()
final int getRowCount ()
final boolean isLeftToRight ()
boolean isRowGroupingEnabled ()
final void nextColumn (int columns)
final void nextColumn ()
final void nextLine (int lines)
final void nextLine ()
final void nextRow (int rows)
final void nextRow ()
final void setAlignment (CellConstraints.Alignment hAlign, CellConstraints.Alignment vAlign)
final void setBorder (Border border)
final void setBounds (int column, int row, int columnSpan, int rowSpan)
final void setColumn (int column)
final void setColumnSpan (int columnSpan)
final void setComponentFactory (ComponentFactory newFactory)
final void setDefaultDialogBorder ()
final void setExtent (int columnSpan, int rowSpan)
final void setHAlignment (CellConstraints.Alignment alignment)
void setLeadingColumnOffset (int columnOffset)
final void setLeftToRight (boolean b)
void setLineGapSize (ConstantSize lineGapSize)
final void setOrigin (int column, int row)
void setParagraphGapSize (ConstantSize paragraphGapSize)
final void setRow (int row)
void setRowGroupingEnabled (boolean enabled)
final void setRowSpan (int rowSpan)
final void setVAlignment (CellConstraints.Alignment alignment)

Protected Member Functions

final CellConstraints cellConstraints ()
final CellConstraints createLeftAdjustedConstraints (int columnSpan)
final int getColumnIncrementSign ()
final ComponentFactory getComponentFactory ()
String getI15dString (String resourceKey)
int getLeadingColumn ()

Private Member Functions

void ensureCursorColumnInGrid ()
void ensureHasComponentLine ()
void ensureHasGapRow (RowSpec gapRowSpec)
RowSpec getCursorRowSpec ()

Private Attributes

int leadingColumnOffset = 0
RowSpec lineGapSpec = FormFactory.LINE_GAP_ROWSPEC
RowSpec paragraphGapSpec = FormFactory.PARAGRAPH_GAP_ROWSPEC
boolean rowGroupingEnabled = false

The documentation for this class was generated from the following file:

Generated by  Doxygen 1.6.0   Back to index