/*

 * Copyright (c) 1995, 2006, Oracle and/or its affiliates. All rights reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.com if you need additional information or have any

 * questions.

 */

package java.awt;

import java.util.Hashtable;

import java.util.Arrays;

/**

 * The <code>GridBagLayout</code> class is a flexible layout

 * manager that aligns components vertically, horizontally or along their

 * baseline without requiring that the components be of the same size.

 * Each <code>GridBagLayout</code> object maintains a dynamic,

 * rectangular grid of cells, with each component occupying

 * one or more cells, called its <em>display area</em>.

 * <p>

 * Each component managed by a <code>GridBagLayout</code> is associated with

 * an instance of {@link GridBagConstraints}.  The constraints object

 * specifies where a component's display area should be located on the grid

 * and how the component should be positioned within its display area.  In

 * addition to its constraints object, the <code>GridBagLayout</code> also

 * considers each component's minimum and preferred sizes in order to

 * determine a component's size.

 * <p>

 * The overall orientation of the grid depends on the container's

 * {@link ComponentOrientation} property.  For horizontal left-to-right

 * orientations, grid coordinate (0,0) is in the upper left corner of the

 * container with x increasing to the right and y increasing downward.  For

 * horizontal right-to-left orientations, grid coordinate (0,0) is in the upper

 * right corner of the container with x increasing to the left and y

 * increasing downward.

 * <p>

 * To use a grid bag layout effectively, you must customize one or more

 * of the <code>GridBagConstraints</code> objects that are associated

 * with its components. You customize a <code>GridBagConstraints</code>

 * object by setting one or more of its instance variables:

 * <p>

 * <dl>

 * <dt>{@link GridBagConstraints#gridx},

 * {@link GridBagConstraints#gridy}

 * <dd>Specifies the cell containing the leading corner of the component's

 * display area, where the cell at the origin of the grid has address

 * <code>gridx&nbsp;=&nbsp;0</code>,

 * <code>gridy&nbsp;=&nbsp;0</code>.  For horizontal left-to-right layout,

 * a component's leading corner is its upper left.  For horizontal

 * right-to-left layout, a component's leading corner is its upper right.

 * Use <code>GridBagConstraints.RELATIVE</code> (the default value)

 * to specify that the component be placed immediately following

 * (along the x axis for <code>gridx</code> or the y axis for

 * <code>gridy</code>) the component that was added to the container

 * just before this component was added.

 * <dt>{@link GridBagConstraints#gridwidth},

 * {@link GridBagConstraints#gridheight}

 * <dd>Specifies the number of cells in a row (for <code>gridwidth</code>)

 * or column (for <code>gridheight</code>)

 * in the component's display area.

 * The default value is 1.

 * Use <code>GridBagConstraints.REMAINDER</code> to specify

 * that the component's display area will be from <code>gridx</code>

 * to the last cell in the row (for <code>gridwidth</code>)

 * or from <code>gridy</code> to the last cell in the column

 * (for <code>gridheight</code>).

 *

 * Use <code>GridBagConstraints.RELATIVE</code> to specify

 * that the component's display area will be from <code>gridx</code>

 * to the next to the last cell in its row (for <code>gridwidth</code>

 * or from <code>gridy</code> to the next to the last cell in its

 * column (for <code>gridheight</code>).

 *

 * <dt>{@link GridBagConstraints#fill}

 * <dd>Used when the component's display area

 * is larger than the component's requested size

 * to determine whether (and how) to resize the component.

 * Possible values are

 * <code>GridBagConstraints.NONE</code> (the default),

 * <code>GridBagConstraints.HORIZONTAL</code>

 * (make the component wide enough to fill its display area

 * horizontally, but don't change its height),

 * <code>GridBagConstraints.VERTICAL</code>

 * (make the component tall enough to fill its display area

 * vertically, but don't change its width), and

 * <code>GridBagConstraints.BOTH</code>

 * (make the component fill its display area entirely).

 * <dt>{@link GridBagConstraints#ipadx},

 * {@link GridBagConstraints#ipady}

 * <dd>Specifies the component's internal padding within the layout,

 * how much to add to the minimum size of the component.

 * The width of the component will be at least its minimum width

 * plus <code>ipadx</code> pixels. Similarly, the height of

 * the component will be at least the minimum height plus

 * <code>ipady</code> pixels.

 * <dt>{@link GridBagConstraints#insets}

 * <dd>Specifies the component's external padding, the minimum

 * amount of space between the component and the edges of its display area.

 * <dt>{@link GridBagConstraints#anchor}

 * <dd>Specifies where the component should be positioned in its display area.

 * There are three kinds of possible values: absolute, orientation-relative,

 * and baseline-relative

 * Orientation relative values are interpreted relative to the container's

 * <code>ComponentOrientation</code> property while absolute values

 * are not.  Baseline relative values are calculated relative to the

 * baseline.  Valid values are:

 * <p>

 * <center><table BORDER=0 WIDTH=800

 *        SUMMARY="absolute, relative and baseline values as described above">

 * <tr>

 * <th><P style="text-align:left">Absolute Values</th>

 * <th><P style="text-align:left">Orientation Relative Values</th>

 * <th><P style="text-align:left">Baseline Relative Values</th>

 * </tr>

 * <tr>

 * <td>

 * <ul style="list-style-type:none">

 * <li><code>GridBagConstraints.NORTH</code></li>

 * <li><code>GridBagConstraints.SOUTH</code></li>

 * <li><code>GridBagConstraints.WEST</code></li>

 * <li><code>GridBagConstraints.EAST</code></li>

 * <li><code>GridBagConstraints.NORTHWEST</code></li>

 * <li><code>GridBagConstraints.NORTHEAST</code></li>

 * <li><code>GridBagConstraints.SOUTHWEST</code></li>

 * <li><code>GridBagConstraints.SOUTHEAST</code></li>

 * <li><code>GridBagConstraints.CENTER</code> (the default)</li>

 * </ul>

 * </td>

 * <td>

 * <ul style="list-style-type:none">

 * <li><code>GridBagConstraints.PAGE_START</code></li>

 * <li><code>GridBagConstraints.PAGE_END</code></li>

 * <li><code>GridBagConstraints.LINE_START</code></li>

 * <li><code>GridBagConstraints.LINE_END</code></li>

 * <li><code>GridBagConstraints.FIRST_LINE_START</code></li>

 * <li><code>GridBagConstraints.FIRST_LINE_END</code></li>

 * <li><code>GridBagConstraints.LAST_LINE_START</code></li>

 * <li><code>GridBagConstraints.LAST_LINE_END</code></li>

 * </ul>

 * </td>

 * <td>

 * <ul style="list-style-type:none">

 * <li><code>GridBagConstraints.BASELINE</code></li>

 * <li><code>GridBagConstraints.BASELINE_LEADING</code></li>

 * <li><code>GridBagConstraints.BASELINE_TRAILING</code></li>

 * <li><code>GridBagConstraints.ABOVE_BASELINE</code></li>

 * <li><code>GridBagConstraints.ABOVE_BASELINE_LEADING</code></li>

 * <li><code>GridBagConstraints.ABOVE_BASELINE_TRAILING</code></li>

 * <li><code>GridBagConstraints.BELOW_BASELINE</code></li>

 * <li><code>GridBagConstraints.BELOW_BASELINE_LEADING</code></li>

 * <li><code>GridBagConstraints.BELOW_BASELINE_TRAILING</code></li>

 * </ul>

 * </td>

 * </tr>

 * </table></center>

 * <dt>{@link GridBagConstraints#weightx},

 * {@link GridBagConstraints#weighty}

 * <dd>Used to determine how to distribute space, which is

 * important for specifying resizing behavior.

 * Unless you specify a weight for at least one component

 * in a row (<code>weightx</code>) and column (<code>weighty</code>),

 * all the components clump together in the center of their container.

 * This is because when the weight is zero (the default),

 * the <code>GridBagLayout</code> object puts any extra space

 * between its grid of cells and the edges of the container.

 * </dl>

 * <p>

 * Each row may have a baseline; the baseline is determined by the

 * components in that row that have a valid baseline and are aligned

 * along the baseline (the component's anchor value is one of {@code

 * BASELINE}, {@code BASELINE_LEADING} or {@code BASELINE_TRAILING}).

 * If none of the components in the row has a valid baseline, the row

 * does not have a baseline.

 * <p>

 * If a component spans rows it is aligned either to the baseline of

 * the start row (if the baseline-resize behavior is {@code

 * CONSTANT_ASCENT}) or the end row (if the baseline-resize behavior

 * is {@code CONSTANT_DESCENT}).  The row that the component is

 * aligned to is called the <em>prevailing row</em>.

 * <p>

 * The following figure shows a baseline layout and includes a

 * component that spans rows:

 * <center><table summary="Baseline Layout">

 * <tr ALIGN=CENTER>

 * <td>

 * <img src="doc-files/GridBagLayout-baseline.png"

 *  alt="The following text describes this graphic (Figure 1)." style="float:center">

 * </td>

 * </table></center>

 * This layout consists of three components:

 * <ul><li>A panel that starts in row 0 and ends in row 1.  The panel

 *   has a baseline-resize behavior of <code>CONSTANT_DESCENT</code> and has

 *   an anchor of <code>BASELINE</code>.  As the baseline-resize behavior

 *   is <code>CONSTANT_DESCENT</code> the prevailing row for the panel is

 *   row 1.

 * <li>Two buttons, each with a baseline-resize behavior of

 *   <code>CENTER_OFFSET</code> and an anchor of <code>BASELINE</code>.

 * </ul>

 * Because the second button and the panel share the same prevailing row,

 * they are both aligned along their baseline.

 * <p>

 * Components positioned using one of the baseline-relative values resize

 * differently than when positioned using an absolute or orientation-relative

 * value.  How components change is dictated by how the baseline of the

 * prevailing row changes.  The baseline is anchored to the

 * bottom of the display area if any components with the same prevailing row

 * have a baseline-resize behavior of <code>CONSTANT_DESCENT</code>,

 * otherwise the baseline is anchored to the top of the display area.

 * The following rules dictate the resize behavior:

 * <ul>

 * <li>Resizable components positioned above the baseline can only

 * grow as tall as the baseline.  For example, if the baseline is at 100

 * and anchored at the top, a resizable component positioned above the

 * baseline can never grow more than 100 units.

 * <li>Similarly, resizable components positioned below the baseline can

 * only grow as high as the difference between the display height and the

 * baseline.

 * <li>Resizable components positioned on the baseline with a

 * baseline-resize behavior of <code>OTHER</code> are only resized if

 * the baseline at the resized size fits within the display area.  If

 * the baseline is such that it does not fit within the display area

 * the component is not resized.

 * <li>Components positioned on the baseline that do not have a

 * baseline-resize behavior of <code>OTHER</code>

 * can only grow as tall as {@code display height - baseline + baseline of component}.

 * </ul>

 * If you position a component along the baseline, but the

 * component does not have a valid baseline, it will be vertically centered

 * in its space.  Similarly if you have positioned a component relative

 * to the baseline and none of the components in the row have a valid

 * baseline the component is vertically centered.

 * <p>

 * The following figures show ten components (all buttons)

 * managed by a grid bag layout.  Figure 2 shows the layout for a horizontal,

 * left-to-right container and Figure 3 shows the layout for a horizontal,

 * right-to-left container.

 * <p>

 * <center><table WIDTH=600 summary="layout">

 * <tr ALIGN=CENTER>

 * <td>

 * </td>

 * <td>

 * </td>

 * <tr ALIGN=CENTER>

 * <td>Figure 2: Horizontal, Left-to-Right</td>

 * <td>Figure 3: Horizontal, Right-to-Left</td>

 * </tr>

 * </table></center>

 * <p>

 * Each of the ten components has the <code>fill</code> field

 * of its associated <code>GridBagConstraints</code> object

 * set to <code>GridBagConstraints.BOTH</code>.

 * In addition, the components have the following non-default constraints:

 * <p>

 * <ul>

 * <li>Button1, Button2, Button3: <code>weightx&nbsp;=&nbsp;1.0</code>

 * <li>Button4: <code>weightx&nbsp;=&nbsp;1.0</code>,

 * <code>gridwidth&nbsp;=&nbsp;GridBagConstraints.REMAINDER</code>

 * <li>Button5: <code>gridwidth&nbsp;=&nbsp;GridBagConstraints.REMAINDER</code>

 * <li>Button6: <code>gridwidth&nbsp;=&nbsp;GridBagConstraints.RELATIVE</code>

 * <li>Button7: <code>gridwidth&nbsp;=&nbsp;GridBagConstraints.REMAINDER</code>

 * <li>Button8: <code>gridheight&nbsp;=&nbsp;2</code>,

 * <code>weighty&nbsp;=&nbsp;1.0</code>

 * <li>Button9, Button 10:

 * <code>gridwidth&nbsp;=&nbsp;GridBagConstraints.REMAINDER</code>

 * </ul>

 * <p>

 * Here is the code that implements the example shown above:

 * <p>

 * <hr><blockquote><pre>

 * import java.awt.*;

 * import java.util.*;

 * import java.applet.Applet;

 *

 * public class GridBagEx1 extends Applet {

 *

 *     protected void makebutton(String name,

 *                               GridBagLayout gridbag,

 *                               GridBagConstraints c) {

 *         Button button = new Button(name);

 *         gridbag.setConstraints(button, c);

 *         add(button);

 *     }

 *

 *     public void init() {

 *         GridBagLayout gridbag = new GridBagLayout();

 *         GridBagConstraints c = new GridBagConstraints();

 *

 *         setFont(new Font("SansSerif", Font.PLAIN, 14));

 *         setLayout(gridbag);

 *

 *         c.fill = GridBagConstraints.BOTH;

 *         c.weightx = 1.0;

 *         makebutton("Button1", gridbag, c);

 *         makebutton("Button2", gridbag, c);

 *         makebutton("Button3", gridbag, c);

 *

 *         c.gridwidth = GridBagConstraints.REMAINDER; //end row

 *         makebutton("Button4", gridbag, c);

 *

 *         c.weightx = 0.0;                //reset to the default

 *         makebutton("Button5", gridbag, c); //another row

 *

 *         c.gridwidth = GridBagConstraints.RELATIVE; //next-to-last in row

 *         makebutton("Button6", gridbag, c);

 *

 *         c.gridwidth = GridBagConstraints.REMAINDER; //end row

 *         makebutton("Button7", gridbag, c);

 *

 *         c.gridwidth = 1;                //reset to the default

 *         c.gridheight = 2;

 *         c.weighty = 1.0;

 *         makebutton("Button8", gridbag, c);

 *

 *         c.weighty = 0.0;                //reset to the default

 *         c.gridwidth = GridBagConstraints.REMAINDER; //end row

 *         c.gridheight = 1;               //reset to the default

 *         makebutton("Button9", gridbag, c);

 *         makebutton("Button10", gridbag, c);

 *

 *         setSize(300, 100);

 *     }

 *

 *     public static void main(String args[]) {

 *         Frame f = new Frame("GridBag Layout Example");

 *         GridBagEx1 ex1 = new GridBagEx1();

 *

 *         ex1.init();

 *

 *         f.add("Center", ex1);

 *         f.pack();

 *         f.setSize(f.getPreferredSize());

 *         f.show();

 *     }

 * }

 * </pre></blockquote><hr>

 * <p>

 * @author Doug Stein

 * @author Bill Spitzak (orignial NeWS & OLIT implementation)

 * @see       java.awt.GridBagConstraints

 * @see       java.awt.GridBagLayoutInfo

 * @see       java.awt.ComponentOrientation

 * @since JDK1.0

 */

public class GridBagLayout implements LayoutManager2,

java.io.Serializable {

    static final int EMPIRICMULTIPLIER = 2;

    /**

     * compatibility. Previously, this was

     * the maximum number of grid positions (both horizontal and

     * vertical) that could be laid out by the grid bag layout.

     * Current implementation doesn't impose any limits

     * on the size of a grid.

     */

    protected static final int MAXGRIDSIZE = 512;

    /**

     * The smallest grid that can be laid out by the grid bag layout.

     */

    protected static final int MINSIZE = 1;

    /**

     * The preferred grid size that can be laid out by the grid bag layout.

     */

    protected static final int PREFERREDSIZE = 2;

    /**

     * This hashtable maintains the association between

     * a component and its gridbag constraints.

     * The Keys in <code>comptable</code> are the components and the

     * values are the instances of <code>GridBagConstraints</code>.

     *

     * @serial

     * @see java.awt.GridBagConstraints

     */

    protected Hashtable<Component,GridBagConstraints> comptable;

    /**

     * This field holds a gridbag constraints instance

     * containing the default values, so if a component

     * does not have gridbag constraints associated with

     * it, then the component will be assigned a

     * copy of the <code>defaultConstraints</code>.

     *

     * @serial

     * @see #getConstraints(Component)

     * @see #setConstraints(Component, GridBagConstraints)

     * @see #lookupConstraints(Component)

     */

    protected GridBagConstraints defaultConstraints;

    /**

     * This field holds the layout information

     * for the gridbag.  The information in this field

     * is based on the most recent validation of the

     * gridbag.

     * If <code>layoutInfo</code> is <code>null</code>

     * this indicates that there are no components in

     * the gridbag or if there are components, they have

     * not yet been validated.

     *

     * @serial

     * @see #getLayoutInfo(Container, int)

     */

    protected GridBagLayoutInfo layoutInfo;

    /**

     * This field holds the overrides to the column minimum

     * width.  If this field is non-<code>null</code> the values are

     * applied to the gridbag after all of the minimum columns

     * widths have been calculated.

     * If columnWidths has more elements than the number of

     * columns, columns are added to the gridbag to match

     * the number of elements in columnWidth.

     *

     * @serial

     * @see #getLayoutDimensions()

     */

    public int columnWidths[];

    /**

     * This field holds the overrides to the row minimum

     * heights.  If this field is non-<code>null</code> the values are

     * applied to the gridbag after all of the minimum row

     * heights have been calculated.

     * If <code>rowHeights</code> has more elements than the number of

     * the number of elements in <code>rowHeights</code>.

     *

     * @serial

     * @see #getLayoutDimensions()

     */

    public int rowHeights[];

    /**

     * This field holds the overrides to the column weights.

     * If this field is non-<code>null</code> the values are

     * applied to the gridbag after all of the columns

     * weights have been calculated.

     * If <code>columnWeights[i]</code> &gt; weight for column i, then

     * column i is assigned the weight in <code>columnWeights[i]</code>.

     * If <code>columnWeights</code> has more elements than the number

     * of columns, the excess elements are ignored - they do

     * not cause more columns to be created.

     *

     * @serial

     */

    public double columnWeights[];

    /**

     * This field holds the overrides to the row weights.

     * If this field is non-<code>null</code> the values are

     * applied to the gridbag after all of the rows

     * weights have been calculated.

     * If <code>rowWeights[i]</code> &gt; weight for row i, then

     * row i is assigned the weight in <code>rowWeights[i]</code>.

     * If <code>rowWeights</code> has more elements than the number

     * of rows, the excess elements are ignored - they do

     * not cause more rows to be created.

     *

     * @serial

     */

    public double rowWeights[];

    /**

     * The component being positioned.  This is set before calling into

     * <code>adjustForGravity</code>.

     */

    private Component componentAdjusting;

    /**

     * Creates a grid bag layout manager.

     */

    public GridBagLayout () {

        comptable = new Hashtable<Component,GridBagConstraints>();

        defaultConstraints = new GridBagConstraints();

    }

    /**

     * Sets the constraints for the specified component in this layout.

     * @param       comp the component to be modified

     * @param       constraints the constraints to be applied

     */

    public void setConstraints(Component comp, GridBagConstraints constraints) {

        comptable.put(comp, (GridBagConstraints)constraints.clone());

    }

    /**

     * Gets the constraints for the specified component.  A copy of

     * the actual <code>GridBagConstraints</code> object is returned.

     * @param       comp the component to be queried

     * @return      the constraint for the specified component in this

     *                  grid bag layout; a copy of the actual constraint

     *                  object is returned

     */

    public GridBagConstraints getConstraints(Component comp) {

        GridBagConstraints constraints = comptable.get(comp);

        if (constraints == null) {

            setConstraints(comp, defaultConstraints);

            constraints = comptable.get(comp);

        }

        return (GridBagConstraints)constraints.clone();

    }