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 java.awt.Component;
034: import java.util.MissingResourceException;
035: import java.util.ResourceBundle;
036:
037: import javax.swing.JComponent;
038: import javax.swing.JLabel;
039: import javax.swing.JPanel;
040:
041: import com.jgoodies.forms.layout.CellConstraints;
042: import com.jgoodies.forms.layout.FormLayout;
043:
044: /**
045: * A general purpose panel builder that uses the {@link FormLayout} to lay out
046: * <code>JPanel</code>s. In addition to its superclass {@link PanelBuilder}
047: * this class provides convenience behavior to map resource keys to their
048: * associated internationalized (i15d) strings when adding labels, titles and
049: * titled separators.
050: * <p>
051: *
052: * The localized texts used in methods <code>#addI15dLabel</code> and
053: * <code>#addI15dTitle</code> can contain an optional mnemonic marker. The
054: * mnemonic and mnemonic index are indicated by a single ampersand (<tt>&</tt>).
055: * For example <tt>"&Save"</tt>, or
056: * <tt>"Save &as"</tt>. To use the ampersand itself,
057: * duplicate it, for example <tt>"Look&&Feel"</tt>.
058: * <p>
059: *
060: * @author Karsten Lentzsch
061: * @version $Revision: 1.2 $
062: * @since 1.0.3
063: *
064: * @see ResourceBundle
065: */
066: public class I15dPanelBuilder extends PanelBuilder {
067:
068: /**
069: * Holds the <code>ResourceBundle</code> used to lookup internationalized
070: * (i15d) String resources.
071: */
072: private final ResourceBundle bundle;
073:
074: // Instance Creation ****************************************************
075:
076: /**
077: * Constructs an instance of <code>I15dPanelBuilder</code> for the given
078: * layout. Uses an instance of <code>JPanel</code> as layout container.
079: *
080: * @param layout
081: * the form layout used to layout the container
082: * @param bundle
083: * the resource bundle used to lookup i15d strings
084: */
085: public I15dPanelBuilder(FormLayout layout, ResourceBundle bundle) {
086: this (new JPanel(null), layout, bundle);
087: }
088:
089: /**
090: * Constructs an instance of <code>I15dPanelBuilder</code> for the given
091: * FormLayout and layout container.
092: *
093: * @param layout
094: * the <code>FormLayout</code> used to layout the container
095: * @param bundle
096: * the <code>ResourceBundle</code> used to lookup i15d strings
097: * @param panel
098: * the layout container
099: */
100: public I15dPanelBuilder(FormLayout layout, ResourceBundle bundle,
101: JPanel panel) {
102: super (layout, panel);
103: this .bundle = bundle;
104: }
105:
106: /**
107: * Constructs an instance of <code>I15dPanelBuilder</code> for the given
108: * FormLayout and layout container.
109: *
110: * @param panel
111: * the layout container
112: * @param bundle
113: * the <code>ResourceBundle</code> used to lookup i15d strings
114: * @param layout
115: * the <code>FormLayout</code> used to layout the container
116: *
117: * @deprecated Replaced by
118: * {@link #I15dPanelBuilder(FormLayout, ResourceBundle, JPanel)}.
119: */
120: public I15dPanelBuilder(JPanel panel, FormLayout layout,
121: ResourceBundle bundle) {
122: this (layout, bundle, panel);
123: }
124:
125: // Adding Labels and Separators *****************************************
126:
127: /**
128: * Adds an internationalized (i15d) textual label to the form using the
129: * specified constraints.
130: *
131: * @param resourceKey
132: * the resource key for the label's text
133: * @param constraints
134: * the label's cell constraints
135: * @return the added label
136: */
137: public final JLabel addI15dLabel(String resourceKey,
138: CellConstraints constraints) {
139: return addLabel(getI15dString(resourceKey), constraints);
140: }
141:
142: /**
143: * Adds an internationalized (i15d) textual label to the form using the
144: * specified constraints.
145: *
146: * @param resourceKey
147: * the resource key for the label's text
148: * @param encodedConstraints
149: * a string representation for the constraints
150: * @return the added label
151: */
152: public final JLabel addI15dLabel(String resourceKey,
153: String encodedConstraints) {
154: return addI15dLabel(resourceKey, new CellConstraints(
155: encodedConstraints));
156: }
157:
158: /**
159: * Adds an internationalized (i15d) label and component to the panel using
160: * the given cell constraints. Sets the label as <i>the</i> component label
161: * using {@link JLabel#setLabelFor(java.awt.Component)}.
162: * <p>
163: *
164: * <strong>Note:</strong> The {@link CellConstraints} objects for the label
165: * and the component must be different. Cell constraints are implicitly
166: * cloned by the <code>FormLayout</code> when added to the container.
167: * However, in this case you may be tempted to reuse a
168: * <code>CellConstraints</code> object in the same way as with many other
169: * builder methods that require a single <code>CellConstraints</code>
170: * parameter. The pitfall is that the methods
171: * <code>CellConstraints.xy**(...)</code> just set the coordinates but do
172: * <em>not</em> create a new instance. And so the second invocation of
173: * <code>xy***(...)</code> overrides the settings performed in the first
174: * invocation before the object is cloned by the <code>FormLayout</code>.
175: * <p>
176: *
177: * <strong>Wrong:</strong>
178: *
179: * <pre>
180: * builder.add("name.key", cc.xy(1, 7), // will be modified by the code below
181: * nameField, cc.xy(3, 7) // sets the single instance to (3, 7)
182: * );
183: * </pre>
184: *
185: * <strong>Correct:</strong>
186: *
187: * <pre>
188: * builder.add("name.key", cc.xy(1, 7).clone(), // cloned before the next modification
189: * nameField, cc.xy(3, 7) // sets this instance to (3, 7)
190: * );
191: * </pre>
192: *
193: * @param resourceKey
194: * the resource key for the label
195: * @param labelConstraints
196: * the label's cell constraints
197: * @param component
198: * the component to add
199: * @param componentConstraints
200: * the component's cell constraints
201: * @return the added label
202: * @throws IllegalArgumentException
203: * if the same cell constraints instance is used for the label
204: * and the component
205: * @see JLabel#setLabelFor(java.awt.Component)
206: */
207: public final JLabel addI15dLabel(String resourceKey,
208: CellConstraints labelConstraints, Component component,
209: CellConstraints componentConstraints) {
210:
211: return addLabel(getI15dString(resourceKey), labelConstraints,
212: component, componentConstraints);
213: }
214:
215: /**
216: * Adds an internationalized (i15d) titled separator to the form using the
217: * specified constraints.
218: *
219: * @param resourceKey
220: * the resource key for the separator title
221: * @param constraints
222: * the separator's cell constraints
223: * @return the added titled separator
224: */
225: public final JComponent addI15dSeparator(String resourceKey,
226: CellConstraints constraints) {
227: return addSeparator(getI15dString(resourceKey), constraints);
228: }
229:
230: /**
231: * Adds an internationalized (i15d) titled separator to the form using the
232: * specified constraints.
233: *
234: * @param resourceKey
235: * the resource key for the separator titel
236: * @param encodedConstraints
237: * a string representation for the constraints
238: * @return the added titled separator
239: */
240: public final JComponent addI15dSeparator(String resourceKey,
241: String encodedConstraints) {
242: return addI15dSeparator(resourceKey, new CellConstraints(
243: encodedConstraints));
244: }
245:
246: /**
247: * Adds a title to the form using the specified constraints.
248: *
249: * @param resourceKey
250: * the resource key for the separator title
251: * @param constraints
252: * the separator's cell constraints
253: * @return the added title label
254: */
255: public final JLabel addI15dTitle(String resourceKey,
256: CellConstraints constraints) {
257: return addTitle(getI15dString(resourceKey), constraints);
258: }
259:
260: /**
261: * Adds a title to the form using the specified constraints.
262: *
263: * @param resourceKey
264: * the resource key for the separator titel
265: * @param encodedConstraints
266: * a string representation for the constraints
267: * @return the added title label
268: */
269: public final JLabel add15dTitle(String resourceKey,
270: String encodedConstraints) {
271: return addI15dTitle(resourceKey, new CellConstraints(
272: encodedConstraints));
273: }
274:
275: // Helper Code **********************************************************
276:
277: /**
278: * Looks up and returns the internationalized (i15d) string for the given
279: * resource key from the <code>ResourceBundle</code>.
280: *
281: * @param resourceKey
282: * the key to look for in the resource bundle
283: * @return the associated internationalized string, or the resource key
284: * itself in case of a missing resource
285: * @throws IllegalStateException
286: * if no <code>ResourceBundle</code> has been set
287: */
288: protected String getI15dString(String resourceKey) {
289: if (bundle == null)
290: throw new IllegalStateException(
291: "You must specify a ResourceBundle"
292: + " before using the internationalization support.");
293: try {
294: return bundle.getString(resourceKey);
295: } catch (MissingResourceException mre) {
296: return resourceKey;
297: }
298: }
299:
300: }
|