001: /*
002: * Copyright (c) 2002-2004 JGoodies Karsten Lentzsch. All Rights Reserved.
003: *
004: * Redistribution and use in source and binary forms, with or without
005: * modification, are permitted provided that the following conditions are met:
006: *
007: * o Redistributions of source code must retain the above copyright notice,
008: * this list of conditions and the following disclaimer.
009: *
010: * o Redistributions in binary form must reproduce the above copyright notice,
011: * this list of conditions and the following disclaimer in the documentation
012: * and/or other materials provided with the distribution.
013: *
014: * o Neither the name of JGoodies Karsten Lentzsch nor the names of
015: * its contributors may be used to endorse or promote products derived
016: * from this software without specific prior written permission.
017: *
018: * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
019: * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
020: * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
021: * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
022: * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
023: * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
024: * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
025: * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
026: * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
027: * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
028: * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
029: */
030:
031: package com.jgoodies.forms.builder;
032:
033: import javax.swing.JButton;
034: import javax.swing.JComponent;
035: import javax.swing.JPanel;
036:
037: import com.jgoodies.forms.factories.FormFactory;
038: import com.jgoodies.forms.layout.ColumnSpec;
039: import com.jgoodies.forms.layout.ConstantSize;
040: import com.jgoodies.forms.layout.FormLayout;
041: import com.jgoodies.forms.layout.RowSpec;
042:
043: /**
044: * A non-visual builder that assists you in building consistent button stacks
045: * using the {@link FormLayout}.
046: * <p>
047: *
048: * This builder sets a hint for narrow margin for the gridded buttons. This can
049: * reduce the button stack's width if some buttons have long texts. For example,
050: * a stack with 'OK', 'Cancel', 'Configure...' will likely exceed the minimum
051: * button width. The narrow margins help getting narrow stacks. Note that some
052: * look&feels do not support the narrow margin feature, and conversely,
053: * others have only narrow margins. The JGoodies look&feels honor the
054: * setting, the Mac Aqua l&f uses narrow margins all the time.
055: * <p>
056: *
057: * <strong>Example:</strong><br>
058: * The following example builds a button stack with <i>Close, Up</i> and
059: * <i>Down</i>, where Up and Down are related, and Close is not related to the
060: * other buttons, which makes a wide gap for the unrelated and a smaller gap for
061: * the related buttons.
062: *
063: * <pre>
064: * private JPanel createCloseUpDownButtonStack(JButton close, JButton up, JButton down) {
065: * ButtonStackBuilder builder = new ButtonStackBuilder();
066: * builder.addGridded(close);
067: * builder.addUnrelatedGap();
068: * builder.addGridded(up);
069: * builder.addRelatedGap();
070: * builder.addGridded(down);
071: * return builder.getPanel();
072: * }
073: * </pre>
074: *
075: * @author Karsten Lentzsch
076: * @version $Revision: 1.2 $
077: *
078: * @see ButtonBarBuilder
079: * @see com.jgoodies.forms.factories.ButtonBarFactory
080: * @see com.jgoodies.forms.util.LayoutStyle
081: */
082: public final class ButtonStackBuilder extends PanelBuilder {
083:
084: /**
085: * Specifies the FormLayout's the single button stack column.
086: */
087: private static final ColumnSpec[] COL_SPECS = new ColumnSpec[] { FormFactory.BUTTON_COLSPEC };
088:
089: /**
090: * Specifies the rows of the initial FormLayout used in constructors.
091: */
092: private static final RowSpec[] ROW_SPECS = new RowSpec[] {};
093:
094: /**
095: * The client property key used to indicate that a button shall get narrow
096: * margins on the left and right hand side.
097: * <p>
098: *
099: * This optional setting will be honored by all JGoodies Look&Feel
100: * implementations. The Mac Aqua l&f uses narrow margins only. Other
101: * look&feel implementations will likely ignore this key and so may
102: * render a wider button margin.
103: */
104: private static final String NARROW_KEY = "jgoodies.isNarrow";
105:
106: // Instance Creation ****************************************************
107:
108: /**
109: * Constructs an instance of <code>ButtonStackBuilder</code> on a default
110: * <code>JPanel</code> using a preconfigured FormLayout as layout manager.
111: */
112: public ButtonStackBuilder() {
113: this (new JPanel(null));
114: }
115:
116: /**
117: * Constructs an instance of <code>ButtonStackBuilder</code> on the given
118: * panel using a preconfigured FormLayout as layout manager.
119: *
120: * @param panel
121: * the layout container
122: */
123: public ButtonStackBuilder(JPanel panel) {
124: super (new FormLayout(COL_SPECS, ROW_SPECS), panel);
125: }
126:
127: // Adding Components ****************************************************
128:
129: /**
130: * Adds a sequence of related buttons separated by a default gap.
131: *
132: * @param buttons
133: * an array of buttons to add
134: */
135: public void addButtons(JButton[] buttons) {
136: for (int i = 0; i < buttons.length; i++) {
137: addGridded(buttons[i]);
138: if (i < buttons.length - 1)
139: addRelatedGap();
140: }
141: }
142:
143: /**
144: * Adds a fixed size component.
145: *
146: * @param component
147: * the component to add
148: */
149: public void addFixed(JComponent component) {
150: getLayout().appendRow(FormFactory.PREF_ROWSPEC);
151: add(component);
152: nextRow();
153: }
154:
155: /**
156: * Adds a gridded component.
157: *
158: * @param component
159: * the component to add
160: */
161: public void addGridded(JComponent component) {
162: getLayout().appendRow(FormFactory.PREF_ROWSPEC);
163: getLayout().addGroupedRow(getRow());
164: component.putClientProperty(NARROW_KEY, Boolean.TRUE);
165: add(component);
166: nextRow();
167: }
168:
169: /**
170: * Adds a glue that will be given the extra space, if this box is larger
171: * than its preferred size.
172: */
173: public void addGlue() {
174: appendGlueRow();
175: nextRow();
176: }
177:
178: /**
179: * Adds the standard gap for related components.
180: */
181: public void addRelatedGap() {
182: appendRelatedComponentsGapRow();
183: nextRow();
184: }
185:
186: /**
187: * Adds the standard gap for unrelated components.
188: */
189: public void addUnrelatedGap() {
190: appendUnrelatedComponentsGapRow();
191: nextRow();
192: }
193:
194: /**
195: * Adds a strut of a specified size.
196: *
197: * @param size
198: * a constant that describes the gap
199: */
200: public void addStrut(ConstantSize size) {
201: getLayout().appendRow(
202: new RowSpec(RowSpec.TOP, size, RowSpec.NO_GROW));
203: nextRow();
204: }
205:
206: }
|