/*

 * Copyright 2000-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.awt.event.FocusEvent;

import java.awt.event.InputEvent;

import java.awt.event.KeyEvent;

import java.awt.event.WindowEvent;

import java.awt.peer.KeyboardFocusManagerPeer;

import java.awt.peer.LightweightPeer;

import java.beans.PropertyChangeListener;

import java.beans.PropertyChangeSupport;

import java.beans.PropertyVetoException;

import java.beans.VetoableChangeListener;

import java.beans.VetoableChangeSupport;

import java.lang.ref.WeakReference;

import java.lang.reflect.Field;

import java.security.AccessController;

import java.security.PrivilegedAction;

import java.util.Collections;

import java.util.HashSet;

import java.util.Iterator;

import java.util.LinkedList;

import java.util.Set;

import java.util.StringTokenizer;

import java.util.WeakHashMap;

import java.util.logging.Level;

import java.util.logging.Logger;

import sun.awt.AppContext;

import sun.awt.HeadlessToolkit;

import sun.awt.SunToolkit;

import sun.awt.CausedFocusEvent;

import sun.awt.KeyboardFocusManagerPeerProvider;

/**

 * The KeyboardFocusManager is responsible for managing the active and focused

 * Windows, and the current focus owner. The focus owner is defined as the

 * Component in an application that will typically receive all KeyEvents

 * generated by the user. The focused Window is the Window that is, or

 * contains, the focus owner. Only a Frame or a Dialog can be the active

 * Window. The native windowing system may denote the active Window or its

 * children with special decorations, such as a highlighted title bar. The

 * active Window is always either the focused Window, or the first Frame or

 * Dialog that is an owner of the focused Window.

 * <p>

 * The KeyboardFocusManager is both a centralized location for client code to

 * query for the focus owner and initiate focus changes, and an event

 * dispatcher for all FocusEvents, WindowEvents related to focus, and

 * KeyEvents.

 * <p>

 * Some browsers partition applets in different code bases into separate

 * contexts, and establish walls between these contexts. In such a scenario,

 * there will be one KeyboardFocusManager per context. Other browsers place all

 * applets into the same context, implying that there will be only a single,

 * global KeyboardFocusManager for all applets. This behavior is

 * implementation-dependent. Consult your browser's documentation for more

 * information. No matter how many contexts there may be, however, there can

 * never be more than one focus owner, focused Window, or active Window, per

 * ClassLoader.

 * <p>

 * Please 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 David Mendenhall

 *

 * @see Window

 * @see Frame

 * @see Dialog

 * @see java.awt.event.FocusEvent

 * @see java.awt.event.WindowEvent

 * @see java.awt.event.KeyEvent

 * @since 1.4

 */

public abstract class KeyboardFocusManager

    implements KeyEventDispatcher, KeyEventPostProcessor

{

    // Shared focus engine logger

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

    static {

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

        Toolkit.loadLibraries();

        if (!GraphicsEnvironment.isHeadless()) {

            initIDs();

        }

    }

    transient KeyboardFocusManagerPeer peer;

    /**

     * Initialize JNI field and method IDs

     */

    private static native void initIDs();

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

    /**

     * The identifier for the Forward focus traversal keys.

     *

     * @see #setDefaultFocusTraversalKeys

     * @see #getDefaultFocusTraversalKeys

     * @see Component#setFocusTraversalKeys

     * @see Component#getFocusTraversalKeys

     */

    public static final int FORWARD_TRAVERSAL_KEYS = 0;

    /**

     * The identifier for the Backward focus traversal keys.

     *

     * @see #setDefaultFocusTraversalKeys

     * @see #getDefaultFocusTraversalKeys

     * @see Component#setFocusTraversalKeys

     * @see Component#getFocusTraversalKeys

     */

    public static final int BACKWARD_TRAVERSAL_KEYS = 1;

    /**

     * The identifier for the Up Cycle focus traversal keys.

     *

     * @see #setDefaultFocusTraversalKeys

     * @see #getDefaultFocusTraversalKeys

     * @see Component#setFocusTraversalKeys

     * @see Component#getFocusTraversalKeys

     */

    public static final int UP_CYCLE_TRAVERSAL_KEYS = 2;

    /**

     * The identifier for the Down Cycle focus traversal keys.

     *

     * @see #setDefaultFocusTraversalKeys

     * @see #getDefaultFocusTraversalKeys

     * @see Component#setFocusTraversalKeys

     * @see Component#getFocusTraversalKeys

     */

    public static final int DOWN_CYCLE_TRAVERSAL_KEYS = 3;

    static final int TRAVERSAL_KEY_LENGTH = DOWN_CYCLE_TRAVERSAL_KEYS + 1;

    /**

     * Returns the current KeyboardFocusManager instance for the calling

     * thread's context.

     *

     * @return this thread's context's KeyboardFocusManager

     * @see #setCurrentKeyboardFocusManager

     */

    public static KeyboardFocusManager getCurrentKeyboardFocusManager() {

        return getCurrentKeyboardFocusManager(AppContext.getAppContext());

    }

    synchronized static KeyboardFocusManager

        getCurrentKeyboardFocusManager(AppContext appcontext)

    {

        KeyboardFocusManager manager = (KeyboardFocusManager)

            appcontext.get(KeyboardFocusManager.class);

        if (manager == null) {

            manager = new DefaultKeyboardFocusManager();

            appcontext.put(KeyboardFocusManager.class, manager);

        }

        return manager;

    }

    /**

     * Sets the current KeyboardFocusManager instance for the calling thread's

     * context. If null is specified, then the current KeyboardFocusManager

     * is replaced with a new instance of DefaultKeyboardFocusManager.

     * <p>

     * If a SecurityManager is installed, the calling thread must be granted

     * the AWTPermission "replaceKeyboardFocusManager" in order to replace the

     * the current KeyboardFocusManager. If this permission is not granted,

     * this method will throw a SecurityException, and the current

     * KeyboardFocusManager will be unchanged.

     *

     * @param newManager the new KeyboardFocusManager for this thread's context

     * @see #getCurrentKeyboardFocusManager

     * @see DefaultKeyboardFocusManager

     * @throws SecurityException if the calling thread does not have permission

     *         to replace the current KeyboardFocusManager

     */

    public static void setCurrentKeyboardFocusManager(

        KeyboardFocusManager newManager) throws SecurityException

    {

        SecurityManager security = System.getSecurityManager();

        if (security != null) {

            if (replaceKeyboardFocusManagerPermission == null) {

                replaceKeyboardFocusManagerPermission =

                    new AWTPermission("replaceKeyboardFocusManager");

            }

            security.

                checkPermission(replaceKeyboardFocusManagerPermission);

        }

        KeyboardFocusManager oldManager = null;

        synchronized (KeyboardFocusManager.class) {

            AppContext appcontext = AppContext.getAppContext();

            if (newManager != null) {

                oldManager = getCurrentKeyboardFocusManager(appcontext);

                appcontext.put(KeyboardFocusManager.class, newManager);

            } else {

                oldManager = getCurrentKeyboardFocusManager(appcontext);

                appcontext.remove(KeyboardFocusManager.class);

            }

        }

        if (oldManager != null) {

            oldManager.firePropertyChange("managingFocus",

                                          Boolean.TRUE,

                                          Boolean.FALSE);

        }

        if (newManager != null) {

            newManager.firePropertyChange("managingFocus",

                                          Boolean.FALSE,

                                          Boolean.TRUE);

        }

    }

    /**

     * The Component in an application that will typically receive all

     * KeyEvents generated by the user.

     */

    private static Component focusOwner;

    /**

     * The Component in an application that will regain focus when an

     * outstanding temporary focus transfer has completed, or the focus owner,

     * if no outstanding temporary transfer exists.

     */

    private static Component permanentFocusOwner;

    /**

     * The Window which is, or contains, the focus owner.

     */

    private static Window focusedWindow;

    /**

     * Only a Frame or a Dialog can be the active Window. The native windowing

     * system may denote the active Window with a special decoration, such as a

     * highlighted title bar. The active Window is always either the focused

     * Window, or the first Frame or Dialog which is an owner of the focused

     * Window.

     */

    private static Window activeWindow;

    /**

     * The default FocusTraversalPolicy for all Windows that have no policy of

     * their own set. If those Windows have focus-cycle-root children that have

     * no keyboard-traversal policy of their own, then those children will also

     * inherit this policy (as will, recursively, their focus-cycle-root

     * children).

     */

    private FocusTraversalPolicy defaultPolicy =

        new DefaultFocusTraversalPolicy();

    /**

     * The bound property names of each focus traversal key.

     */

    private static final String[] defaultFocusTraversalKeyPropertyNames = {

        "forwardDefaultFocusTraversalKeys",

        "backwardDefaultFocusTraversalKeys",

        "upCycleDefaultFocusTraversalKeys",

        "downCycleDefaultFocusTraversalKeys"

    };

    /**

     * The default strokes for initializing the default focus traversal keys.

     */

    private static final AWTKeyStroke[][] defaultFocusTraversalKeyStrokes = {

        {

            AWTKeyStroke.getAWTKeyStroke(KeyEvent.VK_TAB, 0, false),

            AWTKeyStroke.getAWTKeyStroke(KeyEvent.VK_TAB, InputEvent.CTRL_DOWN_MASK | InputEvent.CTRL_MASK, false),

        },

        {

            AWTKeyStroke.getAWTKeyStroke(KeyEvent.VK_TAB, InputEvent.SHIFT_DOWN_MASK | InputEvent.SHIFT_MASK, false),

            AWTKeyStroke.getAWTKeyStroke(KeyEvent.VK_TAB,

                                         InputEvent.SHIFT_DOWN_MASK | InputEvent.SHIFT_MASK | InputEvent.CTRL_DOWN_MASK | InputEvent.CTRL_MASK,

                                         false),

        },

        {},

        {},

      };

    /**

     * The default focus traversal keys. Each array of traversal keys will be

     * in effect on all Windows that have no such array of their own explicitly

     * set. Each array will also be inherited, recursively, by any child

     * Component of those Windows that has no such array of its own explicitly

     * set.

     */

    private Set[] defaultFocusTraversalKeys = new Set[4];

    /**

     * The current focus cycle root. If the focus owner is itself a focus cycle

     * root, then it may be ambiguous as to which Components represent the next

     * and previous Components to focus during normal focus traversal. In that

     * case, the current focus cycle root is used to differentiate among the

     * possibilities.

     */

    private static Container currentFocusCycleRoot;

    /**

     * A description of any VetoableChangeListeners which have been registered.

     */

    private VetoableChangeSupport vetoableSupport;

    /**

     * A description of any PropertyChangeListeners which have been registered.

     */

    private PropertyChangeSupport changeSupport;

    /**

     * This KeyboardFocusManager's KeyEventDispatcher chain. The List does not

     * include this KeyboardFocusManager unless it was explicitly re-registered

     * via a call to <code>addKeyEventDispatcher</code>. If no other

     * KeyEventDispatchers are registered, this field may be null or refer to

     * a List of length 0.

     */

    private java.util.LinkedList keyEventDispatchers;

    /**

     * This KeyboardFocusManager's KeyEventPostProcessor chain. The List does

     * not include this KeyboardFocusManager unless it was explicitly

     * re-registered via a call to <code>addKeyEventPostProcessor</code>.

     * If no other KeyEventPostProcessors are registered, this field may be

     * null or refer to a List of length 0.

     */

    private java.util.LinkedList keyEventPostProcessors;

    /**

     * Maps Windows to those Windows' most recent focus owners.

     */

    private static java.util.Map mostRecentFocusOwners = new WeakHashMap();

    /**

     * Error String for initializing SecurityExceptions.

     */

    private static final String notPrivileged = "this KeyboardFocusManager is not installed in the current thread's context";

    /**

     * We cache the permission used to verify that the calling thread is

     * permitted to access the global focus state.

     */

    private static AWTPermission replaceKeyboardFocusManagerPermission;

    /*

     * SequencedEvent which is currently dispatched in AppContext.

     */

    transient SequencedEvent currentSequencedEvent = null;

    final void setCurrentSequencedEvent(SequencedEvent current) {

        synchronized (SequencedEvent.class) {

            assert(current == null || currentSequencedEvent == null);

            currentSequencedEvent = current;

        }

    }

    final SequencedEvent getCurrentSequencedEvent() {

        synchronized (SequencedEvent.class) {

            return currentSequencedEvent;

        }

    }

    static Set initFocusTraversalKeysSet(String value, Set targetSet) {

        StringTokenizer tokens = new StringTokenizer(value, ",");

        while (tokens.hasMoreTokens()) {

            targetSet.add(AWTKeyStroke.getAWTKeyStroke(tokens.nextToken()));

        }

        return (targetSet.isEmpty())

            ? Collections.EMPTY_SET

            : Collections.unmodifiableSet(targetSet);

    }

    /**

     * Initializes a KeyboardFocusManager.

     */

    public KeyboardFocusManager() {

        for (int i = 0; i < TRAVERSAL_KEY_LENGTH; i++) {

            Set work_set = new HashSet();

            for (int j = 0; j < defaultFocusTraversalKeyStrokes[i].length; j++) {

                work_set.add(defaultFocusTraversalKeyStrokes[i][j]);

            }

            defaultFocusTraversalKeys[i] = (work_set.isEmpty())

                ? Collections.EMPTY_SET

                : Collections.unmodifiableSet(work_set);

        }

        initPeer();

    }

    private void initPeer() {

        Toolkit tk = Toolkit.getDefaultToolkit();

        KeyboardFocusManagerPeerProvider peerProvider = (KeyboardFocusManagerPeerProvider)tk;

        peer = peerProvider.createKeyboardFocusManagerPeer(this);

    }

    /**

     * Returns the focus owner, if the focus owner is in the same context as

     * the calling thread. The focus owner is defined as the Component in an

     * application that will typically receive all KeyEvents generated by the

     * user. KeyEvents which map to the focus owner's focus traversal keys will

     * not be delivered if focus traversal keys are enabled for the focus

     * owner. In addition, KeyEventDispatchers may retarget or consume

     * KeyEvents before they reach the focus owner.

     *

     * @return the focus owner, or null if the focus owner is not a member of

     *         the calling thread's context

     * @see #getGlobalFocusOwner

     * @see #setGlobalFocusOwner

     */

    public Component getFocusOwner() {

        synchronized (KeyboardFocusManager.class) {

            if (focusOwner == null) {

                return null;

            }

            return (focusOwner.appContext == AppContext.getAppContext())

                ? focusOwner

                : null;

        }

    }

    /**

     * Returns the focus owner, even if the calling thread is in a different

     * context than the focus owner. The focus owner is defined as the

     * Component in an application that will typically receive all KeyEvents

     * generated by the user. KeyEvents which map to the focus owner's focus

     * traversal keys will not be delivered if focus traversal keys are enabled

     * for the focus owner. In addition, KeyEventDispatchers may retarget or

     * consume KeyEvents before they reach the focus owner.

     * <p>

     * This method will throw a SecurityException if this KeyboardFocusManager

     * is not the current KeyboardFocusManager for the calling thread's

     * context.

     *

     * @return the focus owner

     * @see #getFocusOwner

     * @see #setGlobalFocusOwner

     * @throws SecurityException if this KeyboardFocusManager is not the

     *         current KeyboardFocusManager for the calling thread's context

     */

    protected Component getGlobalFocusOwner() throws SecurityException {

        synchronized (KeyboardFocusManager.class) {

            if (this == getCurrentKeyboardFocusManager()) {

                return focusOwner;

            } else {

                if (focusLog.isLoggable(Level.FINER)) {

                    focusLog.log(Level.FINER, "This manager is " + this + ", current is " + getCurrentKeyboardFocusManager());

                }

                throw new SecurityException(notPrivileged);

            }

        }

    }

    /**

     * Sets the focus owner. The operation will be cancelled if the Component

     * is not focusable. The focus owner is defined as the Component in an

     * application that will typically receive all KeyEvents generated by the

     * user. KeyEvents which map to the focus owner's focus traversal keys will

     * not be delivered if focus traversal keys are enabled for the focus

     * owner. In addition, KeyEventDispatchers may retarget or consume

     * KeyEvents before they reach the focus owner.

     * <p>

     * This method does not actually set the focus to the specified Component.

     * It merely stores the value to be subsequently returned by

     * <code>getFocusOwner()</code>. Use <code>Component.requestFocus()</code>

     * or <code>Component.requestFocusInWindow()</code> to change the focus

     * owner, subject to platform limitations.

     *

     * @param focusOwner the focus owner

     * @see #getFocusOwner

     * @see #getGlobalFocusOwner

     * @see Component#requestFocus()

     * @see Component#requestFocusInWindow()

     * @see Component#isFocusable

     * @beaninfo

     *       bound: true

     */

    protected void setGlobalFocusOwner(Component focusOwner) {

        Component oldFocusOwner = null;

        boolean shouldFire = false;

        if (focusOwner == null || focusOwner.isFocusable()) {

            synchronized (KeyboardFocusManager.class) {

                oldFocusOwner = getFocusOwner();

                try {

                    fireVetoableChange("focusOwner", oldFocusOwner,

                                       focusOwner);

                } catch (PropertyVetoException e) {

                    // rejected

                    return;

                }

                KeyboardFocusManager.focusOwner = focusOwner;