/*

 * Copyright (c) 1995, 2011, 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.awt.peer.MenuComponentPeer;

import java.awt.event.ActionEvent;

import java.io.IOException;

import java.io.ObjectInputStream;

import sun.awt.AppContext;

import sun.awt.AWTAccessor;

import javax.accessibility.*;

import java.security.AccessControlContext;

import java.security.AccessController;

/**

 * The abstract class <code>MenuComponent</code> is the superclass

 * of all menu-related components. In this respect, the class

 * <code>MenuComponent</code> is analogous to the abstract superclass

 * <code>Component</code> for AWT components.

 * <p>

 * Menu components receive and process AWT events, just as components do,

 * through the method <code>processEvent</code>.

 *

 * @author      Arthur van Hoff

 * @since       JDK1.0

 */

public abstract class MenuComponent implements java.io.Serializable {

    static {

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

        Toolkit.loadLibraries();

        if (!GraphicsEnvironment.isHeadless()) {

            initIDs();

        }

    }

    transient MenuComponentPeer peer;

    transient MenuContainer parent;

    /**

     * The <code>AppContext</code> of the <code>MenuComponent</code>.

     * This is set in the constructor and never changes.

     */

    transient AppContext appContext;

    /**

     * The menu component's font. This value can be

     * <code>null</code> at which point a default will be used.

     * This defaults to <code>null</code>.

     *

     * @serial

     * @see #setFont(Font)

     * @see #getFont()

     */

    Font font;

    /**

     * The menu component's name, which defaults to <code>null</code>.

     * @serial

     * @see #getName()

     * @see #setName(String)

     */

    private String name;

    /**

     * A variable to indicate whether a name is explicitly set.

     * If <code>true</code> the name will be set explicitly.

     * This defaults to <code>false</code>.

     * @serial

     * @see #setName(String)

     */

    private boolean nameExplicitlySet = false;

    /**

     * Defaults to <code>false</code>.

     * @serial

     * @see #dispatchEvent(AWTEvent)

     */

    boolean newEventsOnly = false;

    /*

     * The menu's AccessControlContext.

     */

    private transient volatile AccessControlContext acc =

            AccessController.getContext();

    /*

     * Returns the acc this menu component was constructed with.

     */

    final AccessControlContext getAccessControlContext() {

        if (acc == null) {

            throw new SecurityException(

                    "MenuComponent is missing AccessControlContext");

        }

        return acc;

    }

    /*

     * Internal constants for serialization.

     */

    final static String actionListenerK = Component.actionListenerK;

    final static String itemListenerK = Component.itemListenerK;

    /*

     * JDK 1.1 serialVersionUID

     */

    private static final long serialVersionUID = -4536902356223894379L;

    static {

        AWTAccessor.setMenuComponentAccessor(

            new AWTAccessor.MenuComponentAccessor() {

                public AppContext getAppContext(MenuComponent menuComp) {

                    return menuComp.appContext;

                }

                public void setAppContext(MenuComponent menuComp,

                                          AppContext appContext) {

                    menuComp.appContext = appContext;

                }

                public MenuContainer getParent(MenuComponent menuComp) {

                    return menuComp.parent;

                }

            });

    }

    /**

     * Creates a <code>MenuComponent</code>.

     * @exception HeadlessException if

     *    <code>GraphicsEnvironment.isHeadless</code>

     *    returns <code>true</code>

     * @see java.awt.GraphicsEnvironment#isHeadless

     */

    public MenuComponent() throws HeadlessException {

        GraphicsEnvironment.checkHeadless();

        appContext = AppContext.getAppContext();

    }

    /**

     * Constructs a name for this <code>MenuComponent</code>.

     * Called by <code>getName</code> when the name is <code>null</code>.

     * @return a name for this <code>MenuComponent</code>

     */

    String constructComponentName() {

        return null; // For strict compliance with prior platform versions, a MenuComponent

                     // that doesn't set its name should return null from

                     // getName()

    }

    /**

     * Gets the name of the menu component.

     * @return        the name of the menu component

     * @see           java.awt.MenuComponent#setName(java.lang.String)

     * @since         JDK1.1

     */

    public String getName() {

        if (name == null && !nameExplicitlySet) {

            synchronized(this) {

                if (name == null && !nameExplicitlySet)

                    name = constructComponentName();

            }

        }

        return name;

    }

    /**

     * Sets the name of the component to the specified string.

     * @param         name    the name of the menu component

     * @see           java.awt.MenuComponent#getName

     * @since         JDK1.1

     */

    public void setName(String name) {

        synchronized(this) {

            this.name = name;

            nameExplicitlySet = true;

        }

    }

    /**

     * Returns the parent container for this menu component.

     * @return    the menu component containing this menu component,

     *                 or <code>null</code> if this menu component

     *                 is the outermost component, the menu bar itself

     */

    public MenuContainer getParent() {

        return getParent_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 MenuContainer getParent_NoClientCode() {

        return parent;

    }

    /**

     * @deprecated As of JDK version 1.1,

     * programs should not directly manipulate peers.

     */

    @Deprecated

    public MenuComponentPeer getPeer() {

        return peer;

    }

    /**

     * Gets the font used for this menu component.

     * @return   the font used in this menu component, if there is one;

     *                  <code>null</code> otherwise

     * @see     java.awt.MenuComponent#setFont

     */

    public Font getFont() {

        Font font = this.font;

        if (font != null) {

            return font;

        }

        MenuContainer parent = this.parent;

        if (parent != null) {

            return parent.getFont();

        }

        return null;

    }

    // 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 Font getFont_NoClientCode() {

        Font font = this.font;

        if (font != null) {

            return font;

        }

        // The MenuContainer interface does not have getFont_NoClientCode()

        // and it cannot, because it must be package-private. Because of

        // this, we must manually cast classes that implement

        // MenuContainer.

        Object parent = this.parent;

        if (parent != null) {

            if (parent instanceof Component) {

                font = ((Component)parent).getFont_NoClientCode();

            } else if (parent instanceof MenuComponent) {

                font = ((MenuComponent)parent).getFont_NoClientCode();

            }

        }

        return font;

    } // getFont_NoClientCode()

    /**

     * Sets the font to be used for this menu component to the specified

     * font. This font is also used by all subcomponents of this menu

     * component, unless those subcomponents specify a different font.

     * <p>

     * Some platforms may not support setting of all font attributes

     * of a menu component; in such cases, calling <code>setFont</code>

     * will have no effect on the unsupported font attributes of this

     * menu component.  Unless subcomponents of this menu component

     * specify a different font, this font will be used by those

     * subcomponents if supported by the underlying platform.

     *

     * @param     f   the font to be set

     * @see       #getFont

     * @see       Font#getAttributes

     * @see       java.awt.font.TextAttribute

     */

    public void setFont(Font f) {

        font = f;

        //Fixed 6312943: NullPointerException in method MenuComponent.setFont(Font)

        MenuComponentPeer peer = (MenuComponentPeer)this.peer;

        if (peer != null) {

            peer.setFont(f);

        }

    }

    /**

     * Removes the menu component's peer.  The peer allows us to modify the

     * appearance of the menu component without changing the functionality of

     * the menu component.

     */

    public void removeNotify() {

        synchronized (getTreeLock()) {

            MenuComponentPeer p = (MenuComponentPeer)this.peer;

            if (p != null) {

                Toolkit.getEventQueue().removeSourceEvents(this, true);

                this.peer = null;

                p.dispose();

            }

        }

    }

    /**

     * Posts the specified event to the menu.

     * This method is part of the Java 1.0 event system

     * and it is maintained only for backwards compatibility.

     * Its use is discouraged, and it may not be supported

     * in the future.

     * @param evt the event which is to take place

     * @deprecated As of JDK version 1.1, replaced by {@link

     * #dispatchEvent(AWTEvent) dispatchEvent}.

     */

    @Deprecated

    public boolean postEvent(Event evt) {

        MenuContainer parent = this.parent;

        if (parent != null) {

            parent.postEvent(evt);

        }

        return false;

    }

    /**

     * Delivers an event to this component or one of its sub components.

     * @param e the event

     */

    public final void dispatchEvent(AWTEvent e) {

        dispatchEventImpl(e);

    }

    void dispatchEventImpl(AWTEvent e) {

        EventQueue.setCurrentEventAndMostRecentTime(e);

        Toolkit.getDefaultToolkit().notifyAWTEventListeners(e);

        if (newEventsOnly ||

            (parent != null && parent instanceof MenuComponent &&

             ((MenuComponent)parent).newEventsOnly)) {

            if (eventEnabled(e)) {

                processEvent(e);

            } else if (e instanceof ActionEvent && parent != null) {

                e.setSource(parent);

                ((MenuComponent)parent).dispatchEvent(e);

            }

        } else { // backward compatibility

            Event olde = e.convertToOld();

            if (olde != null) {

                postEvent(olde);

            }

        }

    }

    // REMIND: remove when filtering is done at lower level

    boolean eventEnabled(AWTEvent e) {

        return false;

    }

    /**

     * Processes events occurring on this menu component.

     * <p>Note that if the event parameter is <code>null</code>

     * the behavior is unspecified and may result in an

     * exception.

     *

     * @param e the event

     * @since JDK1.1

     */

    protected void processEvent(AWTEvent e) {

    }

    /**

     * Returns a string representing the state of this

     * <code>MenuComponent</code>. This method is intended to be used

     * only for debugging purposes, and the content and format of the

     * returned string may vary between implementations. The returned

     * string may be empty but may not be <code>null</code>.

     *

     * @return     the parameter string of this menu component

     */

    protected String paramString() {

        String thisName = getName();

        return (thisName != null? thisName : "");

    }

    /**

     * Returns a representation of this menu component as a string.

     * @return  a string representation of this menu component

     */

    public String toString() {

        return getClass().getName() + "[" + paramString() + "]";

    }

    /**

     * Gets this component's locking object (the object that owns the thread

     * sychronization monitor) for AWT component-tree and layout

     * operations.

     * @return this component's locking object

     */

    protected final Object getTreeLock() {

        return Component.LOCK;

    }

    /**

     * Reads the menu component from an object input stream.

     *

     * @param s the <code>ObjectInputStream</code> to read

     * @exception HeadlessException if

     *   <code>GraphicsEnvironment.isHeadless</code> returns

     *   <code>true</code>

     * @serial

     * @see java.awt.GraphicsEnvironment#isHeadless

     */

    private void readObject(ObjectInputStream s)

        throws ClassNotFoundException, IOException, HeadlessException

    {

        GraphicsEnvironment.checkHeadless();

        acc = AccessController.getContext();

        s.defaultReadObject();

        appContext = AppContext.getAppContext();

    }

    /**

     * Initialize JNI field and method IDs.

     */

    private static native void initIDs();

    /*

     * --- Accessibility Support ---

     *

     *  MenuComponent will contain all of the methods in interface Accessible,

     *  though it won't actually implement the interface - that will be up

     *  to the individual objects which extend MenuComponent.

     */

    AccessibleContext accessibleContext = null;

    /**

     * Gets the <code>AccessibleContext</code> associated with

     * this <code>MenuComponent</code>.

     *

     * The method implemented by this base class returns <code>null</code>.

     * Classes that extend <code>MenuComponent</code>

     * should implement this method to return the

     * <code>AccessibleContext</code> associated with the subclass.

     *

     * @return the <code>AccessibleContext</code> of this

     *     <code>MenuComponent</code>

     * @since 1.3

     */

    public AccessibleContext getAccessibleContext() {

        return accessibleContext;

    }

    /**

     * Inner class of <code>MenuComponent</code> used to provide

     * default support for accessibility.  This class is not meant

     * to be used directly by application developers, but is instead

     * meant only to be subclassed by menu component developers.

     * <p>

     * The class used to obtain the accessible role for this object.

     * @since 1.3

     */

    protected abstract class AccessibleAWTMenuComponent

        extends AccessibleContext

        implements java.io.Serializable, AccessibleComponent,

                   AccessibleSelection

    {

        /*

         * JDK 1.3 serialVersionUID

         */

        private static final long serialVersionUID = -4269533416223798698L;

        /**

         * Although the class is abstract, this should be called by

         * all sub-classes.

         */

        protected AccessibleAWTMenuComponent() {

        }

        // AccessibleContext methods

        //

        /**

         * Gets the <code>AccessibleSelection</code> associated with this

         * object which allows its <code>Accessible</code> children to be selected.

         *

         * @return <code>AccessibleSelection</code> if supported by object;

         *      else return <code>null</code>

         * @see AccessibleSelection

         */

        public AccessibleSelection getAccessibleSelection() {

            return this;

        }

        /**

         * Gets the accessible name of this object.  This should almost never

         * return <code>java.awt.MenuComponent.getName</code>, as that

         * generally isn't a localized name, and doesn't have meaning for the

         * user.  If the object is fundamentally a text object (e.g. a menu item), the

         * accessible name should be the text of the object (e.g. "save").

         * If the object has a tooltip, the tooltip text may also be an

         * appropriate String to return.

         *

         * @return the localized name of the object -- can be <code>null</code>

         *         if this object does not have a name

         * @see AccessibleContext#setAccessibleName

         */

        public String getAccessibleName() {

            return accessibleName;

        }