001: /*
002: * Copyright (c) 2002-2007 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}.<p>
046: *
047: * This builder sets a hint for narrow margin for the gridded buttons.
048: * This can reduce the button stack's width if some buttons have long texts.
049: * For example, a stack with 'OK', 'Cancel', 'Configure...' will likely
050: * exceed the minimum button width. The narrow margins help getting narrow
051: * stacks.
052: * Note that some look&feels do not support the narrow margin feature,
053: * and conversely, others have only narrow margins. The JGoodies look&feels
054: * honor the setting, the Mac Aqua l&f uses narrow margins all the time.<p>
055: *
056: * <strong>Example:</strong><br>
057: * The following example builds a button stack with <i>Close, Up</i> and
058: * <i>Down</i>, where Up and Down are related, and Close is not related
059: * to the other buttons, which makes a wide gap for the unrelated and
060: * a smaller gap for the related buttons.
061: * <pre>
062: * private JPanel createCloseUpDownButtonStack(
063: * JButton close, JButton up, JButton down) {
064: * ButtonStackBuilder builder = new ButtonStackBuilder();
065: * builder.addGridded(close);
066: * builder.addUnrelatedGap();
067: * builder.addGridded(up);
068: * builder.addRelatedGap();
069: * builder.addGridded(down);
070: * return builder.getPanel();
071: * }
072: * </pre>
073: *
074: * @author Karsten Lentzsch
075: * @version $Revision: 1.2 $
076: *
077: * @see ButtonBarBuilder
078: * @see com.jgoodies.forms.factories.ButtonBarFactory
079: * @see com.jgoodies.forms.util.LayoutStyle
080: */
081: public final class ButtonStackBuilder extends PanelBuilder {
082:
083: /**
084: * Specifies the FormLayout's the single button stack column.
085: */
086: private static final ColumnSpec[] COL_SPECS = new ColumnSpec[] { FormFactory.BUTTON_COLSPEC };
087:
088: /**
089: * Specifies the rows of the initial FormLayout used in constructors.
090: */
091: private static final RowSpec[] ROW_SPECS = new RowSpec[] {};
092:
093: /**
094: * The client property key used to indicate that a button shall
095: * get narrow margins on the left and right hand side.<p>
096: *
097: * This optional setting will be honored by all JGoodies Look&Feel
098: * implementations. The Mac Aqua l&f uses narrow margins only.
099: * Other look&feel implementations will likely ignore this key
100: * and so may render a wider button margin.
101: */
102: private static final String NARROW_KEY = "jgoodies.isNarrow";
103:
104: // Instance Creation ****************************************************
105:
106: /**
107: * Constructs an instance of <code>ButtonStackBuilder</code> on a default
108: * <code>JPanel</code> using a preconfigured FormLayout as layout manager.
109: */
110: public ButtonStackBuilder() {
111: this (new JPanel(null));
112: }
113:
114: /**
115: * Constructs an instance of <code>ButtonStackBuilder</code> on the given
116: * panel using a preconfigured FormLayout as layout manager.
117: *
118: * @param panel the layout container
119: */
120: public ButtonStackBuilder(JPanel panel) {
121: super (new FormLayout(COL_SPECS, ROW_SPECS), panel);
122: }
123:
124: // Adding Components ****************************************************
125:
126: /**
127: * Adds a sequence of related buttons separated by a default gap.
128: *
129: * @param buttons an array of buttons to add
130: */
131: public void addButtons(JButton[] buttons) {
132: for (int i = 0; i < buttons.length; i++) {
133: addGridded(buttons[i]);
134: if (i < buttons.length - 1)
135: addRelatedGap();
136: }
137: }
138:
139: /**
140: * Adds a fixed size component.
141: *
142: * @param component the component to add
143: */
144: public void addFixed(JComponent component) {
145: getLayout().appendRow(FormFactory.PREF_ROWSPEC);
146: add(component);
147: nextRow();
148: }
149:
150: /**
151: * Adds a gridded component.
152: *
153: * @param component the component to add
154: */
155: public void addGridded(JComponent component) {
156: getLayout().appendRow(FormFactory.PREF_ROWSPEC);
157: getLayout().addGroupedRow(getRow());
158: component.putClientProperty(NARROW_KEY, Boolean.TRUE);
159: add(component);
160: nextRow();
161: }
162:
163: /**
164: * Adds a glue that will be given the extra space,
165: * if this box is larger than its preferred size.
166: */
167: public void addGlue() {
168: appendGlueRow();
169: nextRow();
170: }
171:
172: /**
173: * Adds the standard gap for related components.
174: */
175: public void addRelatedGap() {
176: appendRelatedComponentsGapRow();
177: nextRow();
178: }
179:
180: /**
181: * Adds the standard gap for unrelated components.
182: */
183: public void addUnrelatedGap() {
184: appendUnrelatedComponentsGapRow();
185: nextRow();
186: }
187:
188: /**
189: * Adds a strut of a specified size.
190: *
191: * @param size a constant that describes the gap
192: */
193: public void addStrut(ConstantSize size) {
194: getLayout().appendRow(
195: new RowSpec(RowSpec.TOP, size, RowSpec.NO_GROW));
196: nextRow();
197: }
198:
199: }
|