KickJava   Java API By Example, From Geeks To Geeks.

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


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 javax.swing.JButton JavaDoc;
34 import javax.swing.JComponent JavaDoc;
35 import javax.swing.JPanel JavaDoc;
36
37 import com.jgoodies.forms.factories.Borders;
38 import com.jgoodies.forms.factories.FormFactory;
39 import com.jgoodies.forms.layout.ColumnSpec;
40 import com.jgoodies.forms.layout.ConstantSize;
41 import com.jgoodies.forms.layout.FormLayout;
42 import com.jgoodies.forms.layout.RowSpec;
43
44 /**
45  * A non-visual builder that assists you in building consistent button bars
46  * that comply with popular UI style guides. It utilizes the {@link FormLayout}.
47  * This class is in turn used by the
48  * {@link com.jgoodies.forms.factories.ButtonBarFactory} that provides
49  * an even higher level of abstraction for building consistent button bars.
50  * <p>
51  * Buttons added to the builder are either gridded or fixed and may fill
52  * their FormLayout cell or not. All gridded buttons get the same width,
53  * while fixed button use their own size. Gridded buttons honor
54  * the default minimum button width as specified by the current
55  * {@link com.jgoodies.forms.util.LayoutStyle}.
56  * <p>
57  * A button can optionally be declared as narrow, so that it has
58  * narrow margins if displayed with a JGoodies look&amp;feel.
59  * This is useful if you want to layout buttons with equal width
60  * even if a button has a large label. For example, in a bar with
61  * 'Add...', 'Remove', 'Properties...' you may declare the properties button
62  * to use narrow margins.
63  * <p>
64  * <b>Example:</b><br>
65  * The following example builds a button bar with <i>Help</i> button on the
66  * left-hand side and <i>OK, Cancel, Apply</i> buttons on the right-hand side.
67  * <pre>
68  * private JPanel createHelpOKCancelApplyBar(
69  * JButton help, JButton ok, JButton cancel, JButton apply) {
70  * ButtonBarBuilder builder = new ButtonBarBuilder();
71  * builder.addGridded(help);
72  * builder.addRelatedGap();
73  * builder.addGlue();
74  * builder.addGriddedButtons(new JButton[]{ok, cancel, apply});
75  * return builder.getPanel();
76  * }
77  * </pre>
78  *
79  * @author Karsten Lentzsch
80  * @version $Revision: 1.3 $
81  */
82 public final class ButtonBarBuilder extends PanelBuilder {
83     
84     private static final ColumnSpec[] COL_SPECS = new ColumnSpec[]{};
85     private static final RowSpec ROW_SPEC = new RowSpec("center:pref");
86     private static final RowSpec[] ROW_SPECS = new RowSpec[]{ROW_SPEC};
87     
88     private static final String JavaDoc NARROW_KEY = "jgoodies.isNarrow";
89     
90     
91     // Instance Creation ****************************************************
92
93     /**
94      * Constructs an instance of <code>ButtonBarBuilder</code> on the given
95      * panel.
96      *
97      * @param panel the layout container
98      */
99     public ButtonBarBuilder(JPanel JavaDoc panel) {
100         super(panel, new FormLayout(COL_SPECS, ROW_SPECS));
101     }
102
103     /**
104      * Constructs an instance of <code>ButtonBarBuilder</code> on a
105      * <code>JPanel</code>.
106      */
107     public ButtonBarBuilder() {
108         this(new JPanel JavaDoc());
109     }
110
111
112     // Default Borders ******************************************************
113
114     /**
115      * Sets a default border that has a gap in the bar's north.
116      */
117     public void setDefaultButtonBarGapBorder() {
118         getPanel().setBorder(Borders.BUTTON_BAR_GAP_BORDER);
119     }
120     
121     
122     // Adding Components ****************************************************
123
124     /**
125      * Adds a sequence of related gridded buttons separated by a default gap.
126      *
127      * @param buttons an array of buttons to add
128      */
129     public void addGriddedButtons(JButton JavaDoc[] buttons) {
130         for (int i = 0; i < buttons.length; i++) {
131             addGridded(buttons[i]);
132             if (i < buttons.length - 1)
133                 addRelatedGap();
134         }
135     }
136
137     /**
138      * Adds a sequence of narrow gridded buttons separated by a default gap.
139      *
140      * @param buttons an array of buttons to add
141      * @deprecated #addGriddedButtons already makes the borders narrow
142      */
143     public void addGriddedNarrowButtons(JButton JavaDoc[] buttons) {
144         for (int i = 0; i < buttons.length; i++) {
145             addGriddedNarrow(buttons[i]);
146             if (i < buttons.length - 1)
147                 addRelatedGap();
148         }
149     }
150     
151     /**
152      * Adds a sequence of gridded buttons that grow.
153      * The buttongs are separated by a default gap.
154      *
155      * @param buttons an array of buttons to add
156      */
157     public void addGriddedGrowingButtons(JButton JavaDoc[] buttons) {
158         for (int i = 0; i < buttons.length; i++) {
159             addGriddedGrowing(buttons[i]);
160             if (i < buttons.length - 1)
161                 addRelatedGap();
162         }
163     }
164     
165     /**
166      * Adds a fixed size component.
167      *
168      * @param component the component to add
169      */
170     public void addFixed(JComponent JavaDoc component) {
171         getLayout().appendColumn(FormFactory.PREF_COLSPEC);
172         add(component);
173         nextColumn();
174     }
175
176     /**
177      * Adds a fixed size component with narrow margins.
178      *
179      * @param component the component to add
180      */
181     public void addFixedNarrow(JComponent JavaDoc component) {
182         component.putClientProperty(NARROW_KEY, Boolean.TRUE);
183         addFixed(component);
184     }
185
186     /**
187      * Adds a gridded component.
188      *
189      * @param component the component to add
190      */
191     public void addGridded(JComponent JavaDoc component) {
192         getLayout().appendColumn(FormFactory.BUTTON_COLSPEC);
193         getLayout().addGroupedColumn(getColumn());
194         component.putClientProperty(NARROW_KEY, Boolean.TRUE);
195         add(component);
196         nextColumn();
197     }
198
199     /**
200      * Adds a gridded narrow component.
201      *
202      * @param component the component to add
203      * @deprecated #addGridded(JComponent) already makes the border narrow
204      */
205     public void addGriddedNarrow(JComponent JavaDoc component) {
206         addGridded(component);
207     }
208
209     /**
210      * Adds a gridded component that grows.
211      *
212      * @param component the component to add
213      */
214     public void addGriddedGrowing(JComponent JavaDoc component) {
215         getLayout().appendColumn(FormFactory.GROWING_BUTTON_COLSPEC);
216         getLayout().addGroupedColumn(getColumn());
217         component.putClientProperty(NARROW_KEY, Boolean.TRUE);
218         add(component);
219         nextColumn();
220     }
221
222     /**
223      * Adds a gridded, narrow component that grows.
224      *
225      * @param component the component to add
226      */
227     public void addGriddedGrowingNarrow(JComponent JavaDoc component) {
228         component.putClientProperty(NARROW_KEY, Boolean.TRUE);
229         addGriddedGrowing(component);
230     }
231
232     /**
233      * Adds a glue that will be given the extra space,
234      * if this box is larger than its preferred size.
235      */
236     public void addGlue() {
237         appendGlueColumn();
238         nextColumn();
239     }
240
241     /**
242      * Adds the standard gap for related components.
243      */
244     public void addRelatedGap() {
245         appendRelatedComponentsGapColumn();
246         nextColumn();
247     }
248
249     /**
250      * Adds the standard gap for unrelated components.
251      */
252     public void addUnrelatedGap() {
253         appendUnrelatedComponentsGapColumn();
254         nextColumn();
255     }
256
257     /**
258      * Adds a strut of a specified size.
259      *
260      * @param size a <code>ConstantSize</code> that describes the gap's size
261      */
262     public void addStrut(ConstantSize size) {
263         getLayout().appendColumn(new ColumnSpec(ColumnSpec.LEFT,
264                                                 size,
265                                                 ColumnSpec.NO_GROW));
266         nextColumn();
267     }
268     
269
270 }
271
Popular Tags