BorderLayout.java revision 0
2362N/A * Copyright 1995-2006 Sun Microsystems, Inc. All Rights Reserved. 0N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/A * This code is free software; you can redistribute it and/or modify it 0N/A * under the terms of the GNU General Public License version 2 only, as 2362N/A * published by the Free Software Foundation. Sun designates this 0N/A * particular file as subject to the "Classpath" exception as provided 2362N/A * by Sun in the LICENSE file that accompanied this code. 0N/A * This code is distributed in the hope that it will be useful, but WITHOUT 0N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/A * version 2 for more details (a copy is included in the LICENSE file that 0N/A * accompanied this code). 0N/A * You should have received a copy of the GNU General Public License version 0N/A * 2 along with this work; if not, write to the Free Software Foundation, 0N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 2362N/A * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, 2362N/A * CA 95054 USA or visit www.sun.com if you need additional information or 0N/A * A border layout lays out a container, arranging and resizing 0N/A * its components to fit in five regions: 0N/A * north, south, east, west, and center. 0N/A * Each region may contain no more than one component, and 0N/A * is identified by a corresponding constant: 0N/A * <code>NORTH</code>, <code>SOUTH</code>, <code>EAST</code>, 0N/A * <code>WEST</code>, and <code>CENTER</code>. When adding a 0N/A * component to a container with a border layout, use one of these 0N/A * five constants, for example: 0N/A * Panel p = new Panel(); 0N/A * p.setLayout(new BorderLayout()); 0N/A * p.add(new Button("Okay"), BorderLayout.SOUTH); 0N/A * As a convenience, <code>BorderLayout</code> interprets the 0N/A * absence of a string specification the same as the constant 0N/A * <code>CENTER</code>: 0N/A * Panel p2 = new Panel(); 0N/A * p2.setLayout(new BorderLayout()); 0N/A * p2.add(new TextArea()); // Same as p.add(new TextArea(), BorderLayout.CENTER); 0N/A * In addition, <code>BorderLayout</code> supports the relative 0N/A * positioning constants, <code>PAGE_START</code>, <code>PAGE_END</code>, 0N/A * <code>LINE_START</code>, and <code>LINE_END</code>. 0N/A * In a container whose <code>ComponentOrientation</code> is set to 0N/A * <code>ComponentOrientation.LEFT_TO_RIGHT</code>, these constants map to 0N/A * <code>NORTH</code>, <code>SOUTH</code>, <code>WEST</code>, and 0N/A * <code>EAST</code>, respectively. 0N/A * For compatibility with previous releases, <code>BorderLayout</code> 0N/A * also includes the relative positioning constants <code>BEFORE_FIRST_LINE</code>, 0N/A * <code>AFTER_LAST_LINE</code>, <code>BEFORE_LINE_BEGINS</code> and 0N/A * <code>AFTER_LINE_ENDS</code>. These are equivalent to 0N/A * <code>PAGE_START</code>, <code>PAGE_END</code>, <code>LINE_START</code> 0N/A * and <code>LINE_END</code> respectively. For 0N/A * consistency with the relative positioning constants used by other 0N/A * components, the latter constants are preferred. 0N/A * Mixing both absolute and relative positioning constants can lead to 0N/A * unpredicable results. If 0N/A * you use both types, the relative constants will take precedence. 0N/A * For example, if you add components using both the <code>NORTH</code> 0N/A * and <code>PAGE_START</code> constants in a container whose 0N/A * orientation is <code>LEFT_TO_RIGHT</code>, only the 0N/A * <code>PAGE_START</code> will be layed out. 0N/A * NOTE: Currently (in the Java 2 platform v1.2), 0N/A * <code>BorderLayout</code> does not support vertical 0N/A * orientations. The <code>isVertical</code> setting on the container's 0N/A * <code>ComponentOrientation</code> is not respected. 0N/A * The components are laid out according to their 0N/A * preferred sizes and the constraints of the container's size. 0N/A * The <code>NORTH</code> and <code>SOUTH</code> components may 0N/A * be stretched horizontally; the <code>EAST</code> and 0N/A * <code>WEST</code> components may be stretched vertically; 0N/A * the <code>CENTER</code> component may stretch both horizontally 0N/A * and vertically to fill any space left over. 0N/A * Here is an example of five buttons in an applet laid out using 0N/A * the <code>BorderLayout</code> layout manager: 0N/A * alt="Diagram of an applet demonstrating BorderLayout. 0N/A * Each section of the BorderLayout contains a Button corresponding to its position in the layout, one of: 0N/A * North, West, Center, East, or South." 0N/A * ALIGN=center HSPACE=10 VSPACE=7> 0N/A * The code for this applet is as follows: 0N/A * <hr><blockquote><pre> 0N/A * import java.awt.*; 0N/A * import java.applet.Applet; 0N/A * public class buttonDir extends Applet { 0N/A * public void init() { 0N/A * setLayout(new BorderLayout()); 0N/A * add(new Button("North"), BorderLayout.NORTH); 0N/A * add(new Button("South"), BorderLayout.SOUTH); 0N/A * add(new Button("East"), BorderLayout.EAST); 0N/A * add(new Button("West"), BorderLayout.WEST); 0N/A * add(new Button("Center"), BorderLayout.CENTER); 0N/A * </pre></blockquote><hr> 0N/A * @author Arthur van Hoff 0N/A * @see java.awt.Container#add(String, Component) 0N/A * @see java.awt.ComponentOrientation 0N/A * Constructs a border layout with the horizontal gaps 0N/A * between components. 0N/A * The horizontal gap is specified by <code>hgap</code>. 0N/A * @see #setHgap(int) 0N/A * Constructs a border layout with the vertical gaps 0N/A * between components. 0N/A * The vertical gap is specified by <code>vgap</code>. 0N/A * @see #setVgap(int) 0N/A * Constant to specify components location to be the 0N/A * north portion of the border layout. 0N/A * @see #getChild(String, boolean) 0N/A * @see #addLayoutComponent 0N/A * @see #getLayoutAlignmentX 0N/A * @see #getLayoutAlignmentY 0N/A * @see #removeLayoutComponent 0N/A * Constant to specify components location to be the 0N/A * west portion of the border layout. 0N/A * @see #getChild(String, boolean) 0N/A * @see #addLayoutComponent 0N/A * @see #getLayoutAlignmentX 0N/A * @see #getLayoutAlignmentY 0N/A * @see #removeLayoutComponent 0N/A * Constant to specify components location to be the 0N/A * east portion of the border layout. 0N/A * @see #getChild(String, boolean) 0N/A * @see #addLayoutComponent 0N/A * @see #getLayoutAlignmentX 0N/A * @see #getLayoutAlignmentY 0N/A * @see #removeLayoutComponent * Constant to specify components location to be the * south portion of the border layout. * @see #getChild(String, boolean) * @see #addLayoutComponent * @see #getLayoutAlignmentX * @see #getLayoutAlignmentY * @see #removeLayoutComponent * Constant to specify components location to be the * center portion of the border layout. * @see #getChild(String, boolean) * @see #addLayoutComponent * @see #getLayoutAlignmentX * @see #getLayoutAlignmentY * @see #removeLayoutComponent * A relative positioning constant, that can be used instead of * north, south, east, west or center. * mixing the two types of constants can lead to unpredicable results. If * you use both types, the relative constants will take precedence. * For example, if you add components using both the <code>NORTH</code> * and <code>BEFORE_FIRST_LINE</code> constants in a container whose * orientation is <code>LEFT_TO_RIGHT</code>, only the * <code>BEFORE_FIRST_LINE</code> will be layed out. * This will be the same for lastLine, firstItem, lastItem. * A relative positioning constant, that can be used instead of * north, south, east, west or center. * Please read Description for firstLine. * A relative positioning constant, that can be used instead of * north, south, east, west or center. * Please read Description for firstLine. * A relative positioning constant, that can be used instead of * north, south, east, west or center. * Please read Description for firstLine. * The north layout constraint (top of container). * The south layout constraint (bottom of container). * The east layout constraint (right side of container). * The west layout constraint (left side of container). * The center layout constraint (middle of container). * Synonym for PAGE_START. Exists for compatibility with previous * versions. PAGE_START is preferred. * Synonym for PAGE_END. Exists for compatibility with previous * versions. PAGE_END is preferred. * Synonym for LINE_START. Exists for compatibility with previous * versions. LINE_START is preferred. * Synonym for LINE_END. Exists for compatibility with previous * versions. LINE_END is preferred. * The component comes before the first line of the layout's content. * For Western, left-to-right and top-to-bottom orientations, this is * @see java.awt.Component#getComponentOrientation * The component comes after the last line of the layout's content. * For Western, left-to-right and top-to-bottom orientations, this is * @see java.awt.Component#getComponentOrientation * The component goes at the beginning of the line direction for the * layout. For Western, left-to-right and top-to-bottom orientations, * this is equivalent to WEST. * @see java.awt.Component#getComponentOrientation * The component goes at the end of the line direction for the * layout. For Western, left-to-right and top-to-bottom orientations, * this is equivalent to EAST. * @see java.awt.Component#getComponentOrientation * JDK 1.1 serialVersionUID * Constructs a new border layout with * no gaps between components. * Constructs a border layout with the specified gaps * The horizontal gap is specified by <code>hgap</code> * and the vertical gap is specified by <code>vgap</code>. * @param hgap the horizontal gap. * @param vgap the vertical gap. * Returns the horizontal gap between components. * Sets the horizontal gap between components. * @param hgap the horizontal gap between components * Returns the vertical gap between components. * Sets the vertical gap between components. * @param vgap the vertical gap between components * Adds the specified component to the layout, using the specified * constraint object. For border layouts, the constraint must be * one of the following constants: <code>NORTH</code>, * <code>SOUTH</code>, <code>EAST</code>, * <code>WEST</code>, or <code>CENTER</code>. * Most applications do not call this method directly. This method * is called when a component is added to a container using the * <code>Container.add</code> method with the same argument types. * @param comp the component to be added. * @param constraints an object that specifies how and where * the component is added to the layout. * @see java.awt.Container#add(java.awt.Component, java.lang.Object) * @exception IllegalArgumentException if the constraint object is not * a string, or if it not one of the five specified * @deprecated replaced by <code>addLayoutComponent(Component, Object)</code>. /* Special case: treat null the same as "Center". */ /* Assign the component to one of the known regions of the layout. * Removes the specified component from this border layout. This * method is called when a container calls its <code>remove</code> or * <code>removeAll</code> methods. Most applications do not call this * @param comp the component to be removed. * @see java.awt.Container#remove(java.awt.Component) * @see java.awt.Container#removeAll() * Gets the component that was added using the given constraint * @param constraints the desired constraint, one of <code>CENTER</code>, * <code>NORTH</code>, <code>SOUTH</code>, * <code>WEST</code>, <code>EAST</code>, * <code>PAGE_START</code>, <code>PAGE_END</code>, * <code>LINE_START</code>, <code>LINE_END</code> * @return the component at the given location, or <code>null</code> if * @exception IllegalArgumentException if the constraint object is * not one of the nine specified constants * @see #addLayoutComponent(java.awt.Component, java.lang.Object) * Returns the component that corresponds to the given constraint location * based on the target <code>Container</code>'s component orientation. * Components added with the relative constraints <code>PAGE_START</code>, * <code>PAGE_END</code>, <code>LINE_START</code>, and <code>LINE_END</code> * take precedence over components added with the explicit constraints * <code>NORTH</code>, <code>SOUTH</code>, <code>WEST</code>, and <code>EAST</code>. * The <code>Container</code>'s component orientation is used to determine the location of components * added with <code>LINE_START</code> and <code>LINE_END</code>. * @param constraints the desired absolute position, one of <code>CENTER</code>, * <code>NORTH</code>, <code>SOUTH</code>, * <code>EAST</code>, <code>WEST</code> * @param target the {@code Container} used to obtain * the constraint location based on the target * {@code Container}'s component orientation. * @return the component at the given location, or <code>null</code> if * @exception IllegalArgumentException if the constraint object is * not one of the five specified constants * @exception NullPointerException if the target parameter is null * @see #addLayoutComponent(java.awt.Component, java.lang.Object) * Gets the constraints for the specified component * @param comp the component to be queried * @return the constraint for the specified component, * or null if component is null or is not present * @see #addLayoutComponent(java.awt.Component, java.lang.Object) //fix for 6242148 : API method java.awt.BorderLayout.getConstraints(null) should return null * Determines the minimum size of the <code>target</code> container * using this layout manager. * This method is called when a container calls its * <code>getMinimumSize</code> method. Most applications do not call * @param target the container in which to do the layout. * @return the minimum dimensions needed to lay out the subcomponents * of the specified container. * @see java.awt.Container * @see java.awt.BorderLayout#preferredLayoutSize * @see java.awt.Container#getMinimumSize() * Determines the preferred size of the <code>target</code> * container using this layout manager, based on the components * Most applications do not call this method directly. This method * is called when a container calls its <code>getPreferredSize</code> * @param target the container in which to do the layout. * @return the preferred dimensions to lay out the subcomponents * of the specified container. * @see java.awt.Container * @see java.awt.BorderLayout#minimumLayoutSize * @see java.awt.Container#getPreferredSize() * Returns the maximum dimensions for this layout given the components * in the specified target container. * @param target the component which needs to be laid out * @see #minimumLayoutSize * @see #preferredLayoutSize * Returns the alignment along the x axis. This specifies how * the component would like to be aligned relative to other * components. The value should be a number between 0 and 1 * where 0 represents alignment along the origin, 1 is aligned * the furthest away from the origin, 0.5 is centered, etc. * Returns the alignment along the y axis. This specifies how * the component would like to be aligned relative to other * components. The value should be a number between 0 and 1 * where 0 represents alignment along the origin, 1 is aligned * the furthest away from the origin, 0.5 is centered, etc. * Invalidates the layout, indicating that if the layout manager * has cached information it should be discarded. * Lays out the container argument using this border layout. * This method actually reshapes the components in the specified * container in order to satisfy the constraints of this * <code>BorderLayout</code> object. The <code>NORTH</code> * and <code>SOUTH</code> components, if any, are placed at * the top and bottom of the container, respectively. The * <code>WEST</code> and <code>EAST</code> components are * then placed on the left and right, respectively. Finally, * the <code>CENTER</code> object is placed in any remaining * Most applications do not call this method directly. This method * is called when a container calls its <code>doLayout</code> method. * @param target the container in which to do the layout. * @see java.awt.Container * @see java.awt.Container#doLayout() * Get the component that corresponds to the given constraint location * @param key The desired absolute position, * either NORTH, SOUTH, EAST, or WEST. * @param ltr Is the component line direction left-to-right? * Returns a string representation of the state of this border layout. * @return a string representation of this border layout.