KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > swing > Box


1 /*
2  * @(#)Box.java 1.43 03/12/19
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */
7
8
9 package javax.swing;
10
11 import java.awt.*;
12 import java.awt.event.*;
13 import java.beans.PropertyChangeListener JavaDoc;
14 import java.util.Locale JavaDoc;
15 import java.io.Serializable JavaDoc;
16 import javax.accessibility.*;
17
18 /**
19  * A lightweight container
20  * that uses a BoxLayout object as its layout manager.
21  * Box provides several class methods
22  * that are useful for containers using BoxLayout --
23  * even non-Box containers.
24  *
25  * <p>
26  * The <code>Box</code> class can create several kinds
27  * of invisible components
28  * that affect layout:
29  * glue, struts, and rigid areas.
30  * If all the components your <code>Box</code> contains
31  * have a fixed size,
32  * you might want to use a glue component
33  * (returned by <code>createGlue</code>)
34  * to control the components' positions.
35  * If you need a fixed amount of space between two components,
36  * try using a strut
37  * (<code>createHorizontalStrut</code> or <code>createVerticalStrut</code>).
38  * If you need an invisible component
39  * that always takes up the same amount of space,
40  * get it by invoking <code>createRigidArea</code>.
41  * <p>
42  * If you are implementing a <code>BoxLayout</code> you
43  * can find further information and examples in
44  * <a
45  href="http://java.sun.com/docs/books/tutorial/uiswing/layout/box.html">How to Use BoxLayout</a>,
46  * a section in <em>The Java Tutorial.</em>
47  * <p>
48  * <strong>Warning:</strong>
49  * Serialized objects of this class will not be compatible with
50  * future Swing releases. The current serialization support is
51  * appropriate for short term storage or RMI between applications running
52  * the same version of Swing. As of 1.4, support for long term storage
53  * of all JavaBeans<sup><font size="-2">TM</font></sup>
54  * has been added to the <code>java.beans</code> package.
55  * Please see {@link java.beans.XMLEncoder}.
56  *
57  * @see BoxLayout
58  *
59  * @author Timothy Prinzing
60  * @version 1.43 12/19/03
61  */
62 public class Box extends JComponent JavaDoc implements Accessible {
63
64     /**
65      * Creates a <code>Box</code> that displays its components
66      * along the the specified axis.
67      *
68      * @param axis can be {@link BoxLayout#X_AXIS},
69      * {@link BoxLayout#Y_AXIS},
70      * {@link BoxLayout#LINE_AXIS} or
71      * {@link BoxLayout#PAGE_AXIS}.
72      * @throws AWTError if the <code>axis</code> is invalid
73      * @see #createHorizontalBox
74      * @see #createVerticalBox
75      */
76     public Box(int axis) {
77     super();
78     super.setLayout(new BoxLayout JavaDoc(this, axis));
79     }
80
81     /**
82      * Creates a <code>Box</code> that displays its components
83      * from left to right. If you want a <code>Box</code> that
84      * respects the component orientation you should create the
85      * <code>Box</code> using the constructor and pass in
86      * <code>BoxLayout.LINE_AXIS</code>, eg:
87      * <pre>
88      * Box lineBox = new Box(BoxLayout.LINE_AXIS);
89      * </pre>
90      *
91      * @return the box
92      */
93     public static Box JavaDoc createHorizontalBox() {
94     return new Box JavaDoc(BoxLayout.X_AXIS);
95     }
96
97     /**
98      * Creates a <code>Box</code> that displays its components
99      * from top to bottom. If you want a <code>Box</code> that
100      * respects the component orientation you should create the
101      * <code>Box</code> using the constructor and pass in
102      * <code>BoxLayout.PAGE_AXIS</code>, eg:
103      * <pre>
104      * Box lineBox = new Box(BoxLayout.PAGE_AXIS);
105      * </pre>
106      *
107      * @return the box
108      */
109     public static Box JavaDoc createVerticalBox() {
110     return new Box JavaDoc(BoxLayout.Y_AXIS);
111     }
112
113     /**
114      * Creates an invisible component that's always the specified size.
115      * <!-- WHEN WOULD YOU USE THIS AS OPPOSED TO A STRUT? -->
116      *
117      * @param d the dimensions of the invisible component
118      * @return the component
119      * @see #createGlue
120      * @see #createHorizontalStrut
121      * @see #createVerticalStrut
122      */
123     public static Component createRigidArea(Dimension d) {
124     return new Filler(d, d, d);
125     }
126
127     /**
128      * Creates an invisible, fixed-width component.
129      * In a horizontal box,
130      * you typically use this method
131      * to force a certain amount of space between two components.
132      * In a vertical box,
133      * you might use this method
134      * to force the box to be at least the specified width.
135      * The invisible component has no height
136      * unless excess space is available,
137      * in which case it takes its share of available space,
138      * just like any other component that has no maximum height.
139      *
140      * @param width the width of the invisible component, in pixels >= 0
141      * @return the component
142      * @see #createVerticalStrut
143      * @see #createGlue
144      * @see #createRigidArea
145      */
146     public static Component createHorizontalStrut(int width) {
147     return new Filler(new Dimension(width,0), new Dimension(width,0),
148               new Dimension(width, Short.MAX_VALUE));
149     }
150
151     /**
152      * Creates an invisible, fixed-height component.
153      * In a vertical box,
154      * you typically use this method
155      * to force a certain amount of space between two components.
156      * In a horizontal box,
157      * you might use this method
158      * to force the box to be at least the specified height.
159      * The invisible component has no width
160      * unless excess space is available,
161      * in which case it takes its share of available space,
162      * just like any other component that has no maximum width.
163      *
164      * @param height the height of the invisible component, in pixels >= 0
165      * @return the component
166      * @see #createHorizontalStrut
167      * @see #createGlue
168      * @see #createRigidArea
169      */
170     public static Component createVerticalStrut(int height) {
171     return new Filler(new Dimension(0,height), new Dimension(0,height),
172               new Dimension(Short.MAX_VALUE, height));
173     }
174
175     /**
176      * Creates an invisible "glue" component
177      * that can be useful in a Box
178      * whose visible components have a maximum width
179      * (for a horizontal box)
180      * or height (for a vertical box).
181      * You can think of the glue component
182      * as being a gooey substance
183      * that expands as much as necessary
184      * to fill the space between its neighboring components.
185      *
186      * <p>
187      *
188      * For example, suppose you have
189      * a horizontal box that contains two fixed-size components.
190      * If the box gets extra space,
191      * the fixed-size components won't become larger,
192     * so where does the extra space go?
193      * Without glue,
194      * the extra space goes to the right of the second component.
195      * If you put glue between the fixed-size components,
196      * then the extra space goes there.
197      * If you put glue before the first fixed-size component,
198      * the extra space goes there,
199      * and the fixed-size components are shoved against the right
200      * edge of the box.
201      * If you put glue before the first fixed-size component
202      * and after the second fixed-size component,
203      * the fixed-size components are centered in the box.
204      *
205      * <p>
206      *
207      * To use glue,
208      * call <code>Box.createGlue</code>
209      * and add the returned component to a container.
210      * The glue component has no minimum or preferred size,
211      * so it takes no space unless excess space is available.
212      * If excess space is available,
213      * then the glue component takes its share of available
214      * horizontal or vertical space,
215      * just like any other component that has no maximum width or height.
216      *
217      * @return the component
218      */
219     public static Component createGlue() {
220     return new Filler(new Dimension(0,0), new Dimension(0,0),
221               new Dimension(Short.MAX_VALUE, Short.MAX_VALUE));
222     }
223
224     /**
225      * Creates a horizontal glue component.
226      *
227      * @return the component
228      */
229     public static Component createHorizontalGlue() {
230     return new Filler(new Dimension(0,0), new Dimension(0,0),
231               new Dimension(Short.MAX_VALUE, 0));
232     }
233
234     /**
235      * Creates a vertical glue component.
236      *
237      * @return the component
238      */
239     public static Component createVerticalGlue() {
240     return new Filler(new Dimension(0,0), new Dimension(0,0),
241               new Dimension(0, Short.MAX_VALUE));
242     }
243
244     /**
245      * Throws an AWTError, since a Box can use only a BoxLayout.
246      *
247      * @param l the layout manager to use
248      */
249     public void setLayout(LayoutManager l) {
250     throw new AWTError("Illegal request");
251     }
252
253
254     /**
255      * An implementation of a lightweight component that participates in
256      * layout but has no view.
257      * <p>
258      * <strong>Warning:</strong>
259      * Serialized objects of this class will not be compatible with
260      * future Swing releases. The current serialization support is
261      * appropriate for short term storage or RMI between applications running
262      * the same version of Swing. As of 1.4, support for long term storage
263      * of all JavaBeans<sup><font size="-2">TM</font></sup>
264      * has been added to the <code>java.beans</code> package.
265      * Please see {@link java.beans.XMLEncoder}.
266      */
267     public static class Filler extends JComponent JavaDoc implements Accessible {
268
269     /**
270      * Constructor to create shape with the given size ranges.
271      *
272      * @param min Minimum size
273      * @param pref Preferred size
274      * @param max Maximum size
275      */
276         public Filler(Dimension min, Dimension pref, Dimension max) {
277         reqMin = min;
278         reqPref = pref;
279         reqMax = max;
280     }
281
282     /**
283      * Change the size requests for this shape. An invalidate() is
284      * propagated upward as a result so that layout will eventually
285      * happen with using the new sizes.
286      *
287      * @param min Value to return for getMinimumSize
288      * @param pref Value to return for getPreferredSize
289      * @param max Value to return for getMaximumSize
290      */
291         public void changeShape(Dimension min, Dimension pref, Dimension max) {
292         reqMin = min;
293         reqPref = pref;
294         reqMax = max;
295         invalidate();
296     }
297
298     // ---- Component methods ------------------------------------------
299
300         /**
301          * Returns the minimum size of the component.
302          *
303          * @return the size
304          */
305         public Dimension getMinimumSize() {
306         return reqMin;
307     }
308
309         /**
310          * Returns the preferred size of the component.
311          *
312          * @return the size
313          */
314         public Dimension getPreferredSize() {
315         return reqPref;
316     }
317
318         /**
319          * Returns the maximum size of the component.
320          *
321          * @return the size
322          */
323         public Dimension getMaximumSize() {
324         return reqMax;
325     }
326
327     // ---- member variables ---------------------------------------
328
329         private Dimension reqMin;
330         private Dimension reqPref;
331         private Dimension reqMax;
332
333 /////////////////
334 // Accessibility support for Box$Filler
335 ////////////////
336
337         /**
338          * The currently set AccessibleContext object.
339          */
340         protected AccessibleContext accessibleContext = null;
341
342         /**
343          * Gets the AccessibleContext associated with this Box.Filler.
344          * For box fillers, the AccessibleContext takes the form of an
345          * AccessibleBoxFiller.
346          * A new AccessibleAWTBoxFiller instance is created if necessary.
347          *
348          * @return an AccessibleBoxFiller that serves as the
349          * AccessibleContext of this Box.Filler.
350          */
351         public AccessibleContext getAccessibleContext() {
352         if (accessibleContext == null) {
353         accessibleContext = new AccessibleBoxFiller();
354         }
355         return accessibleContext;
356         }
357
358         /**
359          * This class implements accessibility support for the
360          * <code>Box.Filler</code> class.
361          */
362     protected class AccessibleBoxFiller extends AccessibleAWTComponent {
363             // AccessibleContext methods
364 //
365 /**
366              * Gets the role of this object.
367              *
368              * @return an instance of AccessibleRole describing the role of
369              * the object (AccessibleRole.FILLER)
370              * @see AccessibleRole
371              */
372             public AccessibleRole getAccessibleRole() {
373                 return AccessibleRole.FILLER;
374             }
375         }
376     }
377
378 /////////////////
379 // Accessibility support for Box
380 ////////////////
381
382     /**
383      * The currently set AccessibleContext object.
384      */
385     protected AccessibleContext accessibleContext = null;
386
387     /**
388      * Gets the AccessibleContext associated with this Box.
389      * For boxes, the AccessibleContext takes the form of an
390      * AccessibleBox.
391      * A new AccessibleAWTBox instance is created if necessary.
392      *
393      * @return an AccessibleBox that serves as the
394      * AccessibleContext of this Box
395      */
396     public AccessibleContext getAccessibleContext() {
397     if (accessibleContext == null) {
398         accessibleContext = new AccessibleBox();
399     }
400     return accessibleContext;
401     }
402
403     /**
404      * This class implements accessibility support for the
405      * <code>Box</code> class.
406      */
407     protected class AccessibleBox extends AccessibleAWTContainer {
408         // AccessibleContext methods
409 //
410 /**
411          * Gets the role of this object.
412          *
413          * @return an instance of AccessibleRole describing the role of the
414      * object (AccessibleRole.FILLER)
415          * @see AccessibleRole
416          */
417         public AccessibleRole getAccessibleRole() {
418             return AccessibleRole.FILLER;
419         }
420     } // inner class AccessibleBox
421 }
422
Popular Tags