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.beans.ConstructorProperties; 31 import java.io.Serializable; 32 import java.io.PrintStream; 33 34 /** 35 * A layout manager that allows multiple components to be laid out either 36 * vertically or horizontally. The components will not wrap so, for 37 * example, a vertical arrangement of components will stay vertically 38 * arranged when the frame is resized. 39 * <TABLE STYLE="FLOAT:RIGHT" BORDER="0" SUMMARY="layout"> 40 * <TR> 41 * <TD ALIGN="CENTER"> 42 * <P STYLE="TEXT-ALIGN:CENTER"><IMG SRC="doc-files/BoxLayout-1.gif" 43 * alt="The following text describes this graphic." 44 * WIDTH="191" HEIGHT="201" STYLE="FLOAT:BOTTOM; BORDER:0"> 45 * </TD> 46 * </TR> 47 * </TABLE> 48 * <p> 49 * Nesting multiple panels with different combinations of horizontal and 50 * vertical gives an effect similar to GridBagLayout, without the 51 * complexity. The diagram shows two panels arranged horizontally, each 52 * of which contains 3 components arranged vertically. 53 * 54 * <p> The BoxLayout manager is constructed with an axis parameter that 55 * specifies the type of layout that will be done. There are four choices: 56 * 57 * <blockquote><b><tt>X_AXIS</tt></b> - Components are laid out horizontally 58 * from left to right.</blockquote> 59 * 60 * <blockquote><b><tt>Y_AXIS</tt></b> - Components are laid out vertically 61 * from top to bottom.</blockquote> 62 * 63 * <blockquote><b><tt>LINE_AXIS</tt></b> - Components are laid out the way 64 * words are laid out in a line, based on the container's 65 * <tt>ComponentOrientation</tt> property. If the container's 66 * <tt>ComponentOrientation</tt> is horizontal then components are laid out 67 * horizontally, otherwise they are laid out vertically. For horizontal 68 * orientations, if the container's <tt>ComponentOrientation</tt> is left to 69 * right then components are laid out left to right, otherwise they are laid 70 * out right to left. For vertical orientations components are always laid out 71 * from top to bottom.</blockquote> 72 * 73 * <blockquote><b><tt>PAGE_AXIS</tt></b> - Components are laid out the way 74 * text lines are laid out on a page, based on the container's 75 * <tt>ComponentOrientation</tt> property. If the container's 76 * <tt>ComponentOrientation</tt> is horizontal then components are laid out 77 * vertically, otherwise they are laid out horizontally. For horizontal 78 * orientations, if the container's <tt>ComponentOrientation</tt> is left to 79 * right then components are laid out left to right, otherwise they are laid 80 * out right to left. For vertical orientations components are always 81 * laid out from top to bottom.</blockquote> 82 * <p> 83 * For all directions, components are arranged in the same order as they were 84 * added to the container. 85 * <p> 86 * BoxLayout attempts to arrange components 87 * at their preferred widths (for horizontal layout) 88 * or heights (for vertical layout). 89 * For a horizontal layout, 90 * if not all the components are the same height, 91 * BoxLayout attempts to make all the components 92 * as high as the highest component. 93 * If that's not possible for a particular component, 94 * then BoxLayout aligns that component vertically, 95 * according to the component's Y alignment. 96 * By default, a component has a Y alignment of 0.5, 97 * which means that the vertical center of the component 98 * should have the same Y coordinate as 99 * the vertical centers of other components with 0.5 Y alignment. 100 * <p> 101 * Similarly, for a vertical layout, 102 * BoxLayout attempts to make all components in the column 103 * as wide as the widest component. 104 * If that fails, it aligns them horizontally 105 * according to their X alignments. For <code>PAGE_AXIS</code> layout, 106 * horizontal alignment is done based on the leading edge of the component. 107 * In other words, an X alignment value of 0.0 means the left edge of a 108 * component if the container's <code>ComponentOrientation</code> is left to 109 * right and it means the right edge of the component otherwise. 110 * <p> 111 * Instead of using BoxLayout directly, many programs use the Box class. 112 * The Box class is a lightweight container that uses a BoxLayout. 113 * It also provides handy methods to help you use BoxLayout well. 114 * Adding components to multiple nested boxes is a powerful way to get 115 * the arrangement you want. 116 * <p> 117 * For further information and examples see 118 * <a 119 href="https://docs.oracle.com/javase/tutorial/uiswing/layout/box.html">How to Use BoxLayout</a>, 120 * a section in <em>The Java Tutorial.</em> 121 * <p> 122 * <strong>Warning:</strong> 123 * Serialized objects of this class will not be compatible with 124 * future Swing releases. The current serialization support is 125 * appropriate for short term storage or RMI between applications running 126 * the same version of Swing. As of 1.4, support for long term storage 127 * of all JavaBeans™ 128 * has been added to the <code>java.beans</code> package. 129 * Please see {@link java.beans.XMLEncoder}. 130 * 131 * @see Box 132 * @see java.awt.ComponentOrientation 133 * @see JComponent#getAlignmentX 134 * @see JComponent#getAlignmentY 135 * 136 * @author Timothy Prinzing 137 */ 138 @SuppressWarnings("serial") 139 public class BoxLayout implements LayoutManager2, Serializable { 140 141 /** 142 * Specifies that components should be laid out left to right. 143 */ 144 public static final int X_AXIS = 0; 145 146 /** 147 * Specifies that components should be laid out top to bottom. 148 */ 149 public static final int Y_AXIS = 1; 150 151 /** 152 * Specifies that components should be laid out in the direction of 153 * a line of text as determined by the target container's 154 * <code>ComponentOrientation</code> property. 155 */ 156 public static final int LINE_AXIS = 2; 157 158 /** 159 * Specifies that components should be laid out in the direction that 160 * lines flow across a page as determined by the target container's 161 * <code>ComponentOrientation</code> property. 162 */ 163 public static final int PAGE_AXIS = 3; 164 165 /** 166 * Creates a layout manager that will lay out components along the 167 * given axis. 168 * 169 * @param target the container that needs to be laid out 170 * @param axis the axis to lay out components along. Can be one of: 171 * <code>BoxLayout.X_AXIS</code>, 172 * <code>BoxLayout.Y_AXIS</code>, 173 * <code>BoxLayout.LINE_AXIS</code> or 174 * <code>BoxLayout.PAGE_AXIS</code> 175 * 176 * @exception AWTError if the value of <code>axis</code> is invalid 177 */ 178 @ConstructorProperties({"target", "axis"}) 179 public BoxLayout(Container target, int axis) { 180 if (axis != X_AXIS && axis != Y_AXIS && 181 axis != LINE_AXIS && axis != PAGE_AXIS) { 182 throw new AWTError("Invalid axis"); 183 } 184 this.axis = axis; 185 this.target = target; 186 } 187 188 /** 189 * Constructs a BoxLayout that 190 * produces debugging messages. 191 * 192 * @param target the container that needs to be laid out 193 * @param axis the axis to lay out components along. Can be one of: 194 * <code>BoxLayout.X_AXIS</code>, 195 * <code>BoxLayout.Y_AXIS</code>, 196 * <code>BoxLayout.LINE_AXIS</code> or 197 * <code>BoxLayout.PAGE_AXIS</code> 198 * 199 * @param dbg the stream to which debugging messages should be sent, 200 * null if none 201 */ 202 BoxLayout(Container target, int axis, PrintStream dbg) { 203 this(target, axis); 204 this.dbg = dbg; 205 } 206 207 /** 208 * Returns the container that uses this layout manager. 209 * 210 * @return the container that uses this layout manager 211 * 212 * @since 1.6 213 */ 214 public final Container getTarget() { 215 return this.target; 216 } 217 218 /** 219 * Returns the axis that was used to lay out components. 220 * Returns one of: 221 * <code>BoxLayout.X_AXIS</code>, 222 * <code>BoxLayout.Y_AXIS</code>, 223 * <code>BoxLayout.LINE_AXIS</code> or 224 * <code>BoxLayout.PAGE_AXIS</code> 225 * 226 * @return the axis that was used to lay out components 227 * 228 * @since 1.6 229 */ 230 public final int getAxis() { 231 return this.axis; 232 } 233 234 /** 235 * Indicates that a child has changed its layout related information, 236 * and thus any cached calculations should be flushed. 237 * <p> 238 * This method is called by AWT when the invalidate method is called 239 * on the Container. Since the invalidate method may be called 240 * asynchronously to the event thread, this method may be called 241 * asynchronously. 242 * 243 * @param target the affected container 244 * 245 * @exception AWTError if the target isn't the container specified to the 246 * BoxLayout constructor 247 */ 248 public synchronized void invalidateLayout(Container target) { 249 checkContainer(target); 250 xChildren = null; 251 yChildren = null; 252 xTotal = null; 253 yTotal = null; 254 } 255 256 /** 257 * Not used by this class. 258 * 259 * @param name the name of the component 260 * @param comp the component 261 */ 262 public void addLayoutComponent(String name, Component comp) { 263 invalidateLayout(comp.getParent()); 264 } 265 266 /** 267 * Not used by this class. 268 * 269 * @param comp the component 270 */ 271 public void removeLayoutComponent(Component comp) { 272 invalidateLayout(comp.getParent()); 273 } 274 275 /** 276 * Not used by this class. 277 * 278 * @param comp the component 279 * @param constraints constraints 280 */ 281 public void addLayoutComponent(Component comp, Object constraints) { 282 invalidateLayout(comp.getParent()); 283 } 284 285 /** 286 * Returns the preferred dimensions for this layout, given the components 287 * in the specified target container. 288 * 289 * @param target the container that needs to be laid out 290 * @return the dimensions >= 0 && <= Integer.MAX_VALUE 291 * @exception AWTError if the target isn't the container specified to the 292 * BoxLayout constructor 293 * @see Container 294 * @see #minimumLayoutSize 295 * @see #maximumLayoutSize 296 */ 297 public Dimension preferredLayoutSize(Container target) { 298 Dimension size; 299 synchronized(this) { 300 checkContainer(target); 301 checkRequests(); 302 size = new Dimension(xTotal.preferred, yTotal.preferred); 303 } 304 305 Insets insets = target.getInsets(); 306 size.width = (int) Math.min((long) size.width + (long) insets.left + (long) insets.right, Integer.MAX_VALUE); 307 size.height = (int) Math.min((long) size.height + (long) insets.top + (long) insets.bottom, Integer.MAX_VALUE); 308 return size; 309 } 310 311 /** 312 * Returns the minimum dimensions needed to lay out the components 313 * contained in the specified target container. 314 * 315 * @param target the container that needs to be laid out 316 * @return the dimensions >= 0 && <= Integer.MAX_VALUE 317 * @exception AWTError if the target isn't the container specified to the 318 * BoxLayout constructor 319 * @see #preferredLayoutSize 320 * @see #maximumLayoutSize 321 */ 322 public Dimension minimumLayoutSize(Container target) { 323 Dimension size; 324 synchronized(this) { 325 checkContainer(target); 326 checkRequests(); 327 size = new Dimension(xTotal.minimum, yTotal.minimum); 328 } 329 330 Insets insets = target.getInsets(); 331 size.width = (int) Math.min((long) size.width + (long) insets.left + (long) insets.right, Integer.MAX_VALUE); 332 size.height = (int) Math.min((long) size.height + (long) insets.top + (long) insets.bottom, Integer.MAX_VALUE); 333 return size; 334 } 335 336 /** 337 * Returns the maximum dimensions the target container can use 338 * to lay out the components it contains. 339 * 340 * @param target the container that needs to be laid out 341 * @return the dimensions >= 0 && <= Integer.MAX_VALUE 342 * @exception AWTError if the target isn't the container specified to the 343 * BoxLayout constructor 344 * @see #preferredLayoutSize 345 * @see #minimumLayoutSize 346 */ 347 public Dimension maximumLayoutSize(Container target) { 348 Dimension size; 349 synchronized(this) { 350 checkContainer(target); 351 checkRequests(); 352 size = new Dimension(xTotal.maximum, yTotal.maximum); 353 } 354 355 Insets insets = target.getInsets(); 356 size.width = (int) Math.min((long) size.width + (long) insets.left + (long) insets.right, Integer.MAX_VALUE); 357 size.height = (int) Math.min((long) size.height + (long) insets.top + (long) insets.bottom, Integer.MAX_VALUE); 358 return size; 359 } 360 361 /** 362 * Returns the alignment along the X axis for the container. 363 * If the box is horizontal, the default 364 * alignment will be returned. Otherwise, the alignment needed 365 * to place the children along the X axis will be returned. 366 * 367 * @param target the container 368 * @return the alignment >= 0.0f && <= 1.0f 369 * @exception AWTError if the target isn't the container specified to the 370 * BoxLayout constructor 371 */ 372 public synchronized float getLayoutAlignmentX(Container target) { 373 checkContainer(target); 374 checkRequests(); 375 return xTotal.alignment; 376 } 377 378 /** 379 * Returns the alignment along the Y axis for the container. 380 * If the box is vertical, the default 381 * alignment will be returned. Otherwise, the alignment needed 382 * to place the children along the Y axis will be returned. 383 * 384 * @param target the container 385 * @return the alignment >= 0.0f && <= 1.0f 386 * @exception AWTError if the target isn't the container specified to the 387 * BoxLayout constructor 388 */ 389 public synchronized float getLayoutAlignmentY(Container target) { 390 checkContainer(target); 391 checkRequests(); 392 return yTotal.alignment; 393 } 394 395 /** 396 * Called by the AWT <!-- XXX CHECK! --> when the specified container 397 * needs to be laid out. 398 * 399 * @param target the container to lay out 400 * 401 * @exception AWTError if the target isn't the container specified to the 402 * BoxLayout constructor 403 */ 404 public void layoutContainer(Container target) { 405 checkContainer(target); 406 int nChildren = target.getComponentCount(); 407 int[] xOffsets = new int[nChildren]; 408 int[] xSpans = new int[nChildren]; 409 int[] yOffsets = new int[nChildren]; 410 int[] ySpans = new int[nChildren]; 411 412 Dimension alloc = target.getSize(); 413 Insets in = target.getInsets(); 414 alloc.width -= in.left + in.right; 415 alloc.height -= in.top + in.bottom; 416 417 // Resolve axis to an absolute value (either X_AXIS or Y_AXIS) 418 ComponentOrientation o = target.getComponentOrientation(); 419 int absoluteAxis = resolveAxis( axis, o ); 420 boolean ltr = (absoluteAxis != axis) ? o.isLeftToRight() : true; 421 422 423 // determine the child placements 424 synchronized(this) { 425 checkRequests(); 426 427 if (absoluteAxis == X_AXIS) { 428 SizeRequirements.calculateTiledPositions(alloc.width, xTotal, 429 xChildren, xOffsets, 430 xSpans, ltr); 431 SizeRequirements.calculateAlignedPositions(alloc.height, yTotal, 432 yChildren, yOffsets, 433 ySpans); 434 } else { 435 SizeRequirements.calculateAlignedPositions(alloc.width, xTotal, 436 xChildren, xOffsets, 437 xSpans, ltr); 438 SizeRequirements.calculateTiledPositions(alloc.height, yTotal, 439 yChildren, yOffsets, 440 ySpans); 441 } 442 } 443 444 // flush changes to the container 445 for (int i = 0; i < nChildren; i++) { 446 Component c = target.getComponent(i); 447 c.setBounds((int) Math.min((long) in.left + (long) xOffsets[i], Integer.MAX_VALUE), 448 (int) Math.min((long) in.top + (long) yOffsets[i], Integer.MAX_VALUE), 449 xSpans[i], ySpans[i]); 450 451 } 452 if (dbg != null) { 453 for (int i = 0; i < nChildren; i++) { 454 Component c = target.getComponent(i); 455 dbg.println(c.toString()); 456 dbg.println("X: " + xChildren[i]); 457 dbg.println("Y: " + yChildren[i]); 458 } 459 } 460 461 } 462 463 void checkContainer(Container target) { 464 if (this.target != target) { 465 throw new AWTError("BoxLayout can't be shared"); 466 } 467 } 468 469 void checkRequests() { 470 if (xChildren == null || yChildren == null) { 471 // The requests have been invalidated... recalculate 472 // the request information. 473 int n = target.getComponentCount(); 474 xChildren = new SizeRequirements[n]; 475 yChildren = new SizeRequirements[n]; 476 for (int i = 0; i < n; i++) { 477 Component c = target.getComponent(i); 478 if (!c.isVisible()) { 479 xChildren[i] = new SizeRequirements(0,0,0, c.getAlignmentX()); 480 yChildren[i] = new SizeRequirements(0,0,0, c.getAlignmentY()); 481 continue; 482 } 483 Dimension min = c.getMinimumSize(); 484 Dimension typ = c.getPreferredSize(); 485 Dimension max = c.getMaximumSize(); 486 xChildren[i] = new SizeRequirements(min.width, typ.width, 487 max.width, 488 c.getAlignmentX()); 489 yChildren[i] = new SizeRequirements(min.height, typ.height, 490 max.height, 491 c.getAlignmentY()); 492 } 493 494 // Resolve axis to an absolute value (either X_AXIS or Y_AXIS) 495 int absoluteAxis = resolveAxis(axis,target.getComponentOrientation()); 496 497 if (absoluteAxis == X_AXIS) { 498 xTotal = SizeRequirements.getTiledSizeRequirements(xChildren); 499 yTotal = SizeRequirements.getAlignedSizeRequirements(yChildren); 500 } else { 501 xTotal = SizeRequirements.getAlignedSizeRequirements(xChildren); 502 yTotal = SizeRequirements.getTiledSizeRequirements(yChildren); 503 } 504 } 505 } 506 507 /** 508 * Given one of the 4 axis values, resolve it to an absolute axis. 509 * The relative axis values, PAGE_AXIS and LINE_AXIS are converted 510 * to their absolute couterpart given the target's ComponentOrientation 511 * value. The absolute axes, X_AXIS and Y_AXIS are returned unmodified. 512 * 513 * @param axis the axis to resolve 514 * @param o the ComponentOrientation to resolve against 515 * @return the resolved axis 516 */ 517 private int resolveAxis( int axis, ComponentOrientation o ) { 518 int absoluteAxis; 519 if( axis == LINE_AXIS ) { 520 absoluteAxis = o.isHorizontal() ? X_AXIS : Y_AXIS; 521 } else if( axis == PAGE_AXIS ) { 522 absoluteAxis = o.isHorizontal() ? Y_AXIS : X_AXIS; 523 } else { 524 absoluteAxis = axis; 525 } 526 return absoluteAxis; 527 } 528 529 530 private int axis; 531 private Container target; 532 533 private transient SizeRequirements[] xChildren; 534 private transient SizeRequirements[] yChildren; 535 private transient SizeRequirements xTotal; 536 private transient SizeRequirements yTotal; 537 538 private transient PrintStream dbg; 539 }