FormFactory


1   /*
2    * Copyright (c) 2003 JGoodies Karsten Lentzsch. All Rights Reserved.
3    *
4    * Redistribution and use in source and binary forms, with or without 
5    * modification, are permitted provided that the following conditions are met:
6    * 
7    *  o Redistributions of source code must retain the above copyright notice, 
8    *    this list of conditions and the following disclaimer. 
9    *     
10   *  o Redistributions in binary form must reproduce the above copyright notice, 
11   *    this list of conditions and the following disclaimer in the documentation 
12   *    and/or other materials provided with the distribution. 
13   *     
14   *  o Neither the name of JGoodies Karsten Lentzsch nor the names of 
15   *    its contributors may be used to endorse or promote products derived 
16   *    from this software without specific prior written permission. 
17   *     
18   * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 
19   * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, 
20   * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 
21   * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR 
22   * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 
23   * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 
24   * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; 
25   * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 
26   * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE 
27   * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, 
28   * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 
29   */
30  
31  package com.jgoodies.forms.factories;
32  
33  import com.jgoodies.forms.layout.ColumnSpec;
34  import com.jgoodies.forms.layout.ConstantSize;
35  import com.jgoodies.forms.layout.FormLayout;
36  import com.jgoodies.forms.layout.RowSpec;
37  import com.jgoodies.forms.layout.Sizes;
38  import com.jgoodies.forms.util.LayoutStyle;
39  
40  /**
41   * A factory that creates instances of 
42   * {@link com.jgoodies.forms.layout.FormLayout} for frequently used
43   * form layouts. It makes form creation easier and more consistent.
44   * <p>
45   * <b>The <code>FormLayout</code> factory methods are work in progress 
46   * and may change without notice.</b> If you want to use these methods, 
47   * you may consider copying them into your codebase.
48   * <p> 
49   * The forms are described by major and minor columns. Major columns
50   * consist of a leading label and a set of related components, for example: a
51   * label plus textfield, or label plus textfield plus button. The component
52   * part of a major column is divided into minor columns as shown in this
53   * layout:
54   * <pre>
55   * <-    major column 1        ->  <-     major column 2       -> 
56   * label1 textfield1a textfield1b  label2 textfield2a textfield2b
57   * label3 textfield3a textfield3b  label4 textfield4
58   * label5 textfield5               label6 textfield6
59   * </pre>
60   * <p>
61   * Most forms use 1, 2, 3 or 4 major columns, which in turn are often split
62   * into 1, 2, 3 or 4 minor columns.
63   * 
64   * @author  Karsten Lentzsch
65   * @version $Revision: 1.3 $
66   * @see com.jgoodies.forms.layout.FormLayout
67   * @see ColumnSpec
68   */
69  public final class FormFactory {
70  
71  
72      // Frequently used Column Specifications ********************************
73  
74      public static final ColumnSpec MIN_COLSPEC = 
75          new ColumnSpec(Sizes.MINIMUM).asUnmodifyable();   
76                                      
77      public static final ColumnSpec PREF_COLSPEC = 
78          new ColumnSpec(Sizes.PREFERRED).asUnmodifyable();   
79                                      
80      public static final ColumnSpec DEFAULT_COLSPEC = 
81          new ColumnSpec(Sizes.DEFAULT).asUnmodifyable();   
82                                      
83      public static final ColumnSpec GLUE_COLSPEC = 
84          new ColumnSpec(ColumnSpec.DEFAULT, Sizes.ZERO, ColumnSpec.DEFAULT_GROW).asUnmodifyable();                               
85  
86      /*
87       * The following four constants use logical sizes that change with the
88       * layout style. A future release will likely defined them using 
89       * a class <code>LogicalSize</code> or <code>StyledSize</code>.
90       */
91      public static final ColumnSpec RELATED_GAP_COLSPEC =
92          createGapColumnSpec(LayoutStyle.getCurrent().getRelatedComponentsPadX());
93          
94      public static final ColumnSpec UNRELATED_GAP_COLSPEC =
95          createGapColumnSpec(LayoutStyle.getCurrent().getUnrelatedComponentsPadX()); 
96          
97      public static final ColumnSpec BUTTON_COLSPEC = 
98          new ColumnSpec(Sizes.bounded(Sizes.PREFERRED,
99                                       LayoutStyle.getCurrent().getDefaultButtonWidth(),
100                                      null)).asUnmodifyable();
101         
102     public static final ColumnSpec GROWING_BUTTON_COLSPEC = 
103         new ColumnSpec(ColumnSpec.DEFAULT,
104                        BUTTON_COLSPEC.getSize(),
105                        ColumnSpec.DEFAULT_GROW).asUnmodifyable();
106         
107     
108     // Frequently used Row Specifications ***********************************
109     
110     public static final RowSpec MIN_ROWSPEC = 
111         new RowSpec(Sizes.MINIMUM).asUnmodifyable();   
112                                     
113     public static final RowSpec PREF_ROWSPEC = 
114         new RowSpec(Sizes.PREFERRED).asUnmodifyable();   
115                                     
116     public static final RowSpec DEFAULT_ROWSPEC = 
117         new RowSpec(Sizes.DEFAULT).asUnmodifyable();   
118                                     
119     public static final RowSpec GLUE_ROWSPEC = 
120         new RowSpec(RowSpec.DEFAULT, Sizes.ZERO, RowSpec.DEFAULT_GROW).asUnmodifyable();                               
121 
122     /*
123      * The following five constants use logical sizes that change with the
124      * layout style. A future release will likely defined them using a class
125      * <code>LogicalSize</code> or <code>StyledSize</code>.
126      */
127     public static final RowSpec RELATED_GAP_ROWSPEC =
128         createGapRowSpec(LayoutStyle.getCurrent().getRelatedComponentsPadY());
129         
130     public static final RowSpec UNRELATED_GAP_ROWSPEC =
131         createGapRowSpec(LayoutStyle.getCurrent().getUnrelatedComponentsPadY());
132         
133     public static final RowSpec LINE_GAP_ROWSPEC =
134         createGapRowSpec(LayoutStyle.getCurrent().getLinePad());
135 
136     public static final RowSpec NARROW_LINE_GAP_ROWSPEC =
137         createGapRowSpec(LayoutStyle.getCurrent().getNarrowLinePad());
138 
139     public static final RowSpec PARAGRAPH_GAP_ROWSPEC =
140         createGapRowSpec(LayoutStyle.getCurrent().getParagraphPad());
141         
142     
143     
144     // Factory Methods ******************************************************
145 
146     /**
147      * Creates and answers an instance of <code>FormLayout</code>
148      * to build forms with the specified number of major and minor columns.
149      * <p>
150      * The layout will use default values for all gaps.
151      * <p>
152      * <b>This method is work in progress and may be moved, removed, 
153      * or change without notice.</b>
154      *
155      * @param majorColumns     the number of used major columns
156      * @param minorColumns     the number of used minor columns
157      * @param labelColumnSpec  specifies the label columns
158      * @return a prepared <code>FormLayout</code>
159      */
160     public static FormLayout createColumnLayout(
161             int majorColumns,
162             int minorColumns,
163             ColumnSpec labelColumnSpec) {
164         return createColumnLayout(
165             majorColumns,
166             minorColumns,
167             labelColumnSpec,
168             Sizes.DLUX14,
169             Sizes.DLUX2);
170     }
171 
172     /**
173      * Creates and answers an instance of <code>FormLayout</code>
174      * to build forms with the given number of major columns. 
175      * Major columns consists of a label and a component section, where each 
176      * component section is divided into the given number of minor columns.
177      * <p>
178      * The layout will use the specified gaps to separate major columns, 
179      * and the label and component section.
180      * <p>
181      * <b>This method is work in progress and may be moved, removed, 
182      * or change without notice.</b>
183      * 
184      * @param majorColumns         the number of major columns
185      * @param minorColumns         the number of minor columns
186      * @param labelColumnSpec      specifies the label columns
187      * @param indent               an optional <code>ConstantSize</code> 
188      * that describes the width of the leading indent column
189      * @param minorColumnGap       a <code>ConstantSize</code> that describes
190      * the gap between minor columns
191      * @return a prepared <code>FormLayout</code>
192      */
193     public static FormLayout createColumnLayout(
194             int majorColumns,
195             int minorColumns,
196             ColumnSpec labelColumnSpec,
197             ConstantSize indent,
198             ConstantSize minorColumnGap) {
199         return createColumnLayout(
200             majorColumns, 
201             minorColumns, 
202             labelColumnSpec, 
203             PREF_COLSPEC, 
204             indent, 
205             Sizes.DLUX14, 
206             minorColumnGap);
207     }
208                 
209     /**
210      * Creates and answers an instance of <code>FormLayout</code>
211      * to build forms with the given number of major columns. 
212      * Major columns consists of a label and a component section, where each 
213      * component section is divided into the given number of minor columns.
214      * <p>
215      * The layout will use the specified gaps to separate major columns, 
216      * minor columns, and the label and component section.
217      * <p>
218      * <b>This method is work in progress and may be moved, removed, 
219      * or change without notice.</b>
220      * 
221      * @param majorColumns         the number of major columns
222      * @param minorColumns         the number of minor columns
223      * @param labelColumnSpec      specifies the label columns
224      * @param componentColumnSpec  specifies the label columns
225      * @param indent               an optional <code>ConstantSize</code> 
226      * that describes the width of the leading indent column
227      * @param majorColumnGap       a <code>ConstantSize</code> that describes
228      * the gap between major columns
229      * @param minorColumnGap       a <code>ConstantSize</code> that describes
230      * the gap between minor columns
231      * @return a prepared <code>FormLayout</code>
232      */
233     public static FormLayout createColumnLayout(
234             int majorColumns,
235             int minorColumns,
236             ColumnSpec labelColumnSpec,
237             ColumnSpec componentColumnSpec,
238             ConstantSize indent,
239             ConstantSize majorColumnGap,
240             ConstantSize minorColumnGap) {
241                 
242         ColumnSpec majorGapColSpec = createGapColumnSpec(majorColumnGap);
243         ColumnSpec minorGapColSpec = createGapColumnSpec(minorColumnGap);
244         FormLayout layout = new FormLayout(new ColumnSpec[]{}, new RowSpec[]{});
245 
246         // Add the optional leading indent.
247         if (indent != null) { 
248             layout.appendColumn(createGapColumnSpec(indent));
249         }
250         for (int i = 0; i < majorColumns; i++) {
251             // Add the optional label column with gap.
252             if (labelColumnSpec != null) {
253                 layout.appendColumn(labelColumnSpec);
254                 layout.appendColumn(RELATED_GAP_COLSPEC);
255             }
256             // Add the minor columns with separating gaps.
257             for (int j = 0; j < minorColumns; j++) {
258                 layout.appendColumn(componentColumnSpec);
259                 layout.addGroupedColumn(layout.getColumnCount());
260                 if (j < minorColumns - 1) {
261                     layout.appendColumn(minorGapColSpec);
262                 }
263             }
264             // Add a gap between major columns.
265             if (i < majorColumns - 1) { 
266                 layout.appendColumn(majorGapColSpec); 
267             }
268         }
269         return layout;
270     }
271 
272     
273     // Helper Code **********************************************************
274     
275     /**
276      * Creates and answers a {@link ColumnSpec} that represents a gap with the
277      * specified {@link ConstantSize}.
278      * 
279      * @param gapSize   a <code>ConstantSize</code> that specifies the gap
280      * @return an unmodifyable <code>ColumnSpec</code> that describes a horizontal gap
281      */
282     public static ColumnSpec createGapColumnSpec(ConstantSize gapSize) {
283         ColumnSpec spec = new ColumnSpec(ColumnSpec.LEFT, gapSize, ColumnSpec.NO_GROW);
284         return spec.asUnmodifyable();
285     }
286 
287     /**
288      * Creates and answers a {@link RowSpec} that represents a gap with the
289      * specified {@link ConstantSize}.
290      * 
291      * @param gapSize   a <code>ConstantSize</code> that specifies the gap
292      * @return an unmodifyable <code>RowSpec</code> that describes a vertical gap
293      */
294     public static RowSpec createGapRowSpec(ConstantSize gapSize) {
295         RowSpec spec = new RowSpec(RowSpec.TOP, gapSize, RowSpec.NO_GROW);
296         return spec.asUnmodifyable();
297     }
298     
299     
300 }
301
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags