KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > jgoodies > forms > builder > AbstractFormBuilder


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.builder;
32
33 import java.awt.Component JavaDoc;
34 import java.awt.Container JavaDoc;
35
36 import com.jgoodies.forms.factories.FormFactory;
37 import com.jgoodies.forms.layout.CellConstraints;
38 import com.jgoodies.forms.layout.ColumnSpec;
39 import com.jgoodies.forms.layout.FormLayout;
40 import com.jgoodies.forms.layout.RowSpec;
41
42 /**
43  * An abstract class that minimizes the effort required to implement
44  * non-visual builders that use the {@link FormLayout}.
45  * <p>
46  * Builders hide details of the FormLayout and provide convenience behavior
47  * that assists you in constructing a form.
48  * This class provides a cell cursor that helps you traverse a form while
49  * you add components. Also, it offers several methods to append custom
50  * and logical columns and rows.
51  *
52  * @author Karsten Lentzsch
53  * @version $Revision: 1.2 $
54  * @see ButtonBarBuilder
55  * @see ButtonStackBuilder
56  * @see PanelBuilder
57  * @see com.jgoodies.forms.extras.I15dPanelBuilder
58  * @see com.jgoodies.forms.extras.DefaultFormBuilder
59  */
60 public abstract class AbstractFormBuilder {
61
62     /**
63      * Holds the layout container that we are building.
64      */
65     private final Container JavaDoc container;
66     
67     /**
68      * Holds the instance of <code>FormLayout</code> that is used to
69      * specifiy, fill and layout this form.
70      */
71     private final FormLayout layout;
72
73     /**
74      * Holds an instance of <code>CellConstraints</code> that will be used to
75      * specify the location, extent and alignments of the component to be
76      * added next.
77      */
78     private CellConstraints currentCellConstraints;
79     
80     /**
81      * Specifies if we fill the grid from left to right or right to left.
82      */
83     private boolean leftToRight = true;
84
85
86
87     // Instance Creation ****************************************************
88
89     /**
90      * Constructs an instance of <code>AbstractFormBuilder</code> for the given
91      * container and form layout.
92      *
93      * @param container the layout container
94      * @param layout the {@link FormLayout} to use
95      */
96     public AbstractFormBuilder(Container JavaDoc container, FormLayout layout){
97         this.container = container;
98         this.layout = layout;
99   
100         container.setLayout(layout);
101         currentCellConstraints = new CellConstraints();
102     }
103
104
105     // Accessors ************************************************************
106
107     /**
108      * Returns the container used to build the form.
109      *
110      * @return the layout container
111      */
112     public final Container JavaDoc getContainer() {
113         return container;
114     }
115
116     /**
117      * Returns the instance of {@link FormLayout} used to build this form.
118      *
119      * @return the FormLayout
120      */
121     public final FormLayout getLayout() {
122         return layout;
123     }
124     
125     /**
126      * Returns the number of columns in the form.
127      *
128      * @return the number of columns
129      */
130     public final int getColumnCount() {
131         return getLayout().getColumnCount();
132     }
133     
134     /**
135      * Returns the number of rows in the form.
136      *
137      * @return the number of rows
138      */
139     public final int getRowCount() {
140         return getLayout().getRowCount();
141     }
142     
143
144     // Accessing the Cursor Direction ***************************************
145
146     /**
147      * Returns whether this builder fills the form left-to-right
148      * or right-to-left.
149      *
150      * @return true indicates left-to-right, false indicates right-to-left
151      */
152     public final boolean isLeftToRight() {
153         return leftToRight;
154     }
155     
156     /**
157      * Sets the form fill direction to left-to-right or right-to-left.
158      *
159      * @param b true indicates left-to-right, false right-to-left
160      */
161     public final void setLeftToRight(boolean b) {
162         this.leftToRight = b;
163     }
164     
165
166     // Accessing the Cursor Location and Extent *****************************
167
168     /**
169      * Returns the cursor's column.
170      *
171      * @return the cursor's column
172      */
173     public final int getColumn() {
174         return currentCellConstraints.gridX;
175     }
176     
177     /**
178      * Sets the cursor to the given column.
179      *
180      * @param column the cursor's new column index
181      */
182     public final void setColumn(int column) {
183         currentCellConstraints.gridX = column;
184     }
185     
186     /**
187      * Returns the cursor's row.
188      *
189      * @return the cursor's row
190      */
191     public final int getRow() {
192         return currentCellConstraints.gridY;
193     }
194     
195     /**
196      * Sets the cursor to the given row.
197      *
198      * @param row the cursor's new row index
199      */
200     public final void setRow(int row) {
201         currentCellConstraints.gridY = row;
202     }
203     
204     /**
205      * Sets the cursor's column span.
206      *
207      * @param columnSpan the cursor's new column span (grid width)
208      */
209     public final void setColumnSpan(int columnSpan) {
210         currentCellConstraints.gridWidth = columnSpan;
211     }
212     
213     /**
214      * Sets the cursor's row span.
215      *
216      * @param rowSpan the cursor's new row span (grid height)
217      */
218     public final void setRowSpan(int rowSpan) {
219         currentCellConstraints.gridHeight = rowSpan;
220     }
221     
222     /**
223      * Sets the cursor's origin to the given column and row.
224      *
225      * @param column the new column index
226      * @param row the new row index
227      */
228     public final void setOrigin(int column, int row) {
229         setColumn(column);
230         setRow(row);
231     }
232     
233     /**
234      * Sets the cursor's extent to the given column span and row span.
235      *
236      * @param columnSpan the new column span (grid width)
237      * @param rowSpan the new row span (grid height)
238      */
239     public final void setExtent(int columnSpan, int rowSpan) {
240         setColumnSpan(columnSpan);
241         setRowSpan(rowSpan);
242     }
243     
244     /**
245      * Sets the cell bounds (location and extent) to the given column, row,
246      * column span and row span.
247      *
248      * @param column the new column index (grid x)
249      * @param row the new row index (grid y)
250      * @param columnSpan the new column span (grid width)
251      * @param rowSpan the new row span (grid height)
252      */
253     public final void setBounds(int column, int row, int columnSpan, int rowSpan) {
254         setColumn(column);
255         setRow(row);
256         setColumnSpan(columnSpan);
257         setRowSpan(rowSpan);
258     }
259     
260     /**
261      * Moves to the next column, does the same as #nextColumn(1).
262      */
263     public final void nextColumn() {
264         nextColumn(1);
265     }
266
267     /**
268      * Moves to the next column.
269      *
270      * @param columns number of columns to move
271      */
272     public final void nextColumn(int columns) {
273         currentCellConstraints.gridX += columns * getColumnIncrementSign();
274     }
275
276     /**
277      * Increases the row by one; does the same as #nextRow(1).
278      */
279     public final void nextRow() {
280         nextRow(1);
281     }
282
283     /**
284      * Increases the row by the specified rows.
285      *
286      * @param rows number of rows to move
287      */
288     public final void nextRow(int rows) {
289         currentCellConstraints.gridY += rows;
290     }
291     
292     /**
293      * Moves to the next line: increases the row and resets the column;
294      * does the same as #nextLine(1).
295      */
296     public final void nextLine() {
297         nextLine(1);
298     }
299
300     /**
301      * Moves the cursor down several lines: increases the row by the
302      * specified number of lines and sets the cursor to the leading column.
303      *
304      * @param lines number of rows to move
305      */
306     public final void nextLine(int lines) {
307         nextRow(lines);
308         setColumn(getLeadingColumn());
309     }
310     
311     
312     // Form Constraints Alignment *******************************************
313
314     /**
315      * Sets the horizontal alignment.
316      *
317      * @param alignment the new horizontal alignment
318      */
319     public final void setHAlignment(CellConstraints.Alignment alignment) {
320         currentCellConstraints.hAlign = alignment;
321     }
322
323     /**
324      * Sets the vertical alignment.
325      *
326      * @param alignment the new vertical alignment
327      */
328     public final void setVAlignment(CellConstraints.Alignment alignment) {
329         currentCellConstraints.vAlign = alignment;
330     }
331     
332     /**
333      * Sets the horizontal and vertical alignment.
334      *
335      * @param hAlign the new horizontal alignment
336      * @param vAlign the new vertical alignment
337      */
338     public final void setAlignment(CellConstraints.Alignment hAlign,
339                                     CellConstraints.Alignment vAlign) {
340         setHAlignment(hAlign);
341         setVAlignment(vAlign);
342     }
343
344     
345     // Adding Columns and Rows **********************************************
346
347     /**
348      * Appends the given column specification to the builder's layout.
349      *
350      * @param columnSpec the column specification to append
351      */
352     public final void appendColumn(ColumnSpec columnSpec) {
353         getLayout().appendColumn(columnSpec);
354     }
355
356     /**
357      * Appends a column specification to the builder's layout
358      * that represents the given string encoding.
359      *
360      * @param encodedColumnSpec the column specification to append
361      */
362     public final void appendColumn(String JavaDoc encodedColumnSpec) {
363         appendColumn(new ColumnSpec(encodedColumnSpec));
364     }
365
366     /**
367      * Appends a glue column.
368      */
369     public final void appendGlueColumn() {
370         appendColumn(FormFactory.GLUE_COLSPEC);
371     }
372     
373     /**
374      * Appends a column that is the default gap for related components.
375      */
376     public final void appendRelatedComponentsGapColumn() {
377         appendColumn(FormFactory.RELATED_GAP_COLSPEC);
378     }
379     
380     /**
381      * Appends a column that is the default gap for unrelated components.
382      */
383     public final void appendUnrelatedComponentsGapColumn() {
384         appendColumn(FormFactory.UNRELATED_GAP_COLSPEC);
385     }
386     
387     /**
388      * Appends the given row specification to the builder's layout.
389      *
390      * @param rowSpec the row specification to append
391      */
392     public final void appendRow(RowSpec rowSpec) {
393         getLayout().appendRow(rowSpec);
394     }
395
396     /**
397      * Appends a row specification to the builder's layout that represents
398      * the given string encoding.
399      *
400      * @param encodedRowSpec the row specification to append
401      */
402     public final void appendRow(String JavaDoc encodedRowSpec) {
403         appendRow(new RowSpec(encodedRowSpec));
404     }
405
406     /**
407      * Appends a glue row.
408      */
409     public final void appendGlueRow() {
410         appendRow(FormFactory.GLUE_ROWSPEC);
411     }
412     
413     /**
414      * Appends a row that is the default gap for related components.
415      */
416     public final void appendRelatedComponentsGapRow() {
417         appendRow(FormFactory.RELATED_GAP_ROWSPEC);
418     }
419     
420     /**
421      * Appends a row that is the default gap for unrelated components.
422      */
423     public final void appendUnrelatedComponentsGapRow() {
424         appendRow(FormFactory.UNRELATED_GAP_ROWSPEC);
425     }
426     
427
428     // Adding Components ****************************************************
429
430     /**
431      * Adds a component to the panel using the given cell constraints.
432      *
433      * @param component the component to add
434      * @param cellConstraints the component's cell constraints
435      * @return the added component
436      */
437     public final Component JavaDoc add(Component JavaDoc component, CellConstraints cellConstraints) {
438         container.add(component, cellConstraints);
439         return component;
440     }
441     
442     /**
443      * Adds a component to the panel using the given encoded cell constraints.
444      *
445      * @param component the component to add
446      * @param encodedCellConstraints the component's encoded cell constraints
447      * @return the added component
448      */
449     public final Component JavaDoc add(Component JavaDoc component, String JavaDoc encodedCellConstraints) {
450         container.add(component, new CellConstraints(encodedCellConstraints));
451         return component;
452     }
453     
454     /**
455      * Adds a component to the container using the default cell constraints.
456      *
457      * @param component the component to add
458      * @return the added component
459      */
460     public final Component JavaDoc add(Component JavaDoc component) {
461         add(component, currentCellConstraints);
462         return component;
463     }
464     
465     
466     // Misc *****************************************************************
467
468     /**
469      * Returns the cell constraints.
470      *
471      * @return the builder's current {@link CellConstraints}
472      */
473     protected final CellConstraints cellConstraints() {
474         return currentCellConstraints;
475     }
476     
477     /**
478      * Returns the leading column.
479      * <p>
480      * Subclasses may override this method, for example, if the form
481      * has a leading gap column that should not be filled with components.
482      *
483      * @return the leading column
484      */
485     protected int getLeadingColumn() {
486         return isLeftToRight() ? 1 : getColumnCount();
487     }
488     
489     /**
490      * Returns the sign (-1 or 1) used to increment the cursor's column
491      * when moving to the next column.
492      *
493      * @return -1 for right-to-left, 1 for left-to-right
494      */
495     protected final int getColumnIncrementSign() {
496         return isLeftToRight() ? 1 : -1;
497     }
498     
499
500 }
501
Popular Tags