/*

 * Copyright 1997-2007 Sun Microsystems, Inc.  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.  Sun designates this

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

 * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

 * CA 95054 USA or visit www.sun.com if you need additional information or

 * have any questions.

 */

package javax.swing;

import java.applet.Applet;

import java.awt.*;

import java.awt.event.*;

import java.beans.*;

import java.security.AccessController;

import javax.accessibility.*;

import javax.swing.plaf.RootPaneUI;

import java.util.Vector;

import java.io.Serializable;

import javax.swing.border.*;

import sun.security.action.GetBooleanAction;

/**

 * A lightweight container used behind the scenes by

 * <code>JFrame</code>, <code>JDialog</code>, <code>JWindow</code>,

 * <code>JApplet</code>, and <code>JInternalFrame</code>.

 * For task-oriented information on functionality provided by root panes

 * see <a href="http://java.sun.com/docs/books/tutorial/uiswing/components/rootpane.html">How to Use Root Panes</a>,

 * a section in <em>The Java Tutorial</em>.

 *

 * <p>

 * The following image shows the relationships between

 * the classes that use root panes.

 * <p align=center><img src="doc-files/JRootPane-1.gif"

 * alt="The following text describes this graphic."

 * HEIGHT=484 WIDTH=629></p>

 * The "heavyweight" components (those that delegate to a peer, or native

 * component on the host system) are shown with a darker, heavier box. The four

 * heavyweight JFC/Swing containers (<code>JFrame</code>, <code>JDialog</code>,

 * <code>JWindow</code>, and <code>JApplet</code>) are

 * shown in relation to the AWT classes they extend.

 * These four components are the

 * only heavyweight containers in the Swing library. The lightweight container

 * <code>JInternalFrame</code> is also shown.

 * All five of these JFC/Swing containers implement the

 * <code>RootPaneContainer</code> interface,

 * and they all delegate their operations to a

 * <code>JRootPane</code> (shown with a little "handle" on top).

 * <blockquote>

 * <b>Note:</b> The <code>JComponent</code> method <code>getRootPane</code>

 * can be used to obtain the <code>JRootPane</code> that contains

 * a given component.

 * </blockquote>

 * <table align="right" border="0" summary="layout">

 * <tr>

 * <td align="center">

 * <img src="doc-files/JRootPane-2.gif"

 * alt="The following text describes this graphic." HEIGHT=386 WIDTH=349>

 * </td>

 * </tr>

 * </table>

 * The diagram at right shows the structure of a <code>JRootPane</code>.

 * A <code>JRootpane</code> is made up of a <code>glassPane</code>,

 * an optional <code>menuBar</code>, and a <code>contentPane</code>.

 * (The <code>JLayeredPane</code> manages the <code>menuBar</code>

 * and the <code>contentPane</code>.)

 * The <code>glassPane</code> sits over the top of everything,

 * where it is in a position to intercept mouse movements.

 * Since the <code>glassPane</code> (like the <code>contentPane</code>)

 * can be an arbitrary component, it is also possible to set up the

 * <code>glassPane</code> for drawing. Lines and images on the

 * <code>glassPane</code> can then range

 * over the frames underneath without being limited by their boundaries.

 * <p>

 * Although the <code>menuBar</code> component is optional,

 * the <code>layeredPane</code>, <code>contentPane</code>,

 * and <code>glassPane</code> always exist.

 * Attempting to set them to <code>null</code> generates an exception.

 * <p>

 * To add components to the <code>JRootPane</code> (other than the

 * optional menu bar), you add the object to the <code>contentPane</code>

 * of the <code>JRootPane</code>, like this:

 * <pre>

 *       rootPane.getContentPane().add(child);

 * </pre>

 * The same principle holds true for setting layout managers, removing

 * components, listing children, etc. All these methods are invoked on

 * the <code>contentPane</code> instead of on the <code>JRootPane</code>.

 * <blockquote>

 * <b>Note:</b> The default layout manager for the <code>contentPane</code> is

 *  a <code>BorderLayout</code> manager. However, the <code>JRootPane</code>

 *  uses a custom <code>LayoutManager</code>.

 *  So, when you want to change the layout manager for the components you added

 *  to a <code>JRootPane</code>, be sure to use code like this:

 * <pre>

 *    rootPane.getContentPane().setLayout(new BoxLayout());

 * </pre></blockquote>

 * If a <code>JMenuBar</code> component is set on the <code>JRootPane</code>,

 * it is positioned along the upper edge of the frame.

 * The <code>contentPane</code> is adjusted in location and size to

 * fill the remaining area.

 * (The <code>JMenuBar</code> and the <code>contentPane</code> are added to the

 * <code>layeredPane</code> component at the

 * <code>JLayeredPane.FRAME_CONTENT_LAYER</code> layer.)

 * <p>

 * The <code>layeredPane</code> is the parent of all children in the

 * <code>JRootPane</code> -- both as the direct parent of the menu and

 * the grandparent of all components added to the <code>contentPane</code>.

 * It is an instance of <code>JLayeredPane</code>,

 * which provides the ability to add components at several layers.

 * This capability is very useful when working with menu popups,

 * dialog boxes, and dragging -- situations in which you need to place

 * a component on top of all other components in the pane.

 * <p>

 * The <code>glassPane</code> sits on top of all other components in the

 * <code>JRootPane</code>.

 * That provides a convenient place to draw above all other components,

 * and makes it possible to intercept mouse events,

 * which is useful both for dragging and for drawing.

 * Developers can use <code>setVisible</code> on the <code>glassPane</code>

 * to control when the <code>glassPane</code> displays over the other children.

 * By default the <code>glassPane</code> is not visible.

 * <p>

 * The custom <code>LayoutManager</code> used by <code>JRootPane</code>

 * ensures that:

 * <OL>

 * <LI>The <code>glassPane</code> fills the entire viewable

 *     area of the <code>JRootPane</code> (bounds - insets).

 * <LI>The <code>layeredPane</code> fills the entire viewable area of the

 *     <code>JRootPane</code>. (bounds - insets)

 * <LI>The <code>menuBar</code> is positioned at the upper edge of the

 *     <code>layeredPane</code>.

 * <LI>The <code>contentPane</code> fills the entire viewable area,

 *     minus the <code>menuBar</code>, if present.

 * </OL>

 * Any other views in the <code>JRootPane</code> view hierarchy are ignored.

 * <p>

 * If you replace the <code>LayoutManager</code> of the <code>JRootPane</code>,

 * you are responsible for managing all of these views.

 * So ordinarily you will want to be sure that you

 * change the layout manager for the <code>contentPane</code> rather than

 * for the <code>JRootPane</code> itself!

 * <p>

 * The painting architecture of Swing requires an opaque

 * <code>JComponent</code>

 * to exist in the containment hieararchy above all other components. This is

 * typically provided by way of the content pane. If you replace the content

 * pane, it is recommended that you make the content pane opaque

 * by way of <code>setOpaque(true)</code>. Additionally, if the content pane

 * overrides <code>paintComponent</code>, it

 * will need to completely fill in the background in an opaque color in

 * <code>paintComponent</code>.

 * <p>

 * <strong>Warning:</strong> Swing is not thread safe. For more

 * information see <a

 * href="package-summary.html#threading">Swing's Threading

 * Policy</a>.

 * <p>

 * <strong>Warning:</strong>

 * Serialized objects of this class will not be compatible with

 * future Swing releases. The current serialization support is

 * appropriate for short term storage or RMI between applications running

 * the same version of Swing.  As of 1.4, support for long term storage

 * of all JavaBeans<sup><font size="-2">TM</font></sup>

 * has been added to the <code>java.beans</code> package.

 * Please see {@link java.beans.XMLEncoder}.

 *

 * @see JLayeredPane

 * @see JMenuBar

 * @see JWindow

 * @see JFrame

 * @see JDialog

 * @see JApplet

 * @see JInternalFrame

 * @see JComponent

 * @see BoxLayout

 *

 * @see <a href="http://java.sun.com/products/jfc/tsc/articles/mixing/">

 * Mixing Heavy and Light Components</a>

 *

 * @author David Kloba

 */

/// PENDING(klobad) Who should be opaque in this component?

public class JRootPane extends JComponent implements Accessible {

    private static final String uiClassID = "RootPaneUI";

    /**

     * Whether or not we should dump the stack when true double buffering

     * is disabled. Default is false.

     */

    private static final boolean LOG_DISABLE_TRUE_DOUBLE_BUFFERING;

    /**

     * Whether or not we should ignore requests to disable true double

     * buffering. Default is false.

     */

    private static final boolean IGNORE_DISABLE_TRUE_DOUBLE_BUFFERING;

    /**

     * Constant used for the windowDecorationStyle property. Indicates that

     * the <code>JRootPane</code> should not provide any sort of

     * Window decorations.

     *

     * @since 1.4

     */

    public static final int NONE = 0;

    /**

     * Constant used for the windowDecorationStyle property. Indicates that

     * the <code>JRootPane</code> should provide decorations appropriate for

     * a Frame.

     *

     * @since 1.4

     */

    public static final int FRAME = 1;

    /**

     * Constant used for the windowDecorationStyle property. Indicates that

     * the <code>JRootPane</code> should provide decorations appropriate for

     * a Dialog.

     *

     * @since 1.4

     */

    public static final int PLAIN_DIALOG = 2;

    /**

     * Constant used for the windowDecorationStyle property. Indicates that

     * the <code>JRootPane</code> should provide decorations appropriate for

     * a Dialog used to display an informational message.

     *

     * @since 1.4

     */

    public static final int INFORMATION_DIALOG = 3;

    /**

     * Constant used for the windowDecorationStyle property. Indicates that

     * the <code>JRootPane</code> should provide decorations appropriate for

     * a Dialog used to display an error message.

     *

     * @since 1.4

     */

    public static final int ERROR_DIALOG = 4;

    /**

     * Constant used for the windowDecorationStyle property. Indicates that

     * the <code>JRootPane</code> should provide decorations appropriate for

     * a Dialog used to display a <code>JColorChooser</code>.

     *

     * @since 1.4

     */

    public static final int COLOR_CHOOSER_DIALOG = 5;

    /**

     * Constant used for the windowDecorationStyle property. Indicates that

     * the <code>JRootPane</code> should provide decorations appropriate for

     * a Dialog used to display a <code>JFileChooser</code>.

     *

     * @since 1.4

     */

    public static final int FILE_CHOOSER_DIALOG = 6;

    /**

     * Constant used for the windowDecorationStyle property. Indicates that

     * the <code>JRootPane</code> should provide decorations appropriate for

     * a Dialog used to present a question to the user.

     *

     * @since 1.4

     */

    public static final int QUESTION_DIALOG = 7;

    /**

     * Constant used for the windowDecorationStyle property. Indicates that

     * the <code>JRootPane</code> should provide decorations appropriate for

     * a Dialog used to display a warning message.

     *

     * @since 1.4

     */

    public static final int WARNING_DIALOG = 8;

    private int windowDecorationStyle;

    /** The menu bar. */

    protected JMenuBar menuBar;

    /** The content pane. */

    protected Container contentPane;

    /** The layered pane that manages the menu bar and content pane. */

    protected JLayeredPane layeredPane;

    /**

     * The glass pane that overlays the menu bar and content pane,

     *  so it can intercept mouse movements and such.

     */

    protected Component glassPane;

    /**

     * The button that gets activated when the pane has the focus and

     * a UI-specific action like pressing the <b>Enter</b> key occurs.

     */

    protected JButton defaultButton;

    /**

     * As of Java 2 platform v1.3 this unusable field is no longer used.

     * To override the default button you should replace the <code>Action</code>

     * in the <code>JRootPane</code>'s <code>ActionMap</code>. Please refer to

     * the key bindings specification for further details.

     *

     * @deprecated As of Java 2 platform v1.3.

     *  @see #defaultButton

     */

    @Deprecated

    protected DefaultAction defaultPressAction;

    /**

     * As of Java 2 platform v1.3 this unusable field is no longer used.

     * To override the default button you should replace the <code>Action</code>

     * in the <code>JRootPane</code>'s <code>ActionMap</code>. Please refer to

     * the key bindings specification for further details.

     *

     * @deprecated As of Java 2 platform v1.3.

     *  @see #defaultButton

     */

    @Deprecated

    protected DefaultAction defaultReleaseAction;

    /**

     * Whether or not true double buffering should be used.  This is typically

     * true, but may be set to false in special situations.  For example,

     * heavy weight popups (backed by a window) set this to false.

     */

    boolean useTrueDoubleBuffering = true;

    static {

        LOG_DISABLE_TRUE_DOUBLE_BUFFERING =

            AccessController.doPrivileged(new GetBooleanAction(

                                   "swing.logDoubleBufferingDisable"));

        IGNORE_DISABLE_TRUE_DOUBLE_BUFFERING =

            AccessController.doPrivileged(new GetBooleanAction(

                                   "swing.ignoreDoubleBufferingDisable"));

    }

    /**

     * Creates a <code>JRootPane</code>, setting up its

     * <code>glassPane</code>, <code>layeredPane</code>,

     * and <code>contentPane</code>.

     */

    public JRootPane() {

        setGlassPane(createGlassPane());

        setLayeredPane(createLayeredPane());

        setContentPane(createContentPane());

        setLayout(createRootLayout());

        setDoubleBuffered(true);

        updateUI();

    }

    /**

     * {@inheritDoc}

     * @since 1.6

     */

    public void setDoubleBuffered(boolean aFlag) {

        if (isDoubleBuffered() != aFlag) {

            super.setDoubleBuffered(aFlag);

            RepaintManager.currentManager(this).doubleBufferingChanged(this);

        }

    }

    /**

     * Returns a constant identifying the type of Window decorations the

     * <code>JRootPane</code> is providing.

     *

     * @return One of <code>NONE</code>, <code>FRAME</code>,

     *        <code>PLAIN_DIALOG</code>, <code>INFORMATION_DIALOG</code>,

     *        <code>ERROR_DIALOG</code>, <code>COLOR_CHOOSER_DIALOG</code>,

     *        <code>FILE_CHOOSER_DIALOG</code>, <code>QUESTION_DIALOG</code> or

     *        <code>WARNING_DIALOG</code>.

     * @see #setWindowDecorationStyle

     * @since 1.4

     */

    public int getWindowDecorationStyle() {

        return windowDecorationStyle;

    }

    /**

     * Sets the type of Window decorations (such as borders, widgets for

     * closing a Window, title ...) the <code>JRootPane</code> should

     * provide. The default is to provide no Window decorations

     * (<code>NONE</code>).

     * <p>

     * This is only a hint, and some look and feels may not support

     * this.

     * This is a bound property.

     *

     * @param windowDecorationStyle Constant identifying Window decorations

     *        to provide.

     * @see JDialog#setDefaultLookAndFeelDecorated

     * @see JFrame#setDefaultLookAndFeelDecorated

     * @see LookAndFeel#getSupportsWindowDecorations

     * @throws IllegalArgumentException if <code>style</code> is

     *        not one of: <code>NONE</code>, <code>FRAME</code>,

     *        <code>PLAIN_DIALOG</code>, <code>INFORMATION_DIALOG</code>,

     *        <code>ERROR_DIALOG</code>, <code>COLOR_CHOOSER_DIALOG</code>,

     *        <code>FILE_CHOOSER_DIALOG</code>, <code>QUESTION_DIALOG</code>, or

     *        <code>WARNING_DIALOG</code>.

     * @since 1.4

     * @beaninfo

     *        bound: true

     *         enum: NONE                   JRootPane.NONE

     *               FRAME                  JRootPane.FRAME

     *               PLAIN_DIALOG           JRootPane.PLAIN_DIALOG

     *               INFORMATION_DIALOG     JRootPane.INFORMATION_DIALOG

     *               ERROR_DIALOG           JRootPane.ERROR_DIALOG

     *               COLOR_CHOOSER_DIALOG   JRootPane.COLOR_CHOOSER_DIALOG

     *               FILE_CHOOSER_DIALOG    JRootPane.FILE_CHOOSER_DIALOG

     *               QUESTION_DIALOG        JRootPane.QUESTION_DIALOG

     *               WARNING_DIALOG         JRootPane.WARNING_DIALOG

     *       expert: true

     *    attribute: visualUpdate true

     *  description: Identifies the type of Window decorations to provide

     */

    public void setWindowDecorationStyle(int windowDecorationStyle) {

        if (windowDecorationStyle < 0 ||

                  windowDecorationStyle > WARNING_DIALOG) {

            throw new IllegalArgumentException("Invalid decoration style");

        }

        int oldWindowDecorationStyle = getWindowDecorationStyle();

        this.windowDecorationStyle = windowDecorationStyle;

        firePropertyChange("windowDecorationStyle",

                            oldWindowDecorationStyle,

                            windowDecorationStyle);

    }

    /**

     * Returns the L&F object that renders this component.

     *

     * @return <code>LabelUI</code> object

     * @since 1.3

     */

    public RootPaneUI getUI() {

        return (RootPaneUI)ui;

    }

    /**

     * Sets the L&F object that renders this component.

     *

     * @param ui  the <code>LabelUI</code> L&F object

     * @see UIDefaults#getUI

     * @beaninfo

     *        bound: true

     *       hidden: true

     *      expert: true

     *    attribute: visualUpdate true

     *  description: The UI object that implements the Component's LookAndFeel.

     * @since 1.3

     */

    public void setUI(RootPaneUI ui) {

        super.setUI(ui);

    }

    /**

     * Resets the UI property to a value from the current look and feel.

     *

     * @see JComponent#updateUI

     */

    public void updateUI() {

        setUI((RootPaneUI)UIManager.getUI(this));

    }

    /**

     * Returns a string that specifies the name of the L&F class

     * that renders this component.

     *

     * @return the string "RootPaneUI"

     *

     * @see JComponent#getUIClassID

     * @see UIDefaults#getUI

     */

    public String getUIClassID() {

        return uiClassID;

    }

    /**

      * Called by the constructor methods to create the default

      * <code>layeredPane</code>.

      * Bt default it creates a new <code>JLayeredPane</code>.

      * @return the default <code>layeredPane</code>

      */

    protected JLayeredPane createLayeredPane() {

        JLayeredPane p = new JLayeredPane();

        p.setName(this.getName()+".layeredPane");

        return p;

    }

    /**

     * Called by the constructor methods to create the default

     * <code>contentPane</code>.

     * By default this method creates a new <code>JComponent</code> add sets a

     * <code>BorderLayout</code> as its <code>LayoutManager</code>.

     * @return the default <code>contentPane</code>

     */

    protected Container createContentPane() {

        JComponent c = new JPanel();

        c.setName(this.getName()+".contentPane");

        c.setLayout(new BorderLayout() {

            /* This BorderLayout subclass maps a null constraint to CENTER.

             * Although the reference BorderLayout also does this, some VMs

             * throw an IllegalArgumentException.

             */

            public void addLayoutComponent(Component comp, Object constraints) {

                if (constraints == null) {

                    constraints = BorderLayout.CENTER;

                }