/*

 * Copyright 1995-2009 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 java.awt;

import java.awt.dnd.DropTarget;

import java.awt.event.*;

import java.awt.peer.ContainerPeer;

import java.awt.peer.ComponentPeer;

import java.awt.peer.LightweightPeer;

import java.beans.PropertyChangeListener;

import java.io.IOException;

import java.io.ObjectInputStream;

import java.io.ObjectOutputStream;

import java.io.ObjectStreamField;

import java.io.PrintStream;

import java.io.PrintWriter;

import java.util.Arrays;

import java.util.EventListener;

import java.util.HashSet;

import java.util.Set;

import javax.accessibility.*;

import sun.util.logging.PlatformLogger;

import sun.awt.AppContext;

import sun.awt.CausedFocusEvent;

import sun.awt.PeerEvent;

import sun.awt.SunToolkit;

import sun.awt.dnd.SunDropTargetEvent;

import sun.java2d.pipe.Region;

/**

 * A generic Abstract Window Toolkit(AWT) container object is a component

 * that can contain other AWT components.

 * <p>

 * Components added to a container are tracked in a list.  The order

 * of the list will define the components' front-to-back stacking order

 * within the container.  If no index is specified when adding a

 * component to a container, it will be added to the end of the list

 * (and hence to the bottom of the stacking order).

 * <p>

 * <b>Note</b>: For details on the focus subsystem, see

 * <a href="http://java.sun.com/docs/books/tutorial/uiswing/misc/focus.html">

 * How to Use the Focus Subsystem</a>,

 * a section in <em>The Java Tutorial</em>, and the

 * <a href="../../java/awt/doc-files/FocusSpec.html">Focus Specification</a>

 * for more information.

 *

 * @author      Arthur van Hoff

 * @author      Sami Shaio

 * @see       #add(java.awt.Component, int)

 * @see       #getComponent(int)

 * @see       LayoutManager

 * @since     JDK1.0

 */

public class Container extends Component {

    private static final PlatformLogger log = PlatformLogger.getLogger("java.awt.Container");

    private static final PlatformLogger eventLog = PlatformLogger.getLogger("java.awt.event.Container");

    private static final Component[] EMPTY_ARRAY = new Component[0];

    /**

     * The components in this container.

     * @see #add

     * @see #getComponents

     */

    private java.util.List<Component> component = new java.util.ArrayList<Component>();

    /**

     * Layout manager for this container.

     * @see #doLayout

     * @see #setLayout

     * @see #getLayout

     */

    LayoutManager layoutMgr;

    /**

     * Event router for lightweight components.  If this container

     * is native, this dispatcher takes care of forwarding and

     * retargeting the events to lightweight components contained

     * (if any).

     */

    private LightweightDispatcher dispatcher;

    /**

     * The focus traversal policy that will manage keyboard traversal of this

     * Container's children, if this Container is a focus cycle root. If the

     * value is null, this Container inherits its policy from its focus-cycle-

     * root ancestor. If all such ancestors of this Container have null

     * policies, then the current KeyboardFocusManager's default policy is

     * used. If the value is non-null, this policy will be inherited by all

     * focus-cycle-root children that have no keyboard-traversal policy of

     * their own (as will, recursively, their focus-cycle-root children).

     * <p>

     * If this Container is not a focus cycle root, the value will be

     * remembered, but will not be used or inherited by this or any other

     * Containers until this Container is made a focus cycle root.

     *

     * @see #setFocusTraversalPolicy

     * @see #getFocusTraversalPolicy

     * @since 1.4

     */

    private transient FocusTraversalPolicy focusTraversalPolicy;

    /**

     * Indicates whether this Component is the root of a focus traversal cycle.

     * Once focus enters a traversal cycle, typically it cannot leave it via

     * focus traversal unless one of the up- or down-cycle keys is pressed.

     * Normal traversal is limited to this Container, and all of this

     * Container's descendants that are not descendants of inferior focus cycle

     * roots.

     *

     * @see #setFocusCycleRoot

     * @see #isFocusCycleRoot

     * @since 1.4

     */

    private boolean focusCycleRoot = false;

    /**

     * Stores the value of focusTraversalPolicyProvider property.

     * @since 1.5

     * @see #setFocusTraversalPolicyProvider

     */

    private boolean focusTraversalPolicyProvider;

    // keeps track of the threads that are printing this component

    private transient Set printingThreads;

    // True if there is at least one thread that's printing this component

    private transient boolean printing = false;

    transient ContainerListener containerListener;

    /* HierarchyListener and HierarchyBoundsListener support */

    transient int listeningChildren;

    transient int listeningBoundsChildren;

    transient int descendantsCount;

    /* Non-opaque window support -- see Window.setLayersOpaque */

    transient Color preserveBackgroundColor = null;

    /**

     * JDK 1.1 serialVersionUID

     */

    private static final long serialVersionUID = 4613797578919906343L;

    /**

     * A constant which toggles one of the controllable behaviors

     * of <code>getMouseEventTarget</code>. It is used to specify whether

     * the method can return the Container on which it is originally called

     * in case if none of its children are the current mouse event targets.

     *

     * @see #getMouseEventTarget(int, int, boolean, boolean, boolean)

     */

    static final boolean INCLUDE_SELF = true;

    /**

     * A constant which toggles one of the controllable behaviors

     * of <code>getMouseEventTarget</code>. It is used to specify whether

     * the method should search only lightweight components.

     *

     * @see #getMouseEventTarget(int, int, boolean, boolean, boolean)

     */

    static final boolean SEARCH_HEAVYWEIGHTS = true;

    /*

     * Number of HW or LW components in this container (including

     * all descendant containers).

     */

    private transient int numOfHWComponents = 0;

    private transient int numOfLWComponents = 0;

    private static final PlatformLogger mixingLog = PlatformLogger.getLogger("java.awt.mixing.Container");

    /**

     * @serialField ncomponents                     int

     *       The number of components in this container.

     *       This value can be null.

     * @serialField component                       Component[]

     *       The components in this container.

     * @serialField layoutMgr                       LayoutManager

     *       Layout manager for this container.

     * @serialField dispatcher                      LightweightDispatcher

     *       Event router for lightweight components.  If this container

     *       is native, this dispatcher takes care of forwarding and

     *       retargeting the events to lightweight components contained

     *       (if any).

     * @serialField maxSize                         Dimension

     *       Maximum size of this Container.

     * @serialField focusCycleRoot                  boolean

     *       Indicates whether this Component is the root of a focus traversal cycle.

     *       Once focus enters a traversal cycle, typically it cannot leave it via

     *       focus traversal unless one of the up- or down-cycle keys is pressed.

     *       Normal traversal is limited to this Container, and all of this

     *       Container's descendants that are not descendants of inferior focus cycle

     *       roots.

     * @serialField containerSerializedDataVersion  int

     *       Container Serial Data Version.

     * @serialField focusTraversalPolicyProvider    boolean

     *       Stores the value of focusTraversalPolicyProvider property.

     */

    private static final ObjectStreamField[] serialPersistentFields = {

        new ObjectStreamField("ncomponents", Integer.TYPE),

        new ObjectStreamField("component", Component[].class),

        new ObjectStreamField("layoutMgr", LayoutManager.class),

        new ObjectStreamField("dispatcher", LightweightDispatcher.class),

        new ObjectStreamField("maxSize", Dimension.class),

        new ObjectStreamField("focusCycleRoot", Boolean.TYPE),

        new ObjectStreamField("containerSerializedDataVersion", Integer.TYPE),

        new ObjectStreamField("focusTraversalPolicyProvider", Boolean.TYPE),

    };

    static {

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

        Toolkit.loadLibraries();

        if (!GraphicsEnvironment.isHeadless()) {

            initIDs();

        }

    }

    /**

     * Initialize JNI field and method IDs for fields that may be

       called from C.

     */

    private static native void initIDs();

    /**

     * Constructs a new Container. Containers can be extended directly,

     * but are lightweight in this case and must be contained by a parent

     * somewhere higher up in the component tree that is native.

     * (such as Frame for example).

     */

    public Container() {

    }

    void initializeFocusTraversalKeys() {

        focusTraversalKeys = new Set[4];

    }

    /**

     * Gets the number of components in this panel.

     * <p>

     * Note: This method should be called under AWT tree lock.

     *

     * @return    the number of components in this panel.

     * @see       #getComponent

     * @since     JDK1.1

     * @see Component#getTreeLock()

     */

    public int getComponentCount() {

        return countComponents();

    }

    /**

     * @deprecated As of JDK version 1.1,

     * replaced by getComponentCount().

     */

    @Deprecated

    public int countComponents() {

        // This method is not synchronized under AWT tree lock.

        // Instead, the calling code is responsible for the

        // synchronization. See 6784816 for details.

        return component.size();

    }

    /**

     * Gets the nth component in this container.

     * <p>

     * Note: This method should be called under AWT tree lock.

     *

     * @param      n   the index of the component to get.

     * @return     the n<sup>th</sup> component in this container.

     * @exception  ArrayIndexOutOfBoundsException

     *                 if the n<sup>th</sup> value does not exist.

     * @see Component#getTreeLock()

     */

    public Component getComponent(int n) {

        // This method is not synchronized under AWT tree lock.

        // Instead, the calling code is responsible for the

        // synchronization. See 6784816 for details.

        try {

            return component.get(n);

        } catch (IndexOutOfBoundsException z) {

            throw new ArrayIndexOutOfBoundsException("No such child: " + n);

        }

    }

    /**

     * Gets all the components in this container.

     * <p>

     * Note: This method should be called under AWT tree lock.

     *

     * @return    an array of all the components in this container.

     * @see Component#getTreeLock()

     */

    public Component[] getComponents() {

        // This method is not synchronized under AWT tree lock.

        // Instead, the calling code is responsible for the

        // synchronization. See 6784816 for details.

        return getComponents_NoClientCode();

    }

    // NOTE: This method may be called by privileged threads.

    //       This functionality is implemented in a package-private method

    //       to insure that it cannot be overridden by client subclasses.

    //       DO NOT INVOKE CLIENT CODE ON THIS THREAD!

    final Component[] getComponents_NoClientCode() {

        return component.toArray(EMPTY_ARRAY);

    }

    /*

     * Wrapper for getComponents() method with a proper synchronization.

     */

    Component[] getComponentsSync() {

        synchronized (getTreeLock()) {

            return getComponents();

        }

    }

    /**

     * Determines the insets of this container, which indicate the size

     * of the container's border.

     * <p>

     * A <code>Frame</code> object, for example, has a top inset that

     * corresponds to the height of the frame's title bar.

     * @return    the insets of this container.

     * @see       Insets

     * @see       LayoutManager

     * @since     JDK1.1

     */

    public Insets getInsets() {

        return insets();

    }

    /**

     * @deprecated As of JDK version 1.1,

     * replaced by <code>getInsets()</code>.

     */

    @Deprecated

    public Insets insets() {

        ComponentPeer peer = this.peer;

        if (peer instanceof ContainerPeer) {

            ContainerPeer cpeer = (ContainerPeer)peer;

            return (Insets)cpeer.getInsets().clone();

        }

        return new Insets(0, 0, 0, 0);

    }

    /**

     * Appends the specified component to the end of this container.

     * This is a convenience method for {@link #addImpl}.

     * <p>

     * This method changes layout-related information, and therefore,

     * invalidates the component hierarchy. If the container has already been

     * displayed, the hierarchy must be validated thereafter in order to

     * display the added component.

     *

     * @param     comp   the component to be added

     * @exception NullPointerException if {@code comp} is {@code null}

     * @see #addImpl

     * @see #invalidate

     * @see #validate

     * @see javax.swing.JComponent#revalidate()

     * @return    the component argument

     */

    public Component add(Component comp) {

        addImpl(comp, null, -1);

        return comp;

    }

    /**

     * Adds the specified component to this container.

     * This is a convenience method for {@link #addImpl}.

     * <p>

     * This method is obsolete as of 1.1.  Please use the

     * method <code>add(Component, Object)</code> instead.

     * <p>

     * This method changes layout-related information, and therefore,

     * invalidates the component hierarchy. If the container has already been

     * displayed, the hierarchy must be validated thereafter in order to

     * display the added component.

     *

     * @exception NullPointerException if {@code comp} is {@code null}

     * @see #add(Component, Object)

     * @see #invalidate

     */

    public Component add(String name, Component comp) {

        addImpl(comp, name, -1);

        return comp;

    }

    /**

     * Adds the specified component to this container at the given

     * position.

     * This is a convenience method for {@link #addImpl}.

     * <p>

     * This method changes layout-related information, and therefore,

     * invalidates the component hierarchy. If the container has already been

     * displayed, the hierarchy must be validated thereafter in order to

     * display the added component.

     *

     *

     * @param     comp   the component to be added

     * @param     index    the position at which to insert the component,

     *                   or <code>-1</code> to append the component to the end

     * @exception NullPointerException if {@code comp} is {@code null}

     * @exception IllegalArgumentException if {@code index} is invalid (see

     *            {@link #addImpl} for details)

     * @return    the component <code>comp</code>

     * @see #addImpl

     * @see #remove

     * @see #invalidate

     * @see #validate

     * @see javax.swing.JComponent#revalidate()

     */

    public Component add(Component comp, int index) {

        addImpl(comp, null, index);

        return comp;

    }

    /**

     * Checks that the component

     * isn't supposed to be added into itself.

     */

    private void checkAddToSelf(Component comp){

        if (comp instanceof Container) {

            for (Container cn = this; cn != null; cn=cn.parent) {

                if (cn == comp) {

                    throw new IllegalArgumentException("adding container's parent to itself");

                }

            }

        }

    }

    /**

     * Checks that the component is not a Window instance.

     */

    private void checkNotAWindow(Component comp){

        if (comp instanceof Window) {

            throw new IllegalArgumentException("adding a window to a container");

        }

    }

    /**

     * Checks that the component comp can be added to this container

     * Checks :  index in bounds of container's size,

     * comp is not one of this container's parents,

     * and comp is not a window.

     * Comp and container must be on the same GraphicsDevice.

     * if comp is container, all sub-components must be on

     * same GraphicsDevice.

     *

     * @since 1.5

     */

    private void checkAdding(Component comp, int index) {

        checkTreeLock();

        GraphicsConfiguration thisGC = getGraphicsConfiguration();

        if (index > component.size() || index < 0) {

            throw new IllegalArgumentException("illegal component position");

        }

        if (comp.parent == this) {

            if (index == component.size()) {

                throw new IllegalArgumentException("illegal component position " +

                                                   index + " should be less then " + component.size());

            }

        }

        checkAddToSelf(comp);

        checkNotAWindow(comp);

        Window thisTopLevel = getContainingWindow();

        Window compTopLevel = comp.getContainingWindow();

        if (thisTopLevel != compTopLevel) {

            throw new IllegalArgumentException("component and container should be in the same top-level window");

        }

        if (thisGC != null) {

            comp.checkGD(thisGC.getDevice().getIDstring());

        }

    }

    /**

     * Removes component comp from this container without making unneccessary changes

     * and generating unneccessary events. This function intended to perform optimized

     * remove, for example, if newParent and current parent are the same it just changes

     * index without calling removeNotify.

     * Note: Should be called while holding treeLock