1 /* BorderLayout.java -- A layout manager class 2 Copyright (C) 1999, 2002, 2005 Free Software Foundation, Inc. 3 4 This file is part of GNU Classpath. 5 6 GNU Classpath is free software; you can redistribute it and/or modify 7 it under the terms of the GNU General Public License as published by 8 the Free Software Foundation; either version 2, or (at your option) 9 any later version. 10 11 GNU Classpath is distributed in the hope that it will be useful, but 12 WITHOUT ANY WARRANTY; without even the implied warranty of 13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14 General Public License for more details. 15 16 You should have received a copy of the GNU General Public License 17 along with GNU Classpath; see the file COPYING. If not, write to the 18 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 19 02110-1301 USA. 20 21 Linking this library statically or dynamically with other modules is 22 making a combined work based on this library. Thus, the terms and 23 conditions of the GNU General Public License cover the whole 24 combination. 25 26 As a special exception, the copyright holders of this library give you 27 permission to link this library with independent modules to produce an 28 executable, regardless of the license terms of these independent 29 modules, and to copy and distribute the resulting executable under 30 terms of your choice, provided that you also meet, for each linked 31 independent module, the terms and conditions of the license of that 32 module. An independent module is a module which is not derived from 33 or based on this library. If you modify this library, you may extend 34 this exception to your version of the library, but you are not 35 obligated to do so. If you do not wish to do so, delete this 36 exception statement from your version. */ 37 38 39 package java.awt; 40 41 42 /** 43 * This class implements a layout manager that positions components 44 * in certain sectors of the parent container. 45 * 46 * @author Aaron M. Renn (arenn@urbanophile.com) 47 * @author Rolf W. Rasmussen (rolfwr@ii.uib.no) 48 */ 49 public class BorderLayout implements LayoutManager2, java.io.Serializable 50 { 51 52 /** 53 * Constant indicating the top of the container 54 */ 55 public static final String NORTH = "North"; 56 57 /** 58 * Constant indicating the bottom of the container 59 */ 60 public static final String SOUTH = "South"; 61 62 /** 63 * Constant indicating the right side of the container 64 */ 65 public static final String EAST = "East"; 66 67 /** 68 * Constant indicating the left side of the container 69 */ 70 public static final String WEST = "West"; 71 72 /** 73 * Constant indicating the center of the container 74 */ 75 public static final String CENTER = "Center"; 76 77 78 /** 79 * The constant indicating the position before the first line of the 80 * layout. The exact position depends on the writing system: For a 81 * top-to-bottom orientation, it is the same as {@link #NORTH}, for 82 * a bottom-to-top orientation, it is the same as {@link #SOUTH}. 83 * 84 * <p>This constant is an older name for {@link #PAGE_START} which 85 * has exactly the same value. 86 * 87 * @since 1.2 88 */ 89 public static final String BEFORE_FIRST_LINE = "First"; 90 91 /** 92 * The constant indicating the position after the last line of the 93 * layout. The exact position depends on the writing system: For a 94 * top-to-bottom orientation, it is the same as {@link #SOUTH}, for 95 * a bottom-to-top orientation, it is the same as {@link #NORTH}. 96 * 97 * <p>This constant is an older name for {@link #PAGE_END} which 98 * has exactly the same value. 99 * 100 * @since 1.2 101 */ 102 public static final String AFTER_LAST_LINE = "Last"; 103 104 /** 105 * The constant indicating the position before the first item of the 106 * layout. The exact position depends on the writing system: For a 107 * left-to-right orientation, it is the same as {@link #WEST}, for 108 * a right-to-left orientation, it is the same as {@link #EAST}. 109 * 110 * <p>This constant is an older name for {@link #LINE_START} which 111 * has exactly the same value. 112 * 113 * @since 1.2 114 */ 115 public static final String BEFORE_LINE_BEGINS = "Before"; 116 117 /** 118 * The constant indicating the position after the last item of the 119 * layout. The exact position depends on the writing system: For a 120 * left-to-right orientation, it is the same as {@link #EAST}, for 121 * a right-to-left orientation, it is the same as {@link #WEST}. 122 * 123 * <p>This constant is an older name for {@link #LINE_END} which 124 * has exactly the same value. 125 * 126 * @since 1.2 127 */ 128 public static final String AFTER_LINE_ENDS = "After"; 129 130 /** 131 * The constant indicating the position before the first line of the 132 * layout. The exact position depends on the writing system: For a 133 * top-to-bottom orientation, it is the same as {@link #NORTH}, for 134 * a bottom-to-top orientation, it is the same as {@link #SOUTH}. 135 * 136 * @since 1.4 137 */ 138 public static final String PAGE_START = BEFORE_FIRST_LINE; 139 140 /** 141 * The constant indicating the position after the last line of the 142 * layout. The exact position depends on the writing system: For a 143 * top-to-bottom orientation, it is the same as {@link #SOUTH}, for 144 * a bottom-to-top orientation, it is the same as {@link #NORTH}. 145 * 146 * @since 1.4 147 */ 148 public static final String PAGE_END = AFTER_LAST_LINE; 149 150 /** 151 * The constant indicating the position before the first item of the 152 * layout. The exact position depends on the writing system: For a 153 * left-to-right orientation, it is the same as {@link #WEST}, for 154 * a right-to-left orientation, it is the same as {@link #EAST}. 155 * 156 * @since 1.4 157 */ 158 public static final String LINE_START = BEFORE_LINE_BEGINS; 159 160 /** 161 * The constant indicating the position after the last item of the 162 * layout. The exact position depends on the writing system: For a 163 * left-to-right orientation, it is the same as {@link #EAST}, for 164 * a right-to-left orientation, it is the same as {@link #WEST}. 165 * 166 * @since 1.4 167 */ 168 public static final String LINE_END = AFTER_LINE_ENDS; 169 170 171 /** 172 * Serialization constant. 173 */ 174 private static final long serialVersionUID = -8658291919501921765L; 175 176 177 /** 178 * @serial 179 */ 180 private Component north; 181 182 /** 183 * @serial 184 */ 185 private Component south; 186 187 /** 188 * @serial 189 */ 190 private Component east; 191 192 /** 193 * @serial 194 */ 195 private Component west; 196 197 /** 198 * @serial 199 */ 200 private Component center; 201 202 /** 203 * @serial 204 */ 205 private Component firstLine; 206 207 /** 208 * @serial 209 */ 210 private Component lastLine; 211 212 /** 213 * @serial 214 */ 215 private Component firstItem; 216 217 /** 218 * @serial 219 */ 220 private Component lastItem; 221 222 /** 223 * @serial The horizontal gap between components 224 */ 225 private int hgap; 226 227 /** 228 * @serial The vertical gap between components 229 */ 230 private int vgap; 231 232 233 // Some constants for use with calcSize(). 234 private static final int MIN = 0; 235 private static final int MAX = 1; 236 private static final int PREF = 2; 237 238 239 /** 240 * Initializes a new instance of <code>BorderLayout</code> with no 241 * horiztonal or vertical gaps between components. 242 */ BorderLayout()243 public BorderLayout() 244 { 245 this(0,0); 246 } 247 248 /** 249 * Initializes a new instance of <code>BorderLayout</code> with the 250 * specified horiztonal and vertical gaps between components. 251 * 252 * @param hgap The horizontal gap between components. 253 * @param vgap The vertical gap between components. 254 */ BorderLayout(int hgap, int vgap)255 public BorderLayout(int hgap, int vgap) 256 { 257 this.hgap = hgap; 258 this.vgap = vgap; 259 } 260 261 /** 262 * Returns the horitzontal gap value. 263 * 264 * @return The horitzontal gap value. 265 */ getHgap()266 public int getHgap() 267 { 268 return(hgap); 269 } 270 271 /** 272 * Sets the horizontal gap to the specified value. 273 * 274 * @param hgap The new horizontal gap. 275 */ setHgap(int hgap)276 public void setHgap(int hgap) 277 { 278 this.hgap = hgap; 279 } 280 281 /** 282 * Returns the vertical gap value. 283 * 284 * @return The vertical gap value. 285 */ getVgap()286 public int getVgap() 287 { 288 return(vgap); 289 } 290 291 /** 292 * Sets the vertical gap to the specified value. 293 * 294 * @param vgap The new vertical gap value. 295 */ setVgap(int vgap)296 public void setVgap(int vgap) 297 { 298 this.vgap = vgap; 299 } 300 301 /** 302 * Adds a component to the layout in the specified constraint position, 303 * which must be one of the string constants defined in this class. 304 * 305 * @param component The component to add. 306 * @param constraints The constraint string. 307 * 308 * @exception IllegalArgumentException If the constraint object is not 309 * a string, or is not one of the specified constants in this class. 310 */ addLayoutComponent(Component component, Object constraints)311 public void addLayoutComponent(Component component, Object constraints) 312 { 313 if (constraints != null && ! (constraints instanceof String)) 314 throw new IllegalArgumentException("Constraint must be a string"); 315 316 addLayoutComponent((String) constraints, component); 317 } 318 319 /** 320 * Adds a component to the layout in the specified constraint position, 321 * which must be one of the string constants defined in this class. 322 * 323 * @param constraints The constraint string. 324 * @param component The component to add. 325 * 326 * @exception IllegalArgumentException If the constraint object is not 327 * one of the specified constants in this class. 328 * 329 * @deprecated This method is deprecated in favor of 330 * <code>addLayoutComponent(Component, Object)</code>. 331 */ addLayoutComponent(String constraints, Component component)332 public void addLayoutComponent(String constraints, Component component) 333 { 334 String str = constraints; 335 336 if (str == null || str.equals(CENTER)) 337 center = component; 338 else if (str.equals(NORTH)) 339 north = component; 340 else if (str.equals(SOUTH)) 341 south = component; 342 else if (str.equals(EAST)) 343 east = component; 344 else if (str.equals(WEST)) 345 west = component; 346 else if (str.equals(BEFORE_FIRST_LINE)) 347 firstLine = component; 348 else if (str.equals(AFTER_LAST_LINE)) 349 lastLine = component; 350 else if (str.equals(BEFORE_LINE_BEGINS)) 351 firstItem = component; 352 else if (str.equals(AFTER_LINE_ENDS)) 353 lastItem = component; 354 else 355 throw new IllegalArgumentException("Constraint value not valid: " + str); 356 } 357 358 /** 359 * Removes the specified component from the layout. 360 * 361 * @param component The component to remove from the layout. 362 */ removeLayoutComponent(Component component)363 public void removeLayoutComponent(Component component) 364 { 365 if (north == component) 366 north = null; 367 if (south == component) 368 south = null; 369 if (east == component) 370 east = null; 371 if (west == component) 372 west = null; 373 if (center == component) 374 center = null; 375 if (firstItem == component) 376 firstItem = null; 377 if (lastItem == component) 378 lastItem = null; 379 if (firstLine == component) 380 firstLine = null; 381 if (lastLine == component) 382 lastLine = null; 383 } 384 385 /** 386 * Returns the minimum size of the specified container using this layout. 387 * 388 * @param target The container to calculate the minimum size for. 389 * 390 * @return The minimum size of the container 391 */ minimumLayoutSize(Container target)392 public Dimension minimumLayoutSize(Container target) 393 { 394 return calcSize(target, MIN); 395 } 396 397 /** 398 * Returns the preferred size of the specified container using this layout. 399 * 400 * @param target The container to calculate the preferred size for. 401 * 402 * @return The preferred size of the container 403 */ preferredLayoutSize(Container target)404 public Dimension preferredLayoutSize(Container target) 405 { 406 return calcSize(target, PREF); 407 } 408 409 /** 410 * Returns the maximum size of the specified container using this layout. 411 * 412 * @param target The container to calculate the maximum size for. 413 * 414 * @return The maximum size of the container 415 */ maximumLayoutSize(Container target)416 public Dimension maximumLayoutSize(Container target) 417 { 418 return new Dimension (Integer.MAX_VALUE, Integer.MAX_VALUE); 419 } 420 421 /** 422 * Returns the X axis alignment, which is a <code>float</code> indicating 423 * where along the X axis this container wishs to position its layout. 424 * 0 indicates align to the left, 1 indicates align to the right, and 0.5 425 * indicates align to the center. 426 * 427 * @param parent The parent container. 428 * 429 * @return The X alignment value. 430 */ getLayoutAlignmentX(Container parent)431 public float getLayoutAlignmentX(Container parent) 432 { 433 return 0.5F; 434 } 435 436 /** 437 * Returns the Y axis alignment, which is a <code>float</code> indicating 438 * where along the Y axis this container wishs to position its layout. 439 * 0 indicates align to the top, 1 indicates align to the bottom, and 0.5 440 * indicates align to the center. 441 * 442 * @param parent The parent container. 443 * 444 * @return The Y alignment value. 445 */ getLayoutAlignmentY(Container parent)446 public float getLayoutAlignmentY(Container parent) 447 { 448 return 0.5F; 449 } 450 451 /** 452 * Instructs this object to discard any layout information it might 453 * have cached. 454 * 455 * @param parent The parent container. 456 */ invalidateLayout(Container parent)457 public void invalidateLayout(Container parent) 458 { 459 // Nothing to do here. 460 } 461 462 /** 463 * Lays out the specified container according to the constraints in this 464 * object. 465 * 466 * @param target The container to lay out. 467 */ layoutContainer(Container target)468 public void layoutContainer(Container target) 469 { 470 synchronized (target.getTreeLock()) 471 { 472 Insets i = target.getInsets(); 473 int top = i.top; 474 int bottom = target.height - i.bottom; 475 int left = i.left; 476 int right = target.width - i.right; 477 478 boolean left_to_right = target.getComponentOrientation().isLeftToRight(); 479 480 Component my_north = north; 481 Component my_east = east; 482 Component my_south = south; 483 Component my_west = west; 484 485 // Note that we currently don't handle vertical layouts. 486 // Neither does JDK 1.3. 487 if (firstLine != null) 488 my_north = firstLine; 489 if (lastLine != null) 490 my_south = lastLine; 491 if (firstItem != null) 492 { 493 if (left_to_right) 494 my_west = firstItem; 495 else 496 my_east = firstItem; 497 } 498 if (lastItem != null) 499 { 500 if (left_to_right) 501 my_east = lastItem; 502 else 503 my_west = lastItem; 504 } 505 506 if (my_north != null) 507 { 508 Dimension n = calcCompSize(my_north, PREF); 509 my_north.setBounds(left, top, right - left, n.height); 510 top += n.height + vgap; 511 } 512 513 if (my_south != null) 514 { 515 Dimension s = calcCompSize(my_south, PREF); 516 my_south.setBounds(left, bottom - s.height, right - left, s.height); 517 bottom -= s.height + vgap; 518 } 519 520 if (my_east != null) 521 { 522 Dimension e = calcCompSize(my_east, PREF); 523 my_east.setBounds(right - e.width, top, e.width, bottom - top); 524 right -= e.width + hgap; 525 } 526 527 if (my_west != null) 528 { 529 Dimension w = calcCompSize(my_west, PREF); 530 my_west.setBounds(left, top, w.width, bottom - top); 531 left += w.width + hgap; 532 } 533 534 if (center != null) 535 center.setBounds(left, top, right - left, bottom - top); 536 } 537 } 538 539 /** 540 * Returns a string representation of this layout manager. 541 * 542 * @return A string representation of this object. 543 */ toString()544 public String toString() 545 { 546 return getClass().getName() + "[hgap=" + hgap + ",vgap=" + vgap + "]"; 547 } 548 calcCompSize(Component comp, int what)549 private Dimension calcCompSize(Component comp, int what) 550 { 551 if (comp == null || ! comp.isVisible()) 552 return new Dimension(0, 0); 553 if (what == MIN) 554 return comp.getMinimumSize(); 555 else if (what == MAX) 556 return comp.getMaximumSize(); 557 return comp.getPreferredSize(); 558 } 559 560 /** 561 * This is a helper function used to compute the various sizes for this 562 * layout. 563 */ calcSize(Container target, int what)564 private Dimension calcSize(Container target, int what) 565 { 566 synchronized (target.getTreeLock()) 567 { 568 Insets ins = target.getInsets(); 569 570 ComponentOrientation orient = target.getComponentOrientation (); 571 boolean left_to_right = orient.isLeftToRight (); 572 573 Component my_north = north; 574 Component my_east = east; 575 Component my_south = south; 576 Component my_west = west; 577 578 // Note that we currently don't handle vertical layouts. Neither 579 // does JDK 1.3. 580 if (firstLine != null) 581 my_north = firstLine; 582 if (lastLine != null) 583 my_south = lastLine; 584 if (firstItem != null) 585 { 586 if (left_to_right) 587 my_west = firstItem; 588 else 589 my_east = firstItem; 590 } 591 if (lastItem != null) 592 { 593 if (left_to_right) 594 my_east = lastItem; 595 else 596 my_west = lastItem; 597 } 598 599 Dimension ndim = calcCompSize(my_north, what); 600 Dimension sdim = calcCompSize(my_south, what); 601 Dimension edim = calcCompSize(my_east, what); 602 Dimension wdim = calcCompSize(my_west, what); 603 Dimension cdim = calcCompSize(center, what); 604 605 int width = edim.width + cdim.width + wdim.width + (hgap * 2); 606 // Check for overflow. 607 if (width < edim.width || width < cdim.width || width < cdim.width) 608 width = Integer.MAX_VALUE; 609 610 if (ndim.width > width) 611 width = ndim.width; 612 if (sdim.width > width) 613 width = sdim.width; 614 615 width += (ins.left + ins.right); 616 617 int height = edim.height; 618 if (cdim.height > height) 619 height = cdim.height; 620 if (wdim.height > height) 621 height = wdim.height; 622 623 int addedHeight = height + (ndim.height + sdim.height + (vgap * 2) 624 + ins.top + ins.bottom); 625 // Check for overflow. 626 if (addedHeight < height) 627 height = Integer.MAX_VALUE; 628 else 629 height = addedHeight; 630 631 return(new Dimension(width, height)); 632 } 633 } 634 635 /** 636 * Return the component at the indicated location, or null if no component 637 * is at that location. The constraints argument must be one of the 638 * location constants specified by this class. 639 * @param constraints the location 640 * @return the component at that location, or null 641 * @throws IllegalArgumentException if the constraints argument is not 642 * recognized 643 * @since 1.5 644 */ getLayoutComponent(Object constraints)645 public Component getLayoutComponent(Object constraints) 646 { 647 if (constraints == CENTER) 648 return center; 649 if (constraints == NORTH) 650 return north; 651 if (constraints == EAST) 652 return east; 653 if (constraints == SOUTH) 654 return south; 655 if (constraints == WEST) 656 return west; 657 if (constraints == PAGE_START) 658 return firstLine; 659 if (constraints == PAGE_END) 660 return lastLine; 661 if (constraints == LINE_START) 662 return firstItem; 663 if (constraints == LINE_END) 664 return lastItem; 665 throw new IllegalArgumentException("constraint " + constraints 666 + " is not recognized"); 667 } 668 669 /** 670 * Return the component at the specified location, which must be one 671 * of the absolute constants such as CENTER or SOUTH. The container's 672 * orientation is used to map this location to the correct corresponding 673 * component, so for instance in a right-to-left container, a request 674 * for the EAST component could return the LINE_END component. This will 675 * return null if no component is available at the given location. 676 * @param container the container whose orientation is used 677 * @param constraints the absolute location of the component 678 * @return the component at the location, or null 679 * @throws IllegalArgumentException if the constraint is not recognized 680 */ getLayoutComponent(Container container, Object constraints)681 public Component getLayoutComponent(Container container, Object constraints) 682 { 683 ComponentOrientation orient = container.getComponentOrientation(); 684 if (constraints == CENTER) 685 return center; 686 // Note that we don't support vertical layouts. 687 if (constraints == NORTH) 688 return north; 689 if (constraints == SOUTH) 690 return south; 691 if (constraints == WEST) 692 { 693 // Note that relative layout takes precedence. 694 if (orient.isLeftToRight()) 695 return firstItem == null ? west : firstItem; 696 return lastItem == null ? west : lastItem; 697 } 698 if (constraints == EAST) 699 { 700 // Note that relative layout takes precedence. 701 if (orient.isLeftToRight()) 702 return lastItem == null ? east : lastItem; 703 return firstItem == null ? east : firstItem; 704 } 705 throw new IllegalArgumentException("constraint " + constraints 706 + " is not recognized"); 707 } 708 709 /** 710 * Return the constraint corresponding to a component in this layout. 711 * If the component is null, or is not in this layout, returns null. 712 * Otherwise, this will return one of the constraint constants defined 713 * in this class. 714 * @param c the component 715 * @return the constraint, or null 716 * @since 1.5 717 */ getConstraints(Component c)718 public Object getConstraints(Component c) 719 { 720 if (c == null) 721 return null; 722 if (c == center) 723 return CENTER; 724 if (c == north) 725 return NORTH; 726 if (c == east) 727 return EAST; 728 if (c == south) 729 return SOUTH; 730 if (c == west) 731 return WEST; 732 if (c == firstLine) 733 return PAGE_START; 734 if (c == lastLine) 735 return PAGE_END; 736 if (c == firstItem) 737 return LINE_START; 738 if (c == lastItem) 739 return LINE_END; 740 return null; 741 } 742 } 743