/*

 * 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.awt.event.KeyEvent;

import java.awt.event.WindowEvent;

import java.awt.peer.FramePeer;

import java.io.IOException;

import java.io.ObjectInputStream;

import java.io.ObjectOutputStream;

import java.io.Serializable;

import java.util.ArrayList;

import java.util.Vector;

import javax.accessibility.AccessibleContext;

import javax.accessibility.AccessibleRole;

import javax.accessibility.AccessibleState;

import javax.accessibility.AccessibleStateSet;

import javax.swing.WindowConstants;

import sun.awt.AWTAccessor;

import sun.awt.SunToolkit;

/**

 * A {@code Frame} is a top-level window with a title and a border.

 * <p>

 * The size of the frame includes any area designated for the

 * border.  The dimensions of the border area may be obtained

 * using the {@code getInsets} method, however, since

 * these dimensions are platform-dependent, a valid insets

 * value cannot be obtained until the frame is made displayable

 * by either calling {@code pack} or {@code show}.

 * Since the border area is included in the overall size of the

 * frame, the border effectively obscures a portion of the frame,

 * constraining the area available for rendering and/or displaying

 * subcomponents to the rectangle which has an upper-left corner

 * location of {@code (insets.left, insets.top)}, and has a size of

 * {@code width - (insets.left + insets.right)} by

 * {@code height - (insets.top + insets.bottom)}.

 * <p>

 * The default layout for a frame is {@code BorderLayout}.

 * <p>

 * A frame may have its native decorations (i.e. {@code Frame}

 * and {@code Titlebar}) turned off

 * with {@code setUndecorated}. This can only be done while the frame

 * is not {@link Component#isDisplayable() displayable}.

 * <p>

 * In a multi-screen environment, you can create a {@code Frame}

 * on a different screen device by constructing the {@code Frame}

 * with {@link #Frame(GraphicsConfiguration)} or

 * {@link #Frame(String title, GraphicsConfiguration)}.  The

 * {@code GraphicsConfiguration} object is one of the

 * {@code GraphicsConfiguration} objects of the target screen

 * device.

 * <p>

 * In a virtual device multi-screen environment in which the desktop

 * area could span multiple physical screen devices, the bounds of all

 * configurations are relative to the virtual-coordinate system.  The

 * origin of the virtual-coordinate system is at the upper left-hand

 * corner of the primary physical screen.  Depending on the location

 * of the primary screen in the virtual device, negative coordinates

 * are possible, as shown in the following figure.

 * <p>

 * <p>

 * In such an environment, when calling {@code setLocation},

 * you must pass a virtual coordinate to this method.  Similarly,

 * calling {@code getLocationOnScreen} on a {@code Frame}

 * returns virtual device coordinates.  Call the {@code getBounds}

 * method of a {@code GraphicsConfiguration} to find its origin in

 * the virtual coordinate system.

 * <p>

 * The following code sets the

 * location of the {@code Frame} at (10, 10) relative

 * to the origin of the physical screen of the corresponding

 * {@code GraphicsConfiguration}.  If the bounds of the

 * {@code GraphicsConfiguration} is not taken into account, the

 * {@code Frame} location would be set at (10, 10) relative to the

 * virtual-coordinate system and would appear on the primary physical

 * screen, which might be different from the physical screen of the

 * specified {@code GraphicsConfiguration}.

 *

 * <pre>

 *      Frame f = new Frame(GraphicsConfiguration gc);

 *      Rectangle bounds = gc.getBounds();

 *      f.setLocation(10 + bounds.x, 10 + bounds.y);

 * </pre>

 *

 * <p>

 * Frames are capable of generating the following types of

 * {@code WindowEvent}s:

 * <ul>

 * <li>{@code WINDOW_OPENED}

 * <li>{@code WINDOW_CLOSING}:

 *     <br>If the program doesn't

 *     explicitly hide or dispose the window while processing

 *     this event, the window close operation is canceled.

 * <li>{@code WINDOW_CLOSED}

 * <li>{@code WINDOW_ICONIFIED}

 * <li>{@code WINDOW_DEICONIFIED}

 * <li>{@code WINDOW_ACTIVATED}

 * <li>{@code WINDOW_DEACTIVATED}

 * <li>{@code WINDOW_GAINED_FOCUS}

 * <li>{@code WINDOW_LOST_FOCUS}

 * <li>{@code WINDOW_STATE_CHANGED}

 * </ul>

 *

 * @author      Sami Shaio

 * @see WindowEvent

 * @see Window#addWindowListener

 * @since       1.0

 */

public class Frame extends Window implements MenuContainer {

    /* Note: These are being obsoleted;  programs should use the Cursor class

     * variables going forward. See Cursor and Component.setCursor.

     */

   /**

    * @deprecated   replaced by {@code Cursor.DEFAULT_CURSOR}.

    */

    @Deprecated

    public static final int     DEFAULT_CURSOR                  = Cursor.DEFAULT_CURSOR;

   /**

    * @deprecated   replaced by {@code Cursor.CROSSHAIR_CURSOR}.

    */

    @Deprecated

    public static final int     CROSSHAIR_CURSOR                = Cursor.CROSSHAIR_CURSOR;

   /**

    * @deprecated   replaced by {@code Cursor.TEXT_CURSOR}.

    */

    @Deprecated

    public static final int     TEXT_CURSOR                     = Cursor.TEXT_CURSOR;

   /**

    * @deprecated   replaced by {@code Cursor.WAIT_CURSOR}.

    */

    @Deprecated

    public static final int     WAIT_CURSOR                     = Cursor.WAIT_CURSOR;

   /**

    * @deprecated   replaced by {@code Cursor.SW_RESIZE_CURSOR}.

    */

    @Deprecated

    public static final int     SW_RESIZE_CURSOR                = Cursor.SW_RESIZE_CURSOR;

   /**

    * @deprecated   replaced by {@code Cursor.SE_RESIZE_CURSOR}.

    */

    @Deprecated

    public static final int     SE_RESIZE_CURSOR                = Cursor.SE_RESIZE_CURSOR;

   /**

    * @deprecated   replaced by {@code Cursor.NW_RESIZE_CURSOR}.

    */

    @Deprecated

    public static final int     NW_RESIZE_CURSOR                = Cursor.NW_RESIZE_CURSOR;

   /**

    * @deprecated   replaced by {@code Cursor.NE_RESIZE_CURSOR}.

    */

    @Deprecated

    public static final int     NE_RESIZE_CURSOR                = Cursor.NE_RESIZE_CURSOR;

   /**

    * @deprecated   replaced by {@code Cursor.N_RESIZE_CURSOR}.

    */

    @Deprecated

    public static final int     N_RESIZE_CURSOR                 = Cursor.N_RESIZE_CURSOR;

   /**

    * @deprecated   replaced by {@code Cursor.S_RESIZE_CURSOR}.

    */

    @Deprecated

    public static final int     S_RESIZE_CURSOR                 = Cursor.S_RESIZE_CURSOR;

   /**

    * @deprecated   replaced by {@code Cursor.W_RESIZE_CURSOR}.

    */

    @Deprecated

    public static final int     W_RESIZE_CURSOR                 = Cursor.W_RESIZE_CURSOR;

   /**

    * @deprecated   replaced by {@code Cursor.E_RESIZE_CURSOR}.

    */

    @Deprecated

    public static final int     E_RESIZE_CURSOR                 = Cursor.E_RESIZE_CURSOR;

   /**

    * @deprecated   replaced by {@code Cursor.HAND_CURSOR}.

    */

    @Deprecated

    public static final int     HAND_CURSOR                     = Cursor.HAND_CURSOR;

   /**

    * @deprecated   replaced by {@code Cursor.MOVE_CURSOR}.

    */

    @Deprecated

    public static final int     MOVE_CURSOR                     = Cursor.MOVE_CURSOR;

    /**

     * Frame is in the "normal" state.  This symbolic constant names a

     * frame state with all state bits cleared.

     * @see #setExtendedState(int)

     * @see #getExtendedState

     */

    public static final int NORMAL = 0;

    /**

     * This state bit indicates that frame is iconified.

     * @see #setExtendedState(int)

     * @see #getExtendedState

     */

    public static final int ICONIFIED = 1;

    /**

     * This state bit indicates that frame is maximized in the

     * horizontal direction.

     * @see #setExtendedState(int)

     * @see #getExtendedState

     * @since 1.4

     */

    public static final int MAXIMIZED_HORIZ = 2;

    /**

     * This state bit indicates that frame is maximized in the

     * vertical direction.

     * @see #setExtendedState(int)

     * @see #getExtendedState

     * @since 1.4

     */

    public static final int MAXIMIZED_VERT = 4;

    /**

     * This state bit mask indicates that frame is fully maximized

     * (that is both horizontally and vertically).  It is just a

     * convenience alias for

     * <code>MAXIMIZED_VERT&nbsp;|&nbsp;MAXIMIZED_HORIZ</code>.

     *

     * <p>Note that the correct test for frame being fully maximized is

     * <pre>

     *     (state & Frame.MAXIMIZED_BOTH) == Frame.MAXIMIZED_BOTH

     * </pre>

     *

     * <p>To test is frame is maximized in <em>some</em> direction use

     * <pre>

     *     (state & Frame.MAXIMIZED_BOTH) != 0

     * </pre>

     *

     * @see #setExtendedState(int)

     * @see #getExtendedState

     * @since 1.4

     */

    public static final int MAXIMIZED_BOTH = MAXIMIZED_VERT | MAXIMIZED_HORIZ;

    /**

     * Maximized bounds for this frame.

     * @see     #setMaximizedBounds(Rectangle)

     * @see     #getMaximizedBounds

     * @serial

     * @since 1.4

     */

    Rectangle maximizedBounds;

    /**

     * This is the title of the frame.  It can be changed

     * at any time.  {@code title} can be null and if

     * this is the case the {@code title} = "".

     *

     * @serial

     * @see #getTitle

     * @see #setTitle(String)

     */

    String      title = "Untitled";

    /**

     * The frames menubar.  If {@code menuBar} = null

     * the frame will not have a menubar.

     *

     * @serial

     * @see #getMenuBar

     * @see #setMenuBar(MenuBar)

     */

    MenuBar     menuBar;

    /**

     * This field indicates whether the frame is resizable.

     * This property can be changed at any time.

     * {@code resizable} will be true if the frame is

     * resizable, otherwise it will be false.

     *

     * @serial

     * @see #isResizable()

     */

    boolean     resizable = true;

    /**

     * This field indicates whether the frame is undecorated.

     * This property can only be changed while the frame is not displayable.

     * {@code undecorated} will be true if the frame is

     * undecorated, otherwise it will be false.

     *

     * @serial

     * @see #setUndecorated(boolean)

     * @see #isUndecorated()

     * @see Component#isDisplayable()

     * @since 1.4

     */

    boolean undecorated = false;

    /**

     * {@code mbManagement} is only used by the Motif implementation.

     *

     * @serial

     */

    boolean     mbManagement = false;   /* used only by the Motif impl. */

    // XXX: uwe: abuse old field for now

    // will need to take care of serialization

    private int state = NORMAL;

    /*

     * The Windows owned by the Frame.

     * Note: in 1.2 this has been superseded by Window.ownedWindowList

     *

     * @serial

     * @see java.awt.Window#ownedWindowList

     */

    Vector<Window> ownedWindows;

    private static final String base = "frame";

    private static int nameCounter = 0;

    /*

     * JDK 1.1 serialVersionUID

     */

     private static final long serialVersionUID = 2673458971256075116L;

    static {

        /* ensure that the necessary native libraries are loaded */

        Toolkit.loadLibraries();

        if (!GraphicsEnvironment.isHeadless()) {

            initIDs();

        }

    }

    /**

     * Constructs a new instance of {@code Frame} that is

     * initially invisible.  The title of the {@code Frame}

     * is empty.

     * @exception HeadlessException when

     *     {@code GraphicsEnvironment.isHeadless()} returns {@code true}

     * @see java.awt.GraphicsEnvironment#isHeadless()

     * @see Component#setSize

     * @see Component#setVisible(boolean)

     */

    public Frame() throws HeadlessException {

        this("");

    }

    /**

     * Constructs a new, initially invisible {@code Frame} with the

     * specified {@code GraphicsConfiguration}.

     *

     * @param gc the {@code GraphicsConfiguration}

     * of the target screen device. If {@code gc}

     * is {@code null}, the system default

     * {@code GraphicsConfiguration} is assumed.

     * @exception IllegalArgumentException if

     * {@code gc} is not from a screen device.

     * @exception HeadlessException when

     *     {@code GraphicsEnvironment.isHeadless()} returns {@code true}

     * @see java.awt.GraphicsEnvironment#isHeadless()

     * @since     1.3

     */

    public Frame(GraphicsConfiguration gc) {

        this("", gc);

    }

    /**

     * Constructs a new, initially invisible {@code Frame} object

     * with the specified title.

     * @param title the title to be displayed in the frame's border.

     *              A {@code null} value

     *              is treated as an empty string, "".

     * @exception HeadlessException when

     *     {@code GraphicsEnvironment.isHeadless()} returns {@code true}

     * @see java.awt.GraphicsEnvironment#isHeadless()

     * @see java.awt.Component#setSize

     * @see java.awt.Component#setVisible(boolean)

     * @see java.awt.GraphicsConfiguration#getBounds

     */

    public Frame(String title) throws HeadlessException {

        init(title, null);

    }

    /**

     * Constructs a new, initially invisible {@code Frame} object

     * with the specified title and a

     * {@code GraphicsConfiguration}.

     * @param title the title to be displayed in the frame's border.

     *              A {@code null} value

     *              is treated as an empty string, "".

     * @param gc the {@code GraphicsConfiguration}

     * of the target screen device.  If {@code gc} is

     * {@code null}, the system default

     * {@code GraphicsConfiguration} is assumed.

     * @exception IllegalArgumentException if {@code gc}

     * is not from a screen device.

     * @exception HeadlessException when

     *     {@code GraphicsEnvironment.isHeadless()} returns {@code true}

     * @see java.awt.GraphicsEnvironment#isHeadless()

     * @see java.awt.Component#setSize

     * @see java.awt.Component#setVisible(boolean)

     * @see java.awt.GraphicsConfiguration#getBounds

     * @since 1.3

     */

    public Frame(String title, GraphicsConfiguration gc) {

        super(gc);

        init(title, gc);

    }

    private void init(String title, GraphicsConfiguration gc) {

        this.title = title;

        SunToolkit.checkAndSetPolicy(this);

    }

    /**

     * Construct a name for this component.  Called by getName() when the

     * name is null.

     */

    String constructComponentName() {

        synchronized (Frame.class) {

            return base + nameCounter++;

        }

    }

    /**

     * Makes this Frame displayable by connecting it to

     * a native screen resource.  Making a frame displayable will

     * cause any of its children to be made displayable.

     * This method is called internally by the toolkit and should

     * not be called directly by programs.

     * @see Component#isDisplayable

     * @see #removeNotify

     */

    public void addNotify() {

        synchronized (getTreeLock()) {

            if (peer == null) {

                peer = getComponentFactory().createFrame(this);

            }

            FramePeer p = (FramePeer)peer;

            MenuBar menuBar = this.menuBar;

            if (menuBar != null) {

                mbManagement = true;

                menuBar.addNotify();

                p.setMenuBar(menuBar);

            }

            p.setMaximizedBounds(maximizedBounds);

            super.addNotify();

        }

    }

    /**

     * Gets the title of the frame.  The title is displayed in the

     * frame's border.

     * @return    the title of this frame, or an empty string ("")

     *                if this frame doesn't have a title.

     * @see       #setTitle(String)

     */

    public String getTitle() {

        return title;

    }

    /**

     * Sets the title for this frame to the specified string.

     * @param title the title to be displayed in the frame's border.

     *              A {@code null} value

     *              is treated as an empty string, "".

     * @see      #getTitle

     */

    public void setTitle(String title) {

        String oldTitle = this.title;