/*

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

import java.io.PrintStream;

import java.io.PrintWriter;

import java.util.Vector;

import java.util.Locale;

import java.util.EventListener;

import java.util.Iterator;

import java.util.HashSet;

import java.util.Map;

import java.util.Set;

import java.util.Collections;

import java.awt.peer.ComponentPeer;

import java.awt.peer.ContainerPeer;

import java.awt.peer.LightweightPeer;

import java.awt.image.BufferStrategy;

import java.awt.image.ImageObserver;

import java.awt.image.ImageProducer;

import java.awt.image.ColorModel;

import java.awt.image.VolatileImage;

import java.awt.event.*;

import java.io.Serializable;

import java.io.ObjectOutputStream;

import java.io.ObjectInputStream;

import java.io.IOException;

import java.beans.PropertyChangeListener;

import java.beans.PropertyChangeSupport;

import java.awt.event.InputMethodListener;

import java.awt.event.InputMethodEvent;

import java.awt.im.InputContext;

import java.awt.im.InputMethodRequests;

import java.awt.dnd.DropTarget;

import java.lang.reflect.InvocationTargetException;

import java.lang.reflect.Method;

import java.security.AccessController;

import java.security.PrivilegedAction;

import javax.accessibility.*;

import java.util.logging.*;

import java.applet.Applet;

import sun.security.action.GetPropertyAction;

import sun.awt.AppContext;

import sun.awt.ConstrainableGraphics;

import sun.awt.SubRegionShowable;

import sun.awt.WindowClosingListener;

import sun.awt.CausedFocusEvent;

import sun.awt.EmbeddedFrame;

import sun.awt.dnd.SunDropTargetEvent;

import sun.awt.im.CompositionArea;

import sun.java2d.SunGraphics2D;

import sun.java2d.pipe.Region;

import sun.awt.RequestFocusController;

/**

 * A <em>component</em> is an object having a graphical representation

 * that can be displayed on the screen and that can interact with the

 * user. Examples of components are the buttons, checkboxes, and scrollbars

 * of a typical graphical user interface. <p>

 * The <code>Component</code> class is the abstract superclass of

 * the nonmenu-related Abstract Window Toolkit components. Class

 * <code>Component</code> can also be extended directly to create a

 * lightweight component. A lightweight component is a component that is

 * not associated with a native opaque window.

 * <p>

 * <h3>Serialization</h3>

 * It is important to note that only AWT listeners which conform

 * to the <code>Serializable</code> protocol will be saved when

 * the object is stored.  If an AWT object has listeners that

 * aren't marked serializable, they will be dropped at

 * <code>writeObject</code> time.  Developers will need, as always,

 * to consider the implications of making an object serializable.

 * One situation to watch out for is this:

 * <pre>

 *    import java.awt.*;

 *    import java.awt.event.*;

 *    import java.io.Serializable;

 *

 *    class MyApp implements ActionListener, Serializable

 *    {

 *        BigObjectThatShouldNotBeSerializedWithAButton bigOne;

 *        Button aButton = new Button();

 *

 *        MyApp()

 *        {

 *            // Oops, now aButton has a listener with a reference

 *            // to bigOne!

 *            aButton.addActionListener(this);

 *        }

 *

 *        public void actionPerformed(ActionEvent e)

 *        {

 *            System.out.println("Hello There");

 *        }

 *    }

 * </pre>

 * In this example, serializing <code>aButton</code> by itself

 * will cause <code>MyApp</code> and everything it refers to

 * to be serialized as well.  The problem is that the listener

 * is serializable by coincidence, not by design.  To separate

 * the decisions about <code>MyApp</code> and the

 * <code>ActionListener</code> being serializable one can use a

 * nested class, as in the following example:

 * <pre>

 *    import java.awt.*;

 *    import java.awt.event.*;

 *    import java.io.Serializable;

 *

 *    class MyApp java.io.Serializable

 *    {

 *         BigObjectThatShouldNotBeSerializedWithAButton bigOne;

 *         Button aButton = new Button();

 *

 *         static class MyActionListener implements ActionListener

 *         {

 *             public void actionPerformed(ActionEvent e)

 *             {

 *                 System.out.println("Hello There");

 *             }

 *         }

 *

 *         MyApp()

 *         {

 *             aButton.addActionListener(new MyActionListener());

 *         }

 *    }

 * </pre>

 * <p>

 * <b>Note</b>: For more information on the paint mechanisms utilitized

 * by AWT and Swing, including information on how to write the most

 * efficient painting code, see

 * <a href="http://java.sun.com/products/jfc/tsc/articles/painting/index.html">Painting in AWT and Swing</a>.

 * <p>

 * 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

 */

public abstract class Component implements ImageObserver, MenuContainer,

                                           Serializable

{

    private static final Logger log = Logger.getLogger("java.awt.Component");

    private static final Logger eventLog = Logger.getLogger("java.awt.event.Component");

    private static final Logger focusLog = Logger.getLogger("java.awt.focus.Component");

    private static final Logger mixingLog = Logger.getLogger("java.awt.mixing.Component");

    /**

     * The peer of the component. The peer implements the component's

     * behavior. The peer is set when the <code>Component</code> is

     * added to a container that also is a peer.

     * @see #addNotify

     * @see #removeNotify

     */

    transient ComponentPeer peer;

    /**

     * The parent of the object. It may be <code>null</code>

     * for top-level components.

     * @see #getParent

     */

    transient Container parent;

    /**

     * The <code>AppContext</code> of the component. Applets/Plugin may

     * change the AppContext.

     */

    transient AppContext appContext;

    /**

     * The x position of the component in the parent's coordinate system.

     *

     * @serial

     * @see #getLocation

     */

    int x;

    /**

     * The y position of the component in the parent's coordinate system.

     *

     * @serial

     * @see #getLocation

     */

    int y;

    /**

     * The width of the component.

     *

     * @serial

     * @see #getSize

     */

    int width;

    /**

     * The height of the component.

     *

     * @serial

     * @see #getSize

     */

    int height;

    /**

     * The foreground color for this component.

     * <code>foreground</code> can be <code>null</code>.

     *

     * @serial

     * @see #getForeground

     * @see #setForeground

     */

    Color       foreground;

    /**

     * The background color for this component.

     * <code>background</code> can be <code>null</code>.

     *

     * @serial

     * @see #getBackground

     * @see #setBackground

     */

    Color       background;

    /**

     * The font used by this component.

     * The <code>font</code> can be <code>null</code>.

     *

     * @serial

     * @see #getFont

     * @see #setFont

     */

    Font        font;

    /**

     * The font which the peer is currently using.

     * (<code>null</code> if no peer exists.)

     */

    Font        peerFont;

    /**

     * The cursor displayed when pointer is over this component.

     * This value can be <code>null</code>.

     *

     * @serial

     * @see #getCursor

     * @see #setCursor

     */

    Cursor      cursor;

    /**

     * The locale for the component.

     *

     * @serial

     * @see #getLocale

     * @see #setLocale

     */

    Locale      locale;

    /**

     * A reference to a <code>GraphicsConfiguration</code> object

     * used to describe the characteristics of a graphics

     * destination.

     * This value can be <code>null</code>.

     *

     * @since 1.3

     * @serial

     * @see GraphicsConfiguration

     * @see #getGraphicsConfiguration

     */

    transient GraphicsConfiguration graphicsConfig = null;

    /**

     * A reference to a <code>BufferStrategy</code> object

     * used to manipulate the buffers on this component.

     *

     * @since 1.4

     * @see java.awt.image.BufferStrategy

     * @see #getBufferStrategy()

     */

    transient BufferStrategy bufferStrategy = null;

    /**

     * True when the object should ignore all repaint events.

     *

     * @since 1.4

     * @serial

     * @see #setIgnoreRepaint

     * @see #getIgnoreRepaint

     */

    boolean ignoreRepaint = false;

    /**

     * True when the object is visible. An object that is not

     * visible is not drawn on the screen.

     *

     * @serial

     * @see #isVisible

     * @see #setVisible

     */

    boolean visible = true;

    /**

     * True when the object is enabled. An object that is not

     * enabled does not interact with the user.

     *

     * @serial

     * @see #isEnabled

     * @see #setEnabled

     */

    boolean enabled = true;

    /**

     * True when the object is valid. An invalid object needs to

     * be layed out. This flag is set to false when the object

     * size is changed.

     *

     * @serial

     * @see #isValid

     * @see #validate

     * @see #invalidate

     */

    volatile boolean valid = false;

    /**

     * The <code>DropTarget</code> associated with this component.

     *

     * @since 1.2

     * @serial

     * @see #setDropTarget

     * @see #getDropTarget

     */

    DropTarget dropTarget;

    /**

     * @serial

     * @see #add

     */

    Vector popups;

    /**

     * A component's name.

     * This field can be <code>null</code>.

     *

     * @serial

     * @see #getName

     * @see #setName(String)

     */

    private String name;

    /**

     * A bool to determine whether the name has

     * been set explicitly. <code>nameExplicitlySet</code> will

     * be false if the name has not been set and

     * true if it has.

     *

     * @serial

     * @see #getName

     * @see #setName(String)

     */

    private boolean nameExplicitlySet = false;

    /**

     * Indicates whether this Component can be focused.

     *

     * @serial

     * @see #setFocusable

     * @see #isFocusable

     * @since 1.4

     */

    private boolean focusable = true;

    private static final int FOCUS_TRAVERSABLE_UNKNOWN = 0;

    private static final int FOCUS_TRAVERSABLE_DEFAULT = 1;

    private static final int FOCUS_TRAVERSABLE_SET = 2;

    /**

     * Tracks whether this Component is relying on default focus travesability.

     *

     * @serial

     * @since 1.4

     */

    private int isFocusTraversableOverridden = FOCUS_TRAVERSABLE_UNKNOWN;

    /**

     * The focus traversal keys. These keys will generate focus traversal

     * behavior for Components for which focus traversal keys are enabled. If a

     * value of null is specified for a traversal key, this Component inherits

     * that traversal key from its parent. If all ancestors of this Component

     * have null specified for that traversal key, then the current

     * KeyboardFocusManager's default traversal key is used.

     *

     * @serial

     * @see #setFocusTraversalKeys

     * @see #getFocusTraversalKeys

     * @since 1.4

     */

    Set[] focusTraversalKeys;

    private static final String[] focusTraversalKeyPropertyNames = {

        "forwardFocusTraversalKeys",

        "backwardFocusTraversalKeys",

        "upCycleFocusTraversalKeys",

        "downCycleFocusTraversalKeys"

    };

    /**

     * Indicates whether focus traversal keys are enabled for this Component.

     * Components for which focus traversal keys are disabled receive key

     * events for focus traversal keys. Components for which focus traversal

     * keys are enabled do not see these events; instead, the events are

     * automatically converted to traversal operations.

     *

     * @serial

     * @see #setFocusTraversalKeysEnabled

     * @see #getFocusTraversalKeysEnabled

     * @since 1.4

     */

    private boolean focusTraversalKeysEnabled = true;

    /**

     * The locking object for AWT component-tree and layout operations.

     *

     * @see #getTreeLock

     */

    static final Object LOCK = new AWTTreeLock();

    static class AWTTreeLock {}

    /**

     * Minimum size.

     * (This field perhaps should have been transient).

     *

     * @serial

     */

    Dimension minSize;

    /**

     * Whether or not setMinimumSize has been invoked with a non-null value.

     */

    boolean minSizeSet;

    /**

     * Preferred size.

     * (This field perhaps should have been transient).

     *

     * @serial

     */

    Dimension prefSize;

    /**

     * Whether or not setPreferredSize has been invoked with a non-null value.

     */

    boolean prefSizeSet;

    /**

     * Maximum size

     *

     * @serial

     */

    Dimension maxSize;

    /**

     * Whether or not setMaximumSize has been invoked with a non-null value.

     */

    boolean maxSizeSet;

    /**

     * The orientation for this component.

     * @see #getComponentOrientation

     * @see #setComponentOrientation

     */

    transient ComponentOrientation componentOrientation

    = ComponentOrientation.UNKNOWN;

    /**

     * <code>newEventsOnly</code> will be true if the event is

     * one of the event types enabled for the component.

     * It will then allow for normal processing to

     * continue.  If it is false the event is passed

     * to the component's parent and up the ancestor

     * tree until the event has been consumed.

     *

     * @serial

     * @see #dispatchEvent

     */

    boolean newEventsOnly = false;

    transient ComponentListener componentListener;

    transient FocusListener focusListener;

    transient HierarchyListener hierarchyListener;

    transient HierarchyBoundsListener hierarchyBoundsListener;

    transient KeyListener keyListener;

    transient MouseListener mouseListener;

    transient MouseMotionListener mouseMotionListener;

    transient MouseWheelListener mouseWheelListener;

    transient InputMethodListener inputMethodListener;

    transient RuntimeException windowClosingException = null;

    /** Internal, constants for serialization */

    final static String actionListenerK = "actionL";

    final static String adjustmentListenerK = "adjustmentL";

    final static String componentListenerK = "componentL";

    final static String containerListenerK = "containerL";