KickJava   Java API By Example, From Geeks To Geeks.

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


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
35 import javax.swing.JComponent JavaDoc;
36 import javax.swing.JLabel JavaDoc;
37 import javax.swing.JPanel JavaDoc;
38 import javax.swing.SwingConstants JavaDoc;
39 import javax.swing.border.Border JavaDoc;
40
41 import com.jgoodies.forms.factories.Borders;
42 import com.jgoodies.forms.factories.ComponentFactory;
43 import com.jgoodies.forms.factories.DefaultComponentFactory;
44 import com.jgoodies.forms.layout.CellConstraints;
45 import com.jgoodies.forms.layout.FormLayout;
46
47 /**
48  * An general purpose panel builder that uses the {@link FormLayout}
49  * to layout <code>JPanel</code>s. It provides convenience methods
50  * to set a default border and to add labels, titles and titled separators.
51  * <p>
52  * The PanelBuilder is the working horse for layouts when more specialized
53  * builders like the {@link com.jgoodies.forms.builder.ButtonBarBuilder}
54  * or {@link com.jgoodies.forms.extras.DefaultFormBuilder} are inappropriate.
55  * <p>
56  * The Forms tutorial includes several examples that present and compare
57  * different style to build with the PanelBuilder: static row numbers
58  * vs. row variable, explicit CellConstraints vs. builder cursor,
59  * static rows vs. dynamically added rows. Also, you may check out the
60  * Tips &amp; Tricks section of the Forms HTML documentation.
61  * <p>
62  * <b>Example:</b><br>
63  * This example creates a panel with 3 columns and 3 rows.
64  * <pre>
65  * FormLayout layout = new FormLayout(
66  * "right:pref, 6dlu, 50dlu, 4dlu, default", // columns
67  * "pref, 3dlu, pref, 3dlu, pref"); // rows
68  *
69  * PanelBuilder builder = new PanelBuilder(layout);
70  * CellConstraints cc = new CellConstraints();
71  * builder.addLabel("Label1", cc.xy (1, 1));
72  * builder.add(new JTextField(), cc.xywh(3, 1, 3, 1));
73  * builder.addLabel("Label2", cc.xy (1, 3));
74  * builder.add(new JTextField(), cc.xy (3, 3));
75  * builder.addLabel("Label3", cc.xy (1, 5));
76  * builder.add(new JTextField(), cc.xy (3, 5));
77  * builder.add(new JButton("..."), cc.xy (5, 5));
78  * return builder.getPanel();
79  * </pre>
80  *
81  * @author Karsten Lentzsch
82  * @version $Revision: 1.3 $
83  * @see com.jgoodies.forms.extras.I15dPanelBuilder
84  * @see com.jgoodies.forms.extras.DefaultFormBuilder
85  */
86 public class PanelBuilder extends AbstractFormBuilder {
87     
88     /**
89      * Holds a factory that is used to create labels,
90      * titles and paragraph separators.
91      */
92     private ComponentFactory componentFactory;
93     
94
95     // Instance Creation ****************************************************
96
97     /**
98      * Constructs an instance of <code>PanelBuilder</code> for the given
99      * panel and layout.
100      *
101      * @param panel the layout container to build on
102      * @param layout the form layout to use
103      */
104     public PanelBuilder(JPanel JavaDoc panel, FormLayout layout){
105         super(panel, layout);
106     }
107
108     /**
109      * Constructs an instance of <code>PanelBuilder</code> for the given
110      * layout. Uses an instance of <code>JPanel</code> as layout container.
111      *
112      * @param layout the form layout to use
113      */
114     public PanelBuilder(FormLayout layout){
115         this(new JPanel JavaDoc(), layout);
116     }
117
118
119     // Accessors ************************************************************
120
121     /**
122      * Returns the panel used to build the form.
123      */
124     public final JPanel JavaDoc getPanel() {
125         return (JPanel JavaDoc) getContainer();
126     }
127
128
129     // Borders **************************************************************
130
131     /**
132      * Sets the panel's border.
133      *
134      * @param border the border to set
135      */
136     public final void setBorder(Border JavaDoc border) {
137         getPanel().setBorder(border);
138     }
139     
140     /**
141      * Sets the default dialog border.
142      */
143     public final void setDefaultDialogBorder() {
144         setBorder(Borders.DIALOG_BORDER);
145     }
146     
147
148     // Adding Labels **********************************************************
149
150     /**
151      * Adds a textual label to the form using the specified constraints.
152      *
153      * @param textWithMnemonic the label's text - may contain a mnemonic marker
154      * @param constraints the label's cell constraints
155      * @return the new label
156      */
157     public final JLabel JavaDoc addLabel(String JavaDoc textWithMnemonic, CellConstraints constraints) {
158         JLabel JavaDoc label = getComponentFactory().createLabel(textWithMnemonic);
159         add(label, constraints);
160         return label;
161     }
162     
163     /**
164      * Adds a textual label to the form using the specified constraints.
165      *
166      * @param textWithMnemonic the label's text - may contain a mnemonic marker
167      * @param encodedConstraints a string representation for the constraints
168      * @return the new label
169      */
170     public final JLabel JavaDoc addLabel(String JavaDoc textWithMnemonic, String JavaDoc encodedConstraints) {
171         return addLabel(textWithMnemonic, new CellConstraints(encodedConstraints));
172     }
173     
174     /**
175      * Adds a textual label to the form using the default constraints.
176      *
177      * @param textWithMnemonic the label's text - may contain a mnemonic marker
178      * @return the new label
179      */
180     public final JLabel JavaDoc addLabel(String JavaDoc textWithMnemonic) {
181         return addLabel(textWithMnemonic, cellConstraints());
182     }
183     
184
185     // Adding Label with related Component ************************************
186
187     /**
188      * Adds a label and component to the panel using the given cell constraints.
189      * Sets the given label as <i>the</i> component label using Label#setLabelFor.
190      *
191      * @param label the label to add
192      * @param labelConstraints the label's cell constraints
193      * @param component the component to add
194      * @param componentConstraints the component's cell constraints
195      * @return the added label
196      * @see javax.swing.JLabel#setLabelFor
197      */
198     public final JLabel JavaDoc add(JLabel JavaDoc label, CellConstraints labelConstraints,
199                              Component JavaDoc component, CellConstraints componentConstraints) {
200         add(label, labelConstraints);
201         add(component, componentConstraints);
202         label.setLabelFor(component);
203         return label;
204     }
205     
206     /**
207      * Adds a label and component to the panel using the given cell constraints.
208      * Sets the given label as <i>the</i> component label using Label#setLabelFor.
209      *
210      * @param textWithMnemonic the label's text - may contain a mnemonic marker
211      * @param labelConstraints the label's cell constraints
212      * @param component the component to add
213      * @param componentConstraints the component's cell constraints
214      * @return the added label
215      * @see javax.swing.JLabel#setLabelFor
216      */
217     public final JLabel JavaDoc addLabel(
218         String JavaDoc textWithMnemonic, CellConstraints labelConstraints,
219         Component JavaDoc component, CellConstraints componentConstraints) {
220         JLabel JavaDoc label = addLabel(textWithMnemonic, labelConstraints);
221         add(component, componentConstraints);
222         label.setLabelFor(component);
223         return label;
224     }
225     
226
227     // Adding Titles ----------------------------------------------------------
228
229     /**
230      * Adds a title label to the form using the specified constraints.
231      *
232      * @param text the label's title text
233      * @param constraints the separator's cell constraints
234      * @return the added title label
235      */
236     public final JLabel JavaDoc addTitle(String JavaDoc text, CellConstraints constraints) {
237         JLabel JavaDoc titleLabel = getComponentFactory().createTitle(text);
238         add(titleLabel, constraints);
239         return titleLabel;
240     }
241     
242     /**
243      * Adds a title label to the form using the specified constraints.
244      *
245      * @param text the label's text
246      * @param encodedConstraints a string representation for the constraints
247      * @return the added title label
248      */
249     public final JLabel JavaDoc addTitle(String JavaDoc text, String JavaDoc encodedConstraints) {
250         return addTitle(text, new CellConstraints(encodedConstraints));
251     }
252      
253     /**
254      * Adds a title label to the form using the default constraints.
255      *
256      * @param text the separator titel
257      * @return the added title label
258      */
259     public final JLabel JavaDoc addTitle(String JavaDoc text) {
260         return addTitle(text, cellConstraints());
261     }
262      
263
264     // Adding Separators ------------------------------------------------------
265
266     /**
267      * Adds a titled separator to the form using the specified constraints.
268      *
269      * @param text the separator title
270      * @param constraints the separator's cell constraints
271      * @return the added separator
272      */
273     public final JComponent JavaDoc addSeparator(String JavaDoc text, CellConstraints constraints) {
274         int titleAlignment =
275             getPanel().getComponentOrientation().isLeftToRight()
276                 ? SwingConstants.LEFT
277                 : SwingConstants.RIGHT;
278         JComponent JavaDoc titledSeparator =
279             getComponentFactory().createSeparator(text, titleAlignment);
280         add(titledSeparator, constraints);
281         return titledSeparator;
282     }
283     
284     /**
285      * Adds a titled separator to the form using the specified constraints.
286      *
287      * @param text the separator titel
288      * @param encodedConstraints a string representation for the constraints
289      * @return the added separator
290      */
291     public final JComponent JavaDoc addSeparator(String JavaDoc text, String JavaDoc encodedConstraints) {
292         return addSeparator(text, new CellConstraints(encodedConstraints));
293     }
294      
295     /**
296      * Adds a titled separator to the form that spans the specified columns.
297      *
298      * @param text the separator titel
299      * @param columnSpan the number of columns the separator spans
300      * @return the added separator
301      */
302     public final JComponent JavaDoc addSeparator(String JavaDoc text, int columnSpan) {
303         return addSeparator(text, new CellConstraints(getColumn(),
304                                                        getRow(),
305                                                        columnSpan,
306                                                        1));
307     }
308      
309     /**
310      * Adds a titled separator to the form that spans all columns.
311      *
312      * @param text the separator titel
313      * @return the added separator
314      */
315     public final JComponent JavaDoc addSeparator(String JavaDoc text) {
316         return addSeparator(text, getLayout().getColumnCount());
317     }
318     
319
320     // Accessing the ComponentFactory *****************************************
321
322     /**
323      * Returns the builder's component factory. If no factory
324      * has been set before, it is lazily initialized using with an instance of
325      * {@link com.jgoodies.forms.factories.DefaultComponentFactory}.
326      *
327      * @return the component factory
328      */
329     protected final ComponentFactory getComponentFactory() {
330         if (componentFactory == null) {
331             componentFactory = DefaultComponentFactory.getInstance();
332         }
333         return componentFactory;
334     }
335     
336     /**
337      * Sets a new component factory.
338      *
339      * @param newFactory the component factory to be set
340      */
341     protected final void setComponentFactory(ComponentFactory newFactory) {
342         componentFactory = newFactory;
343     }
344     
345     
346 }
347
Popular Tags