001 /*
002 * Copyright 1997-2007 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package javax.swing;
027
028 import java.awt.*;
029 import java.awt.event.*;
030 import java.beans.ConstructorProperties;
031 import java.util.Locale;
032 import java.io.Serializable;
033 import javax.accessibility.*;
034
035 /**
036 * A lightweight container
037 * that uses a BoxLayout object as its layout manager.
038 * Box provides several class methods
039 * that are useful for containers using BoxLayout --
040 * even non-Box containers.
041 *
042 * <p>
043 * The <code>Box</code> class can create several kinds
044 * of invisible components
045 * that affect layout:
046 * glue, struts, and rigid areas.
047 * If all the components your <code>Box</code> contains
048 * have a fixed size,
049 * you might want to use a glue component
050 * (returned by <code>createGlue</code>)
051 * to control the components' positions.
052 * If you need a fixed amount of space between two components,
053 * try using a strut
054 * (<code>createHorizontalStrut</code> or <code>createVerticalStrut</code>).
055 * If you need an invisible component
056 * that always takes up the same amount of space,
057 * get it by invoking <code>createRigidArea</code>.
058 * <p>
059 * If you are implementing a <code>BoxLayout</code> you
060 * can find further information and examples in
061 * <a
062 href="http://java.sun.com/docs/books/tutorial/uiswing/layout/box.html">How to Use BoxLayout</a>,
063 * a section in <em>The Java Tutorial.</em>
064 * <p>
065 * <strong>Warning:</strong>
066 * Serialized objects of this class will not be compatible with
067 * future Swing releases. The current serialization support is
068 * appropriate for short term storage or RMI between applications running
069 * the same version of Swing. As of 1.4, support for long term storage
070 * of all JavaBeans<sup><font size="-2">TM</font></sup>
071 * has been added to the <code>java.beans</code> package.
072 * Please see {@link java.beans.XMLEncoder}.
073 *
074 * @see BoxLayout
075 *
076 * @author Timothy Prinzing
077 * @version 1.50 05/05/07
078 */
079 public class Box extends JComponent implements Accessible {
080
081 /**
082 * Creates a <code>Box</code> that displays its components
083 * along the the specified axis.
084 *
085 * @param axis can be {@link BoxLayout#X_AXIS},
086 * {@link BoxLayout#Y_AXIS},
087 * {@link BoxLayout#LINE_AXIS} or
088 * {@link BoxLayout#PAGE_AXIS}.
089 * @throws AWTError if the <code>axis</code> is invalid
090 * @see #createHorizontalBox
091 * @see #createVerticalBox
092 */
093 public Box(int axis) {
094 super ();
095 super .setLayout(new BoxLayout(this , axis));
096 }
097
098 /**
099 * Creates a <code>Box</code> that displays its components
100 * from left to right. If you want a <code>Box</code> that
101 * respects the component orientation you should create the
102 * <code>Box</code> using the constructor and pass in
103 * <code>BoxLayout.LINE_AXIS</code>, eg:
104 * <pre>
105 * Box lineBox = new Box(BoxLayout.LINE_AXIS);
106 * </pre>
107 *
108 * @return the box
109 */
110 public static Box createHorizontalBox() {
111 return new Box(BoxLayout.X_AXIS);
112 }
113
114 /**
115 * Creates a <code>Box</code> that displays its components
116 * from top to bottom. If you want a <code>Box</code> that
117 * respects the component orientation you should create the
118 * <code>Box</code> using the constructor and pass in
119 * <code>BoxLayout.PAGE_AXIS</code>, eg:
120 * <pre>
121 * Box lineBox = new Box(BoxLayout.PAGE_AXIS);
122 * </pre>
123 *
124 * @return the box
125 */
126 public static Box createVerticalBox() {
127 return new Box(BoxLayout.Y_AXIS);
128 }
129
130 /**
131 * Creates an invisible component that's always the specified size.
132 * <!-- WHEN WOULD YOU USE THIS AS OPPOSED TO A STRUT? -->
133 *
134 * @param d the dimensions of the invisible component
135 * @return the component
136 * @see #createGlue
137 * @see #createHorizontalStrut
138 * @see #createVerticalStrut
139 */
140 public static Component createRigidArea(Dimension d) {
141 return new Filler(d, d, d);
142 }
143
144 /**
145 * Creates an invisible, fixed-width component.
146 * In a horizontal box,
147 * you typically use this method
148 * to force a certain amount of space between two components.
149 * In a vertical box,
150 * you might use this method
151 * to force the box to be at least the specified width.
152 * The invisible component has no height
153 * unless excess space is available,
154 * in which case it takes its share of available space,
155 * just like any other component that has no maximum height.
156 *
157 * @param width the width of the invisible component, in pixels >= 0
158 * @return the component
159 * @see #createVerticalStrut
160 * @see #createGlue
161 * @see #createRigidArea
162 */
163 public static Component createHorizontalStrut(int width) {
164 return new Filler(new Dimension(width, 0), new Dimension(width,
165 0), new Dimension(width, Short.MAX_VALUE));
166 }
167
168 /**
169 * Creates an invisible, fixed-height component.
170 * In a vertical box,
171 * you typically use this method
172 * to force a certain amount of space between two components.
173 * In a horizontal box,
174 * you might use this method
175 * to force the box to be at least the specified height.
176 * The invisible component has no width
177 * unless excess space is available,
178 * in which case it takes its share of available space,
179 * just like any other component that has no maximum width.
180 *
181 * @param height the height of the invisible component, in pixels >= 0
182 * @return the component
183 * @see #createHorizontalStrut
184 * @see #createGlue
185 * @see #createRigidArea
186 */
187 public static Component createVerticalStrut(int height) {
188 return new Filler(new Dimension(0, height), new Dimension(0,
189 height), new Dimension(Short.MAX_VALUE, height));
190 }
191
192 /**
193 * Creates an invisible "glue" component
194 * that can be useful in a Box
195 * whose visible components have a maximum width
196 * (for a horizontal box)
197 * or height (for a vertical box).
198 * You can think of the glue component
199 * as being a gooey substance
200 * that expands as much as necessary
201 * to fill the space between its neighboring components.
202 *
203 * <p>
204 *
205 * For example, suppose you have
206 * a horizontal box that contains two fixed-size components.
207 * If the box gets extra space,
208 * the fixed-size components won't become larger,
209 * so where does the extra space go?
210 * Without glue,
211 * the extra space goes to the right of the second component.
212 * If you put glue between the fixed-size components,
213 * then the extra space goes there.
214 * If you put glue before the first fixed-size component,
215 * the extra space goes there,
216 * and the fixed-size components are shoved against the right
217 * edge of the box.
218 * If you put glue before the first fixed-size component
219 * and after the second fixed-size component,
220 * the fixed-size components are centered in the box.
221 *
222 * <p>
223 *
224 * To use glue,
225 * call <code>Box.createGlue</code>
226 * and add the returned component to a container.
227 * The glue component has no minimum or preferred size,
228 * so it takes no space unless excess space is available.
229 * If excess space is available,
230 * then the glue component takes its share of available
231 * horizontal or vertical space,
232 * just like any other component that has no maximum width or height.
233 *
234 * @return the component
235 */
236 public static Component createGlue() {
237 return new Filler(new Dimension(0, 0), new Dimension(0, 0),
238 new Dimension(Short.MAX_VALUE, Short.MAX_VALUE));
239 }
240
241 /**
242 * Creates a horizontal glue component.
243 *
244 * @return the component
245 */
246 public static Component createHorizontalGlue() {
247 return new Filler(new Dimension(0, 0), new Dimension(0, 0),
248 new Dimension(Short.MAX_VALUE, 0));
249 }
250
251 /**
252 * Creates a vertical glue component.
253 *
254 * @return the component
255 */
256 public static Component createVerticalGlue() {
257 return new Filler(new Dimension(0, 0), new Dimension(0, 0),
258 new Dimension(0, Short.MAX_VALUE));
259 }
260
261 /**
262 * Throws an AWTError, since a Box can use only a BoxLayout.
263 *
264 * @param l the layout manager to use
265 */
266 public void setLayout(LayoutManager l) {
267 throw new AWTError("Illegal request");
268 }
269
270 /**
271 * Paints this <code>Box</code>. If this <code>Box</code> has a UI this
272 * method invokes super's implementation, otherwise if this
273 * <code>Box</code> is opaque the <code>Graphics</code> is filled
274 * using the background.
275 *
276 * @param g the <code>Graphics</code> to paint to
277 * @throws NullPointerException if <code>g</code> is null
278 * @since 1.6
279 */
280 protected void paintComponent(Graphics g) {
281 if (ui != null) {
282 // On the off chance some one created a UI, honor it
283 super .paintComponent(g);
284 } else if (isOpaque()) {
285 g.setColor(getBackground());
286 g.fillRect(0, 0, getWidth(), getHeight());
287 }
288 }
289
290 /**
291 * An implementation of a lightweight component that participates in
292 * layout but has no view.
293 * <p>
294 * <strong>Warning:</strong>
295 * Serialized objects of this class will not be compatible with
296 * future Swing releases. The current serialization support is
297 * appropriate for short term storage or RMI between applications running
298 * the same version of Swing. As of 1.4, support for long term storage
299 * of all JavaBeans<sup><font size="-2">TM</font></sup>
300 * has been added to the <code>java.beans</code> package.
301 * Please see {@link java.beans.XMLEncoder}.
302 */
303 public static class Filler extends JComponent implements Accessible {
304
305 /**
306 * Constructor to create shape with the given size ranges.
307 *
308 * @param min Minimum size
309 * @param pref Preferred size
310 * @param max Maximum size
311 */
312 @ConstructorProperties({"minimumSize","preferredSize","maximumSize"})
313 public Filler(Dimension min, Dimension pref, Dimension max) {
314 setMinimumSize(min);
315 setPreferredSize(pref);
316 setMaximumSize(max);
317 }
318
319 /**
320 * Change the size requests for this shape. An invalidate() is
321 * propagated upward as a result so that layout will eventually
322 * happen with using the new sizes.
323 *
324 * @param min Value to return for getMinimumSize
325 * @param pref Value to return for getPreferredSize
326 * @param max Value to return for getMaximumSize
327 */
328 public void changeShape(Dimension min, Dimension pref,
329 Dimension max) {
330 setMinimumSize(min);
331 setPreferredSize(pref);
332 setMaximumSize(max);
333 revalidate();
334 }
335
336 // ---- Component methods ------------------------------------------
337
338 /**
339 * Paints this <code>Filler</code>. If this
340 * <code>Filler</code> has a UI this method invokes super's
341 * implementation, otherwise if this <code>Filler</code> is
342 * opaque the <code>Graphics</code> is filled using the
343 * background.
344 *
345 * @param g the <code>Graphics</code> to paint to
346 * @throws NullPointerException if <code>g</code> is null
347 * @since 1.6
348 */
349 protected void paintComponent(Graphics g) {
350 if (ui != null) {
351 // On the off chance some one created a UI, honor it
352 super .paintComponent(g);
353 } else if (isOpaque()) {
354 g.setColor(getBackground());
355 g.fillRect(0, 0, getWidth(), getHeight());
356 }
357 }
358
359 /////////////////
360 // Accessibility support for Box$Filler
361 ////////////////
362
363 /**
364 * Gets the AccessibleContext associated with this Box.Filler.
365 * For box fillers, the AccessibleContext takes the form of an
366 * AccessibleBoxFiller.
367 * A new AccessibleAWTBoxFiller instance is created if necessary.
368 *
369 * @return an AccessibleBoxFiller that serves as the
370 * AccessibleContext of this Box.Filler.
371 */
372 public AccessibleContext getAccessibleContext() {
373 if (accessibleContext == null) {
374 accessibleContext = new AccessibleBoxFiller();
375 }
376 return accessibleContext;
377 }
378
379 /**
380 * This class implements accessibility support for the
381 * <code>Box.Filler</code> class.
382 */
383 protected class AccessibleBoxFiller extends
384 AccessibleAWTComponent {
385 // AccessibleContext methods
386 //
387 /**
388 * Gets the role of this object.
389 *
390 * @return an instance of AccessibleRole describing the role of
391 * the object (AccessibleRole.FILLER)
392 * @see AccessibleRole
393 */
394 public AccessibleRole getAccessibleRole() {
395 return AccessibleRole.FILLER;
396 }
397 }
398 }
399
400 /////////////////
401 // Accessibility support for Box
402 ////////////////
403
404 /**
405 * Gets the AccessibleContext associated with this Box.
406 * For boxes, the AccessibleContext takes the form of an
407 * AccessibleBox.
408 * A new AccessibleAWTBox instance is created if necessary.
409 *
410 * @return an AccessibleBox that serves as the
411 * AccessibleContext of this Box
412 */
413 public AccessibleContext getAccessibleContext() {
414 if (accessibleContext == null) {
415 accessibleContext = new AccessibleBox();
416 }
417 return accessibleContext;
418 }
419
420 /**
421 * This class implements accessibility support for the
422 * <code>Box</code> class.
423 */
424 protected class AccessibleBox extends AccessibleAWTContainer {
425 // AccessibleContext methods
426 //
427 /**
428 * Gets the role of this object.
429 *
430 * @return an instance of AccessibleRole describing the role of the
431 * object (AccessibleRole.FILLER)
432 * @see AccessibleRole
433 */
434 public AccessibleRole getAccessibleRole() {
435 return AccessibleRole.FILLER;
436 }
437 } // inner class AccessibleBox
438 }
|