Java > Open Source Codes > java > awt > KeyboardFocusManager


1 /*
2  * @(#)KeyboardFocusManager.java 1.66 07/03/13
3  *
4  * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */
7 package java.awt;
8
9 import java.awt.event.FocusEvent ;
10 import java.awt.event.InputEvent ;
11 import java.awt.event.KeyEvent ;
12 import java.awt.event.WindowEvent ;
13
14 import java.awt.peer.LightweightPeer;
15 import java.awt.peer.WindowPeer;
16 import java.beans.*;
17 import java.util.Set ;
18 import java.util.HashSet ;
19 import java.util.Collections ;
20 import java.util.Iterator ;
21 import java.util.LinkedList ;
22 import java.util.ListIterator ;
23 import java.util.StringTokenizer ;
24 import java.util.WeakHashMap ;
25 import java.lang.ref.WeakReference ;
26 import sun.awt.AppContext;
27 import sun.awt.DebugHelper;
28 import sun.awt.SunToolkit;
29 import sun.awt.HeadlessToolkit;
30 import java.util.logging.*;
31 import java.awt.peer.KeyboardFocusManagerPeer;
32 import java.lang.reflect.*;
33 import java.security.AccessController ;
34 import java.security.PrivilegedAction ;
35
36 /**
37  * The KeyboardFocusManager is responsible for managing the active and focused
38  * Windows, and the current focus owner. The focus owner is defined as the
39  * Component in an application that will typically receive all KeyEvents
40  * generated by the user. The focused Window is the Window that is, or
41  * contains, the focus owner. Only a Frame or a Dialog can be the active
42  * Window. The native windowing system may denote the active Window or its
43  * children with special decorations, such as a highlighted title bar. The
44  * active Window is always either the focused Window, or the first Frame or
45  * Dialog that is an owner of the focused Window.
46  * <p>
47  * The KeyboardFocusManager is both a centralized location for client code to
48  * query for the focus owner and initiate focus changes, and an event
49  * dispatcher for all FocusEvents, WindowEvents related to focus, and
50  * KeyEvents.
51  * <p>
52  * Some browsers partition applets in different code bases into separate
53  * contexts, and establish walls between these contexts. In such a scenario,
54  * there will be one KeyboardFocusManager per context. Other browsers place all
55  * applets into the same context, implying that there will be only a single,
56  * global KeyboardFocusManager for all applets. This behavior is
57  * implementation-dependent. Consult your browser's documentation for more
58  * information. No matter how many contexts there may be, however, there can
59  * never be more than one focus owner, focused Window, or active Window, per
60  * ClassLoader.
61  * <p>
62  * Please see
63  * <a HREF="http://java.sun.com/docs/books/tutorial/uiswing/misc/focus.html">
64  * How to Use the Focus Subsystem</a>,
65  * a section in <em>The Java Tutorial</em>, and the
66  * <a HREF="../../java/awt/doc-files/FocusSpec.html">Focus Specification</a>
67  * for more information.
68  *
69  * @author David Mendenhall
70  * @version 1.66, 03/13/07
71  *
72  * @see Window
73  * @see Frame
74  * @see Dialog
75  * @see java.awt.event.FocusEvent
76  * @see java.awt.event.WindowEvent
77  * @see java.awt.event.KeyEvent
78  * @since 1.4
79  */
80 public abstract class KeyboardFocusManager
81     implements KeyEventDispatcher , KeyEventPostProcessor
82 {
83
84     // Shared focus engine logger
85 private static final Logger focusLog = Logger.getLogger("java.awt.focus.KeyboardFocusManager");
86
87     static {
88         /* ensure that the necessary native libraries are loaded */
89         Toolkit.loadLibraries();
90         if (!GraphicsEnvironment.isHeadless()) {
91             initIDs();
92         }
93     }
94
95     transient KeyboardFocusManagerPeer peer;
96
97     /**
98      * Initialize JNI field and method IDs
99      */
100     private static native void initIDs();
101
102     private static final DebugHelper dbg =
103         DebugHelper.create(KeyboardFocusManager .class);
104
105     /**
106      * The identifier for the Forward focus traversal keys.
107      *
108      * @see #setDefaultFocusTraversalKeys
109      * @see #getDefaultFocusTraversalKeys
110      * @see Component#setFocusTraversalKeys
111      * @see Component#getFocusTraversalKeys
112      */
113     public static final int FORWARD_TRAVERSAL_KEYS = 0;
114
115     /**
116      * The identifier for the Backward focus traversal keys.
117      *
118      * @see #setDefaultFocusTraversalKeys
119      * @see #getDefaultFocusTraversalKeys
120      * @see Component#setFocusTraversalKeys
121      * @see Component#getFocusTraversalKeys
122      */
123     public static final int BACKWARD_TRAVERSAL_KEYS = 1;
124
125     /**
126      * The identifier for the Up Cycle focus traversal keys.
127      *
128      * @see #setDefaultFocusTraversalKeys
129      * @see #getDefaultFocusTraversalKeys
130      * @see Component#setFocusTraversalKeys
131      * @see Component#getFocusTraversalKeys
132      */
133     public static final int UP_CYCLE_TRAVERSAL_KEYS = 2;
134
135     /**
136      * The identifier for the Down Cycle focus traversal keys.
137      *
138      * @see #setDefaultFocusTraversalKeys
139      * @see #getDefaultFocusTraversalKeys
140      * @see Component#setFocusTraversalKeys
141      * @see Component#getFocusTraversalKeys
142      */
143     public static final int DOWN_CYCLE_TRAVERSAL_KEYS = 3;
144
145     static final int TRAVERSAL_KEY_LENGTH = DOWN_CYCLE_TRAVERSAL_KEYS + 1;
146
147     private transient boolean inActivation;
148
149     /*
150     * Please be careful changing this method! It is called from
151     * javax.swing.JComponent.runInputVerifier() using reflection.
152     */
153     synchronized boolean isInActivation() {
154         return inActivation;
155     }
156
157     synchronized void setInActivation(boolean inActivation) {
158         this.inActivation = inActivation;
159     }
160
161     /**
162      * Returns the current KeyboardFocusManager instance for the calling
163      * thread's context.
164      *
165      * @return this thread's context's KeyboardFocusManager
166      * @see #setCurrentKeyboardFocusManager
167      */
168     public static KeyboardFocusManager getCurrentKeyboardFocusManager() {
169     return getCurrentKeyboardFocusManager(AppContext.getAppContext());
170     }
171
172     synchronized static KeyboardFocusManager
173     getCurrentKeyboardFocusManager(AppContext appcontext)
174     {
175         KeyboardFocusManager manager = (KeyboardFocusManager )
176             appcontext.get(KeyboardFocusManager .class);
177         if (manager == null) {
178             manager = new DefaultKeyboardFocusManager ();
179             appcontext.put(KeyboardFocusManager .class, manager);
180         }
181         return manager;
182     }
183
184     /**
185      * Sets the current KeyboardFocusManager instance for the calling thread's
186      * context. If null is specified, then the current KeyboardFocusManager
187      * is replaced with a new instance of DefaultKeyboardFocusManager.
188      * <p>
189      * If a SecurityManager is installed, the calling thread must be granted
190      * the AWTPermission "replaceKeyboardFocusManager" in order to replace the
191      * the current KeyboardFocusManager. If this permission is not granted,
192      * this method will throw a SecurityException, and the current
193      * KeyboardFocusManager will be unchanged.
194      *
195      * @param newManager the new KeyboardFocusManager for this thread's context
196      * @see #getCurrentKeyboardFocusManager
197      * @see DefaultKeyboardFocusManager
198      * @throws SecurityException if the calling thread does not have permission
199      * to replace the current KeyboardFocusManager
200      */
201     public static void setCurrentKeyboardFocusManager(
202         KeyboardFocusManager newManager) throws SecurityException
203     {
204         SecurityManager security = System.getSecurityManager();
205         if (security != null) {
206             if (replaceKeyboardFocusManagerPermission == null) {
207                 replaceKeyboardFocusManagerPermission =
208                     new AWTPermission ("replaceKeyboardFocusManager");
209             }
210             security.
211                 checkPermission(replaceKeyboardFocusManagerPermission);
212         }
213
214         KeyboardFocusManager oldManager = null;
215
216         synchronized (KeyboardFocusManager .class) {
217             AppContext appcontext = AppContext.getAppContext();
218
219             if (newManager != null) {
220                 oldManager = getCurrentKeyboardFocusManager(appcontext);
221
222                 appcontext.put(KeyboardFocusManager .class, newManager);
223             } else {
224                 oldManager = getCurrentKeyboardFocusManager(appcontext);
225                 appcontext.remove(KeyboardFocusManager .class);
226             }
227         }
228
229         if (oldManager != null) {
230             oldManager.firePropertyChange("managingFocus",
231                                           Boolean.TRUE,
232                                           Boolean.FALSE);
233         }
234         if (newManager != null) {
235             newManager.firePropertyChange("managingFocus",
236                                           Boolean.FALSE,
237                                           Boolean.TRUE);
238         }
239     }
240
241     /**
242      * The Component in an application that will typically receive all
243      * KeyEvents generated by the user.
244      */
245     private static Component focusOwner;
246
247     /**
248      * The Component in an application that will regain focus when an
249      * outstanding temporary focus transfer has completed, or the focus owner,
250      * if no outstanding temporary transfer exists.
251      */
252     private static Component permanentFocusOwner;
253
254     /**
255      * The Window which is, or contains, the focus owner.
256      */
257     private static Window focusedWindow;
258
259     /**
260      * Only a Frame or a Dialog can be the active Window. The native windowing
261      * system may denote the active Window with a special decoration, such as a
262      * highlighted title bar. The active Window is always either the focused
263      * Window, or the first Frame or Dialog which is an owner of the focused
264      * Window.
265      */
266     private static Window activeWindow;
267
268     /**
269      * The default FocusTraversalPolicy for all Windows that have no policy of
270      * their own set. If those Windows have focus-cycle-root children that have
271      * no keyboard-traversal policy of their own, then those children will also
272      * inherit this policy (as will, recursively, their focus-cycle-root
273      * children).
274      */
275     private FocusTraversalPolicy defaultPolicy =
276         new DefaultFocusTraversalPolicy ();
277
278     /**
279      * The bound property names of each focus traversal key.
280      */
281     private static final String [] defaultFocusTraversalKeyPropertyNames = {
282         "forwardDefaultFocusTraversalKeys",
283         "backwardDefaultFocusTraversalKeys",
284         "upCycleDefaultFocusTraversalKeys",
285         "downCycleDefaultFocusTraversalKeys"
286     };
287
288     /**
289      * The default strokes for initializing the default focus traversal keys.
290      */
291     private static final AWTKeyStroke [][] defaultFocusTraversalKeyStrokes = {
292         {
293             AWTKeyStroke.getAWTKeyStroke(KeyEvent.VK_TAB, 0, false),
294             AWTKeyStroke.getAWTKeyStroke(KeyEvent.VK_TAB, InputEvent.CTRL_DOWN_MASK | InputEvent.CTRL_MASK, false),
295         },
296         {
297             AWTKeyStroke.getAWTKeyStroke(KeyEvent.VK_TAB, InputEvent.SHIFT_DOWN_MASK | InputEvent.SHIFT_MASK, false),
298             AWTKeyStroke.getAWTKeyStroke(KeyEvent.VK_TAB,
299                                          InputEvent.SHIFT_DOWN_MASK | InputEvent.SHIFT_MASK | InputEvent.CTRL_DOWN_MASK | InputEvent.CTRL_MASK,
300                                          false),
301         },
302         {},
303         {},
304       };
305     /**
306      * The default focus traversal keys. Each array of traversal keys will be
307      * in effect on all Windows that have no such array of their own explicitly
308      * set. Each array will also be inherited, recursively, by any child
309      * Component of those Windows that has no such array of its own explicitly
310      * set.
311      */
312     private Set [] defaultFocusTraversalKeys = new Set [4];
313
314     /**
315      * The current focus cycle root. If the focus owner is itself a focus cycle
316      * root, then it may be ambiguous as to which Components represent the next
317      * and previous Components to focus during normal focus traversal. In that
318      * case, the current focus cycle root is used to differentiate among the
319      * possibilities.
320      */
321     private static Container currentFocusCycleRoot;
322
323     /**
324      * A description of any VetoableChangeListeners which have been registered.
325      */
326     private VetoableChangeSupport vetoableSupport;
327
328     /**
329      * A description of any PropertyChangeListeners which have been registered.
330      */
331     private PropertyChangeSupport changeSupport;
332
333     /**
334      * This KeyboardFocusManager's KeyEventDispatcher chain. The List does not
335      * include this KeyboardFocusManager unless it was explicitly re-registered
336      * via a call to <code>addKeyEventDispatcher</code>. If no other
337      * KeyEventDispatchers are registered, this field may be null or refer to
338      * a List of length 0.
339      */
340     private java.util.LinkedList keyEventDispatchers;
341
342     /**
343      * This KeyboardFocusManager's KeyEventPostProcessor chain. The List does
344      * not include this KeyboardFocusManager unless it was explicitly
345      * re-registered via a call to <code>addKeyEventPostProcessor</code>.
346      * If no other KeyEventPostProcessors are registered, this field may be
347      * null or refer to a List of length 0.
348      */
349     private java.util.LinkedList keyEventPostProcessors;
350
351     /**
352      * Maps Windows to those Windows' most recent focus owners.
353      */
354     private static java.util.Map mostRecentFocusOwners = new WeakHashMap ();
355
356     /**
357      * Error String for initializing SecurityExceptions.
358      */
359     private static final String notPrivileged = "this KeyboardFocusManager is not installed in the current thread's context";
360
361     /**
362      * We cache the permission used to verify that the calling thread is
363      * permitted to access the global focus state.
364      */
365     private static AWTPermission replaceKeyboardFocusManagerPermission;
366
367     /*
368      * SequencedEvent which is currently dispatched in AppContext.
369      */
370     transient SequencedEvent currentSequencedEvent = null;
371
372     final void setCurrentSequencedEvent(SequencedEvent current) {
373         synchronized (SequencedEvent .class) {
374             assert(current == null || currentSequencedEvent == null);
375             currentSequencedEvent = current;
376         }
377     }
378
379     final SequencedEvent getCurrentSequencedEvent() {
380         synchronized (SequencedEvent .class) {
381             return currentSequencedEvent;
382         }
383     }
384
385     static Set initFocusTraversalKeysSet(String value, Set targetSet) {
386     StringTokenizer tokens = new StringTokenizer (value, ",");
387     while (tokens.hasMoreTokens()) {
388         targetSet.add(AWTKeyStroke.getAWTKeyStroke(tokens.nextToken()));
389     }
390     return (targetSet.isEmpty())
391         ? Collections.EMPTY_SET
392         : Collections.unmodifiableSet(targetSet);
393     }
394
395     /**
396      * Initializes a KeyboardFocusManager.
397      */
398     public KeyboardFocusManager() {
399         for (int i = 0; i < TRAVERSAL_KEY_LENGTH; i++) {
400             Set work_set = new HashSet ();
401             for (int j = 0; j < defaultFocusTraversalKeyStrokes[i].length; j++) {
402                 work_set.add(defaultFocusTraversalKeyStrokes[i][j]);
403             }
404             defaultFocusTraversalKeys[i] = (work_set.isEmpty())
405                 ? Collections.EMPTY_SET
406                 : Collections.unmodifiableSet(work_set);
407         }
408         initPeer();
409     }
410
411     private void initPeer() {
412         if (Toolkit.getDefaultToolkit() instanceof HeadlessToolkit){
413             peer = ((HeadlessToolkit)Toolkit.getDefaultToolkit()).createKeyboardFocusManagerPeer(this);
414         }
415         if (Toolkit.getDefaultToolkit() instanceof SunToolkit){
416             peer = ((SunToolkit)Toolkit.getDefaultToolkit()).createKeyboardFocusManagerPeer(this);
417         }
418     }
419
420     /**
421      * Returns the focus owner, if the focus owner is in the same context as
422      * the calling thread. The focus owner is defined as the Component in an
423      * application that will typically receive all KeyEvents generated by the
424      * user. KeyEvents which map to the focus owner's focus traversal keys will
425      * not be delivered if focus traversal keys are enabled for the focus
426      * owner. In addition, KeyEventDispatchers may retarget or consume
427      * KeyEvents before they reach the focus owner.
428      *
429      * @return the focus owner, or null if the focus owner is not a member of
430      * the calling thread's context
431      * @see #getGlobalFocusOwner
432      * @see #setGlobalFocusOwner
433      */
434     public Component getFocusOwner() {
435         synchronized (KeyboardFocusManager .class) {
436         if (focusOwner == null) {
437             return null;
438         }
439
440         return (focusOwner.appContext == AppContext.getAppContext())
441             ? focusOwner
442             : null;
443     }
444     }
445
446     /**
447      * Returns the focus owner, even if the calling thread is in a different
448      * context than the focus owner. The focus owner is defined as the
449      * Component in an application that will typically receive all KeyEvents
450      * generated by the user. KeyEvents which map to the focus owner's focus
451      * traversal keys will not be delivered if focus traversal keys are enabled
452      * for the focus owner. In addition, KeyEventDispatchers may retarget or
453      * consume KeyEvents before they reach the focus owner.
454      * <p>
455      * This method will throw a SecurityException if this KeyboardFocusManager
456      * is not the current KeyboardFocusManager for the calling thread's
457      * context.
458      *
459      * @return the focus owner
460      * @see #getFocusOwner
461      * @see #setGlobalFocusOwner
462      * @throws SecurityException if this KeyboardFocusManager is not the
463      * current KeyboardFocusManager for the calling thread's context
464      */
465     protected Component getGlobalFocusOwner() throws SecurityException {
466         synchronized (KeyboardFocusManager .class) {
467         if (this == getCurrentKeyboardFocusManager()) {
468             return focusOwner;
469         } else {
470                 if (focusLog.isLoggable(Level.FINE)) focusLog.fine("This manager is " + this + ", current is " + getCurrentKeyboardFocusManager());
471             throw new SecurityException (notPrivileged);
472         }
473     }
474     }
475
476     /**
477      * Sets the focus owner. The operation will be cancelled if the Component
478      * is not focusable. The focus owner is defined as the Component in an
479      * application that will typically receive all KeyEvents generated by the
480      * user. KeyEvents which map to the focus owner's focus traversal keys will
481      * not be delivered if focus traversal keys are enabled for the focus
482      * owner. In addition, KeyEventDispatchers may retarget or consume
483      * KeyEvents before they reach the focus owner.
484      * <p>
485      * This method does not actually set the focus to the specified Component.
486      * It merely stores the value to be subsequently returned by
487      * <code>getFocusOwner()</code>. Use <code>Component.requestFocus()</code>
488      * or <code>Component.requestFocusInWindow()</code> to change the focus
489      * owner, subject to platform limitations.
490      *
491      * @param focusOwner the focus owner
492      * @see #getFocusOwner
493      * @see #getGlobalFocusOwner
494      * @see Component#requestFocus()
495      * @see Component#requestFocusInWindow()
496      * @see Component#isFocusable
497      * @beaninfo
498      * bound: true
499      */
500     protected void setGlobalFocusOwner(Component focusOwner) {
501         Component oldFocusOwner = null;
502     boolean shouldFire = false;
503
504     if (focusOwner == null || focusOwner.isFocusable()) {
505         synchronized (KeyboardFocusManager .class) {
506             oldFocusOwner = getFocusOwner();
507
508         try {
509             fireVetoableChange("focusOwner", oldFocusOwner,
510                        focusOwner);
511         } catch (PropertyVetoException e) {
512             // rejected
513 return;
514         }
515
516         KeyboardFocusManager.focusOwner = focusOwner;
517
518         if (focusOwner != null &&
519                     (getCurrentFocusCycleRoot() == null ||
520              !focusOwner.isFocusCycleRoot(getCurrentFocusCycleRoot())))
521         {
522             Container rootAncestor =
523                 focusOwner.getFocusCycleRootAncestor();
524             if (rootAncestor == null && (focusOwner instanceof Window ))
525             {
526                 rootAncestor = (Container )focusOwner;
527             }
528                     if (rootAncestor != null) {
529                 setGlobalCurrentFocusCycleRoot(rootAncestor);
530             }
531                 }
532
533         shouldFire = true;
534         }
535     }
536
537     if (shouldFire) {
538         firePropertyChange("focusOwner", oldFocusOwner, focusOwner);
539     }
540     }
541
542     /**
543      * Clears the global focus owner at both the Java and native levels. If
544      * there exists a focus owner, that Component will receive a permanent
545      * FOCUS_LOST event. After this operation completes, the native windowing
546      * system will discard all user-generated KeyEvents until the user selects
547      * a new Component to receive focus, or a Component is given focus
548      * explicitly via a call to <code>requestFocus()</code>. This operation
549      * does not change the focused or active Windows.
550      *
551      * @see Component#requestFocus()
552      * @see java.awt.event.FocusEvent#FOCUS_LOST
553      */
554     public void clearGlobalFocusOwner() {
555         if (!GraphicsEnvironment.isHeadless()) {
556             // Toolkit must be fully initialized, otherwise
557 // _clearGlobalFocusOwner will crash or throw an exception
558 Toolkit.getDefaultToolkit();
559
560             _clearGlobalFocusOwner();
561         }
562     }
563     private void _clearGlobalFocusOwner() {
564         Window activeWindow = markClearGlobalFocusOwner();
565         peer.clearGlobalFocusOwner(activeWindow);
566     }
567
568     Component getNativeFocusOwner() {
569         return peer.getCurrentFocusOwner();
570     }
571
572     void setNativeFocusOwner(Component comp) {
573         focusLog.log(Level.FINEST, "Calling peer {0} setCurrentFocusOwner for {1}",
574                      new Object [] {peer, comp});
575         peer.setCurrentFocusOwner(comp);
576     }
577       
578     Window getNativeFocusedWindow() {
579         return peer.getCurrentFocusedWindow();
580     }
581
582     void setNativeFocusedWindow(Window win) {
583         peer.setCurrentFocusedWindow(win);
584     }
585
586     /**
587      * Returns the permanent focus owner, if the permanent focus owner is in
588      * the same context as the calling thread. The permanent focus owner is
589      * defined as the last Component in an application to receive a permanent
590      * FOCUS_GAINED event. The focus owner and permanent focus owner are
591      * equivalent unless a temporary focus change is currently in effect. In
592      * such a situation, the permanent focus owner will again be the focus
593      * owner when the temporary focus change ends.
594      *
595      * @return the permanent focus owner, or null if the permanent focus owner
596      * is not a member of the calling thread's context
597      * @see #getGlobalPermanentFocusOwner
598      * @see #setGlobalPermanentFocusOwner
599      */
600     public Component getPermanentFocusOwner() {
601     synchronized (KeyboardFocusManager .class) {
602         if (permanentFocusOwner == null) {
603         return null;
604         }
605
606         return (permanentFocusOwner.appContext ==
607             AppContext.getAppContext())
608         ? permanentFocusOwner
609         : null;
610     }
611     }
612
613     /**
614      * Returns the permanent focus owner, even if the calling thread is in a
615      * different context than the permanent focus owner. The permanent focus
616      * owner is defined as the last Component in an application to receive a
617      * permanent FOCUS_GAINED event. The focus owner and permanent focus owner
618      * are equivalent unless a temporary focus change is currently in effect.
619      * In such a situation, the permanent focus owner will again be the focus
620      * owner when the temporary focus change ends.
621      * <p>
622      * This method will throw a SecurityException if this KeyboardFocusManager
623      * is not the current KeyboardFocusManager for the calling thread's
624      * context.
625      *
626      * @return the permanent focus owner
627      * @see #getPermanentFocusOwner
628      * @see #setGlobalPermanentFocusOwner
629      * @throws SecurityException if this KeyboardFocusManager is not the
630      * current KeyboardFocusManager for the calling thread's context
631      */
632     protected Component getGlobalPermanentFocusOwner()
633     throws SecurityException
634     {
635     synchronized (KeyboardFocusManager .class) {
636         if (this == getCurrentKeyboardFocusManager()) {
637         return permanentFocusOwner;
638         } else {
639                 if (focusLog.isLoggable(Level.FINE)) focusLog.fine("This manager is " + this + ", current is " + getCurrentKeyboardFocusManager());
640         throw new SecurityException (notPrivileged);
641         }
642     }
643     }
644
645     /**
646      * Sets the permanent focus owner. The operation will be cancelled if the
647      * Component is not focusable. The permanent focus owner is defined as the
648      * last Component in an application to receive a permanent FOCUS_GAINED
649      * event. The focus owner and permanent focus owner are equivalent unless
650      * a temporary focus change is currently in effect. In such a situation,
651      * the permanent focus owner will again be the focus owner when the
652      * temporary focus change ends.
653      * <p>
654      * This method does not actually set the focus to the specified Component.
655      * It merely stores the value to be subsequently returned by
656      * <code>getPermanentFocusOwner()</code>. Use
657      * <code>Component.requestFocus()</code> or
658      * <code>Component.requestFocusInWindow()</code> to change the focus owner,
659      * subject to platform limitations.
660      *
661      * @param permanentFocusOwner the permanent focus owner
662      * @see #getPermanentFocusOwner
663      * @see #getGlobalPermanentFocusOwner
664      * @see Component#requestFocus()
665      * @see Component#requestFocusInWindow()
666      * @see Component#isFocusable
667      * @beaninfo
668      * bound: true
669      */
670     protected void setGlobalPermanentFocusOwner(Component permanentFocusOwner)
671     {
672         Component oldPermanentFocusOwner = null;
673     boolean shouldFire = false;
674
675     if (permanentFocusOwner == null || permanentFocusOwner.isFocusable()) {
676         synchronized (KeyboardFocusManager .class) {
677             oldPermanentFocusOwner = getPermanentFocusOwner();
678
679         try {
680             fireVetoableChange("permanentFocusOwner",
681                        oldPermanentFocusOwner,
682                        permanentFocusOwner);
683         } catch (PropertyVetoException e) {
684             // rejected
685 return;
686         }
687
688         KeyboardFocusManager.permanentFocusOwner = permanentFocusOwner;
689
690         KeyboardFocusManager.
691             setMostRecentFocusOwner(permanentFocusOwner);
692
693         shouldFire = true;
694         }
695     }
696
697     if (shouldFire) {
698         firePropertyChange("permanentFocusOwner", oldPermanentFocusOwner,
699                    permanentFocusOwner);
700     }
701     }
702
703     /**
704      * Returns the focused Window, if the focused Window is in the same context
705      * as the calling thread. The focused Window is the Window that is or
706      * contains the focus owner.
707      *
708      * @return the focused Window, or null if the focused Window is not a
709      * member of the calling thread's context
710      * @see #getGlobalFocusedWindow
711      * @see #setGlobalFocusedWindow
712      */
713     public Window getFocusedWindow() {
714         synchronized (KeyboardFocusManager .class) {
715         if (focusedWindow == null) {
716             return null;
717         }
718
719         return (focusedWindow.appContext == AppContext.getAppContext())
720             ? focusedWindow
721             : null;
722     }
723     }
724
725     /**
726      * Returns the focused Window, even if the calling thread is in a different
727      * context than the focused Window. The focused Window is the Window that
728      * is or contains the focus owner.
729      * <p>
730      * This method will throw a SecurityException if this KeyboardFocusManager
731      * is not the current KeyboardFocusManager for the calling thread's
732      * context.
733      *
734      * @return the focused Window
735      * @see #getFocusedWindow
736      * @see #setGlobalFocusedWindow
737      * @throws SecurityException if this KeyboardFocusManager is not the
738      * current KeyboardFocusManager for the calling thread's context
739      */
740     protected Window getGlobalFocusedWindow() throws SecurityException {
741         synchronized (KeyboardFocusManager .class) {
742         if (this == getCurrentKeyboardFocusManager()) {
743            return focusedWindow;
744         } else {
745                 if (focusLog.isLoggable(Level.FINE)) focusLog.fine("This manager is " + this + ", current is " + getCurrentKeyboardFocusManager());
746             throw new SecurityException (notPrivileged);
747         }
748     }
749     }
750
751     /**
752      * Sets the focused Window. The focused Window is the Window that is or
753      * contains the focus owner. The operation will be cancelled if the
754      * specified Window to focus is not a focusable Window.
755      * <p>
756      * This method does not actually change the focused Window as far as the
757      * native windowing system is concerned. It merely stores the value to be
758      * subsequently returned by <code>getFocusedWindow()</code>. Use
759      * <code>Component.requestFocus()</code> or
760      * <code>Component.requestFocusInWindow()</code> to change the focused
761      * Window, subject to platform limitations.
762      *
763      * @param focusedWindow the focused Window
764      * @see #getFocusedWindow
765      * @see #getGlobalFocusedWindow
766      * @see Component#requestFocus()
767      * @see Component#requestFocusInWindow()
768      * @see Window#isFocusableWindow
769      * @beaninfo
770      * bound: true
771      */
772     protected void setGlobalFocusedWindow(Window focusedWindow) {
773         Window oldFocusedWindow = null;
774     boolean shouldFire = false;
775
776     if (focusedWindow == null || focusedWindow.isFocusableWindow()) {
777         synchronized (KeyboardFocusManager .class) {
778             oldFocusedWindow = getFocusedWindow();
779
780         try {
781             fireVetoableChange("focusedWindow", oldFocusedWindow,
782                        focusedWindow);
783         } catch (PropertyVetoException e) {
784             // rejected
785 return;
786         }
787
788         KeyboardFocusManager.focusedWindow = focusedWindow;
789         shouldFire = true;
790         }
791     }
792
793     if (shouldFire) {
794         firePropertyChange("focusedWindow", oldFocusedWindow,
795                    focusedWindow);
796     }
797     }
798
799     /**
800      * Returns the active Window, if the active Window is in the same context
801      * as the calling thread. Only a Frame or a Dialog can be the active
802      * Window. The native windowing system may denote the active Window or its
803      * children with special decorations, such as a highlighted title bar.
804      * The active Window is always either the focused Window, or the first
805      * Frame or Dialog that is an owner of the focused Window.
806      *
807      * @return the active Window, or null if the active Window is not a member
808      * of the calling thread's context
809      * @see #getGlobalActiveWindow
810      * @see #setGlobalActiveWindow
811      */
812     public Window getActiveWindow() {
813         synchronized (KeyboardFocusManager .class) {
814         if (activeWindow == null) {
815             return null;
816         }
817
818         return (activeWindow.appContext == AppContext.getAppContext())
819             ? activeWindow
820             : null;
821     }
822     }
823
824     /**
825      * Returns the active Window, even if the calling thread is in a different
826      * context than the active Window. Only a Frame or a Dialog can be the
827      * active Window. The native windowing system may denote the active Window
828      * or its children with special decorations, such as a highlighted title
829      * bar. The active Window is always either the focused Window, or the first
830      * Frame or Dialog that is an owner of the focused Window.
831      * <p>
832      * This method will throw a SecurityException if this KeyboardFocusManager
833      * is not the current KeyboardFocusManager for the calling thread's
834      * context.
835      *
836      * @return the active Window
837      * @see #getActiveWindow
838      * @see #setGlobalActiveWindow
839      * @throws SecurityException if this KeyboardFocusManager is not the
840      * current KeyboardFocusManager for the calling thread's context
841      */
842     protected Window getGlobalActiveWindow() throws SecurityException {
843         synchronized (KeyboardFocusManager .class) {
844         if (this == getCurrentKeyboardFocusManager()) {
845            return activeWindow;
846         } else {
847                 if (focusLog.isLoggable(Level.FINE)) focusLog.fine("This manager is " + this + ", current is " + getCurrentKeyboardFocusManager());
848         throw new SecurityException (notPrivileged);
849         }
850     }
851     }
852
853     /**
854      * Sets the active Window. Only a Frame or a Dialog can be the active
855      * Window. The native windowing system may denote the active Window or its
856      * children with special decorations, such as a highlighted title bar. The
857      * active Window is always either the focused Window, or the first Frame or
858      * Dialog that is an owner of the focused Window.
859      * <p>
860      * This method does not actually change the active Window as far as the
861      * native windowing system is concerned. It merely stores the value to be
862      * subsequently returned by <code>getActiveWindow()</code>. Use
863      * <code>Component.requestFocus()</code> or
864      * <code>Component.requestFocusInWindow()</code>to change the active
865      * Window, subject to platform limitations.
866      *
867      * @param activeWindow the active Window
868      * @see #getActiveWindow
869      * @see #getGlobalActiveWindow
870      * @see Component#requestFocus()
871      * @see Component#requestFocusInWindow()
872      * @beaninfo
873      * bound: true
874      */
875     protected void setGlobalActiveWindow(Window activeWindow) {
876         Window oldActiveWindow;
877     synchronized (KeyboardFocusManager .class) {
878         oldActiveWindow = getActiveWindow();
879             if (focusLog.isLoggable(Level.FINER)) {
880                 focusLog.finer("Setting global active window to " + activeWindow + ", old active " + oldActiveWindow);
881             }
882
883         try {
884         fireVetoableChange("activeWindow", oldActiveWindow,
885                    activeWindow);
886         } catch (PropertyVetoException e) {
887         // rejected
888 return;
889         }
890
891         KeyboardFocusManager.activeWindow = activeWindow;
892     }
893
894     firePropertyChange("activeWindow", oldActiveWindow, activeWindow);
895     }
896
897     /**
898      * Returns the default FocusTraversalPolicy. Top-level components
899