2
* Copyright (c) 2002-2004 JGoodies Karsten Lentzsch. All Rights Reserved.
4
* Redistribution and use in source and binary forms, with or without
5
* modification, are permitted provided that the following conditions are met:
7
* o Redistributions of source code must retain the above copyright notice,
8
* this list of conditions and the following disclaimer.
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.
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.
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.
31
package com.jgoodies.forms.builder;
33
import java.awt.Component;
34
import java.awt.ComponentOrientation;
35
import java.awt.Container;
37
import com.jgoodies.forms.factories.FormFactory;
38
import com.jgoodies.forms.layout.CellConstraints;
39
import com.jgoodies.forms.layout.ColumnSpec;
40
import com.jgoodies.forms.layout.FormLayout;
41
import com.jgoodies.forms.layout.RowSpec;
44
* An abstract class that minimizes the effort required to implement
45
* non-visual builders that use the {@link FormLayout}.<p>
47
* Builders hide details of the FormLayout and provide convenience behavior
48
* that assists you in constructing a form.
49
* This class provides a cell cursor that helps you traverse a form while
50
* you add components. Also, it offers several methods to append custom
51
* and logical columns and rows.
53
* @author Karsten Lentzsch
54
* @version $Revision: 1.8 $
56
* @see ButtonBarBuilder
57
* @see ButtonStackBuilder
59
* @see I15dPanelBuilder
60
* @see DefaultFormBuilder
62
public abstract class AbstractFormBuilder {
65
* Holds the layout container that we are building.
67
private final Container container;
70
* Holds the instance of <code>FormLayout</code> that is used to
71
* specifiy, fill and layout this form.
73
private final FormLayout layout;
76
* Holds an instance of <code>CellConstraints</code> that will be used to
77
* specify the location, extent and alignments of the component to be
80
private CellConstraints currentCellConstraints;
83
* Specifies if we fill the grid from left to right or right to left.
84
* This value is initialized during the construction from the layout
85
* container's component orientation.
87
* @see #isLeftToRight()
88
* @see #setLeftToRight(boolean)
89
* @see ComponentOrientation
91
private boolean leftToRight;
95
// Instance Creation ****************************************************
98
* Constructs an instance of <code>AbstractFormBuilder</code>
99
* for the given FormLayout and layout container.
101
* @param layout the {@link FormLayout} to use
102
* @param container the layout container
104
* @throws NullPointerException if the layout or container is null
106
public AbstractFormBuilder(FormLayout layout, Container container) {
108
throw new NullPointerException("The layout must not be null.");
110
if (container == null)
111
throw new NullPointerException("The layout container must not be null.");
113
this.container = container;
114
this.layout = layout;
116
container.setLayout(layout);
117
currentCellConstraints = new CellConstraints();
118
ComponentOrientation orientation = container.getComponentOrientation();
119
leftToRight = orientation.isLeftToRight()
120
|| !orientation.isHorizontal();
125
* Constructs an instance of <code>AbstractFormBuilder</code> for the given
126
* container and form layout.
128
* @param container the layout container
129
* @param layout the {@link FormLayout} to use
131
* @deprecated Replaced by {@link #AbstractFormBuilder(FormLayout, Container)}.
133
public AbstractFormBuilder(Container container, FormLayout layout){
134
this(layout, container);
138
// Accessors ************************************************************
141
* Returns the container used to build the form.
143
* @return the layout container
145
public final Container getContainer() {
151
* Returns the instance of {@link FormLayout} used to build this form.
153
* @return the FormLayout
155
public final FormLayout getLayout() {
161
* Returns the number of columns in the form.
163
* @return the number of columns
165
public final int getColumnCount() {
166
return getLayout().getColumnCount();
171
* Returns the number of rows in the form.
173
* @return the number of rows
175
public final int getRowCount() {
176
return getLayout().getRowCount();
180
// Accessing the Cursor Direction ***************************************
183
* Returns whether this builder fills the form left-to-right
184
* or right-to-left. The initial value of this property is set
185
* during the builder construction from the layout container's
186
* <code>componentOrientation</code> property.
188
* @return true indicates left-to-right, false indicates right-to-left
190
* @see #setLeftToRight(boolean)
191
* @see ComponentOrientation
193
public final boolean isLeftToRight() {
199
* Sets the form fill direction to left-to-right or right-to-left.
200
* The initial value of this property is set during the builder construction
201
* from the layout container's <code>componentOrientation</code> property.
203
* @param b true indicates left-to-right, false right-to-left
205
* @see #isLeftToRight()
206
* @see ComponentOrientation
208
public final void setLeftToRight(boolean b) {
213
// Accessing the Cursor Location and Extent *****************************
216
* Returns the cursor's column.
218
* @return the cursor's column
220
public final int getColumn() {
221
return currentCellConstraints.gridX;
226
* Sets the cursor to the given column.
228
* @param column the cursor's new column index
230
public final void setColumn(int column) {
231
currentCellConstraints.gridX = column;
236
* Returns the cursor's row.
238
* @return the cursor's row
240
public final int getRow() {
241
return currentCellConstraints.gridY;
246
* Sets the cursor to the given row.
248
* @param row the cursor's new row index
250
public final void setRow(int row) {
251
currentCellConstraints.gridY = row;
256
* Sets the cursor's column span.
258
* @param columnSpan the cursor's new column span (grid width)
260
public final void setColumnSpan(int columnSpan) {
261
currentCellConstraints.gridWidth = columnSpan;
266
* Sets the cursor's row span.
268
* @param rowSpan the cursor's new row span (grid height)
270
public final void setRowSpan(int rowSpan) {
271
currentCellConstraints.gridHeight = rowSpan;
276
* Sets the cursor's origin to the given column and row.
278
* @param column the new column index
279
* @param row the new row index
281
public final void setOrigin(int column, int row) {
288
* Sets the cursor's extent to the given column span and row span.
290
* @param columnSpan the new column span (grid width)
291
* @param rowSpan the new row span (grid height)
293
public final void setExtent(int columnSpan, int rowSpan) {
294
setColumnSpan(columnSpan);
300
* Sets the cell bounds (location and extent) to the given column, row,
301
* column span and row span.
303
* @param column the new column index (grid x)
304
* @param row the new row index (grid y)
305
* @param columnSpan the new column span (grid width)
306
* @param rowSpan the new row span (grid height)
308
public final void setBounds(int column, int row, int columnSpan, int rowSpan) {
311
setColumnSpan(columnSpan);
317
* Moves to the next column, does the same as #nextColumn(1).
319
public final void nextColumn() {
325
* Moves to the next column.
327
* @param columns number of columns to move
329
public final void nextColumn(int columns) {
330
currentCellConstraints.gridX += columns * getColumnIncrementSign();
335
* Increases the row by one; does the same as #nextRow(1).
337
public final void nextRow() {
343
* Increases the row by the specified rows.
345
* @param rows number of rows to move
347
public final void nextRow(int rows) {
348
currentCellConstraints.gridY += rows;
353
* Moves to the next line: increases the row and resets the column;
354
* does the same as #nextLine(1).
356
public final void nextLine() {
362
* Moves the cursor down several lines: increases the row by the
363
* specified number of lines and sets the cursor to the leading column.
365
* @param lines number of rows to move
367
public final void nextLine(int lines) {
369
setColumn(getLeadingColumn());
373
// Form Constraints Alignment *******************************************
376
* Sets the horizontal alignment.
378
* @param alignment the new horizontal alignment
380
public final void setHAlignment(CellConstraints.Alignment alignment) {
381
currentCellConstraints.hAlign = alignment;
385
* Sets the vertical alignment.
387
* @param alignment the new vertical alignment
389
public final void setVAlignment(CellConstraints.Alignment alignment) {
390
currentCellConstraints.vAlign = alignment;
395
* Sets the horizontal and vertical alignment.
397
* @param hAlign the new horizontal alignment
398
* @param vAlign the new vertical alignment
400
public final void setAlignment(CellConstraints.Alignment hAlign,
401
CellConstraints.Alignment vAlign) {
402
setHAlignment(hAlign);
403
setVAlignment(vAlign);
407
// Appending Columns ******************************************************
410
* Appends the given column specification to the builder's layout.
412
* @param columnSpec the column specification object to append
414
* @see #appendColumn(String)
416
public final void appendColumn(ColumnSpec columnSpec) {
417
getLayout().appendColumn(columnSpec);
422
* Appends a column specification to the builder's layout
423
* that represents the given string encoding.
425
* @param encodedColumnSpec the column specification to append in encoded form
427
* @see #appendColumn(ColumnSpec)
429
public final void appendColumn(String encodedColumnSpec) {
430
appendColumn(new ColumnSpec(encodedColumnSpec));
435
* Appends a glue column.
437
* @see #appendLabelComponentsGapColumn()
438
* @see #appendRelatedComponentsGapColumn()
439
* @see #appendUnrelatedComponentsGapColumn()
441
public final void appendGlueColumn() {
442
appendColumn(FormFactory.GLUE_COLSPEC);
447
* Appends a column that is the default gap between a label and
448
* its associated component.
452
* @see #appendGlueColumn()
453
* @see #appendRelatedComponentsGapColumn()
454
* @see #appendUnrelatedComponentsGapColumn()
456
public final void appendLabelComponentsGapColumn() {
457
appendColumn(FormFactory.LABEL_COMPONENT_GAP_COLSPEC);
462
* Appends a column that is the default gap for related components.
464
* @see #appendGlueColumn()
465
* @see #appendLabelComponentsGapColumn()
466
* @see #appendUnrelatedComponentsGapColumn()
468
public final void appendRelatedComponentsGapColumn() {
469
appendColumn(FormFactory.RELATED_GAP_COLSPEC);
474
* Appends a column that is the default gap for unrelated components.
476
* @see #appendGlueColumn()
477
* @see #appendLabelComponentsGapColumn()
478
* @see #appendRelatedComponentsGapColumn()
480
public final void appendUnrelatedComponentsGapColumn() {
481
appendColumn(FormFactory.UNRELATED_GAP_COLSPEC);
485
// Appending Rows ********************************************************
488
* Appends the given row specification to the builder's layout.
490
* @param rowSpec the row specification object to append
492
* @see #appendRow(String)
494
public final void appendRow(RowSpec rowSpec) {
495
getLayout().appendRow(rowSpec);
500
* Appends a row specification to the builder's layout that represents
501
* the given string encoding.
503
* @param encodedRowSpec the row specification to append in encoded form
505
* @see #appendRow(RowSpec)
507
public final void appendRow(String encodedRowSpec) {
508
appendRow(new RowSpec(encodedRowSpec));
513
* Appends a glue row.
515
* @see #appendRelatedComponentsGapRow()
516
* @see #appendUnrelatedComponentsGapRow()
517
* @see #appendParagraphGapRow()
519
public final void appendGlueRow() {
520
appendRow(FormFactory.GLUE_ROWSPEC);
525
* Appends a row that is the default gap for related components.
527
* @see #appendGlueRow()
528
* @see #appendUnrelatedComponentsGapRow()
529
* @see #appendParagraphGapRow()
531
public final void appendRelatedComponentsGapRow() {
532
appendRow(FormFactory.RELATED_GAP_ROWSPEC);
537
* Appends a row that is the default gap for unrelated components.
539
* @see #appendGlueRow()
540
* @see #appendRelatedComponentsGapRow()
541
* @see #appendParagraphGapRow()
543
public final void appendUnrelatedComponentsGapRow() {
544
appendRow(FormFactory.UNRELATED_GAP_ROWSPEC);
549
* Appends a row that is the default gap for paragraphs.
553
* @see #appendGlueRow()
554
* @see #appendRelatedComponentsGapRow()
555
* @see #appendUnrelatedComponentsGapRow()
557
public final void appendParagraphGapRow() {
558
appendRow(FormFactory.PARAGRAPH_GAP_ROWSPEC);
562
// Adding Components ****************************************************
565
* Adds a component to the panel using the given cell constraints.
567
* @param component the component to add
568
* @param cellConstraints the component's cell constraints
569
* @return the added component
571
public final Component add(Component component, CellConstraints cellConstraints) {
572
container.add(component, cellConstraints);
578
* Adds a component to the panel using the given encoded cell constraints.
580
* @param component the component to add
581
* @param encodedCellConstraints the component's encoded cell constraints
582
* @return the added component
584
public final Component add(Component component, String encodedCellConstraints) {
585
container.add(component, new CellConstraints(encodedCellConstraints));
591
* Adds a component to the container using the default cell constraints.
592
* Note that when building from left to right, this method won't adjust
593
* the cell constraints if the column span is larger than 1. In this case
594
* you should use {@link #add(Component, CellConstraints)} with a cell
595
* constraints object created by {@link #createLeftAdjustedConstraints(int)}.
597
* @param component the component to add
598
* @return the added component
600
* @see #add(Component, CellConstraints)
601
* @see #createLeftAdjustedConstraints(int)
603
public final Component add(Component component) {
604
add(component, currentCellConstraints);
609
// Misc *****************************************************************
612
* Returns the CellConstraints object that is used as a cursor and
613
* holds the current column span and row span.
615
* @return the builder's current {@link CellConstraints} object
617
protected final CellConstraints cellConstraints() {
618
return currentCellConstraints;
623
* Returns the index of the leading column.<p>
625
* Subclasses may override this method, for example, if the form
626
* has a leading gap column that should not be filled with components.
628
* @return the leading column
630
protected int getLeadingColumn() {
631
return isLeftToRight() ? 1 : getColumnCount();
636
* Returns the sign (-1 or 1) used to increment the cursor's column
637
* when moving to the next column.
639
* @return -1 for right-to-left, 1 for left-to-right
641
protected final int getColumnIncrementSign() {
642
return isLeftToRight() ? 1 : -1;
647
* Creates and returns a <code>CellConstraints</code> object at
648
* the current cursor position that uses the given column span
649
* and is adjusted to the left. Useful when building from right to left.
651
* @param columnSpan the column span to be used in the constraints
652
* @return CellConstraints adjusted to the left hand side
654
protected final CellConstraints createLeftAdjustedConstraints(int columnSpan) {
655
int firstColumn = isLeftToRight()
657
: getColumn() + 1 - columnSpan;
658
return new CellConstraints(firstColumn, getRow(),
660
cellConstraints().gridHeight);
added
removed
src/main/com/jgoodies/forms/builder/AbstractFormBuilder.java
