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