KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > java > awt > KeyEventDispatcher


1 /*
2  * @(#)KeyEventDispatcher.java 1.5 03/12/19
3  *
4  * Copyright 2004 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.KeyEvent JavaDoc;
10
11
12 /**
13  * A KeyEventDispatcher cooperates with the current KeyboardFocusManager in the
14  * targeting and dispatching of all KeyEvents. KeyEventDispatchers registered
15  * with the current KeyboardFocusManager will receive KeyEvents before they are
16  * dispatched to their targets, allowing each KeyEventDispatcher to retarget
17  * the event, consume it, dispatch the event itself, or make other changes.
18  * <p>
19  * Note that KeyboardFocusManager itself implements KeyEventDispatcher. By
20  * default, the current KeyboardFocusManager will be the sink for all KeyEvents
21  * not dispatched by the registered KeyEventDispatchers. The current
22  * KeyboardFocusManager cannot be completely deregistered as a
23  * KeyEventDispatcher. However, if a KeyEventDispatcher reports that it
24  * dispatched the KeyEvent, regardless of whether it actually did so, the
25  * KeyboardFocusManager will take no further action with regard to the
26  * KeyEvent. (While it is possible for client code to register the current
27  * KeyboardFocusManager as a KeyEventDispatcher one or more times, this is
28  * usually unnecessary and not recommended.)
29  *
30  * @author David Mendenhall
31  * @version 1.5, 12/19/03
32  *
33  * @see KeyboardFocusManager#addKeyEventDispatcher
34  * @see KeyboardFocusManager#removeKeyEventDispatcher
35  * @since 1.4
36  */
37 public interface KeyEventDispatcher {
38
39     /**
40      * This method is called by the current KeyboardFocusManager requesting
41      * that this KeyEventDispatcher dispatch the specified event on its behalf.
42      * This KeyEventDispatcher is free to retarget the event, consume it,
43      * dispatch it itself, or make other changes. This capability is typically
44      * used to deliver KeyEvents to Components other than the focus owner. This
45      * can be useful when navigating children of non-focusable Windows in an
46      * accessible environment, for example. Note that if a KeyEventDispatcher
47      * dispatches the KeyEvent itself, it must use <code>redispatchEvent</code>
48      * to prevent the current KeyboardFocusManager from recursively requesting
49      * that this KeyEventDispatcher dispatch the event again.
50      * <p>
51      * If an implementation of this method returns <code>false</code>, then
52      * the KeyEvent is passed to the next KeyEventDispatcher in the chain,
53      * ending with the current KeyboardFocusManager. If an implementation
54      * returns <code>true</code>, the KeyEvent is assumed to have been
55      * dispatched (although this need not be the case), and the current
56      * KeyboardFocusManager will take no further action with regard to the
57      * KeyEvent. In such a case,
58      * <code>KeyboardFocusManager.dispatchEvent</code> should return
59      * <code>true</code> as well. If an implementation consumes the KeyEvent,
60      * but returns <code>false</code>, the consumed event will still be passed
61      * to the next KeyEventDispatcher in the chain. It is important for
62      * developers to check whether the KeyEvent has been consumed before
63      * dispatching it to a target. By default, the current KeyboardFocusManager
64      * will not dispatch a consumed KeyEvent.
65      *
66      * @param e the KeyEvent to dispatch
67      * @return <code>true</code> if the KeyboardFocusManager should take no
68      * further action with regard to the KeyEvent; <code>false</code>
69      * otherwise
70      * @see KeyboardFocusManager#redispatchEvent
71      */
72     boolean dispatchKeyEvent(KeyEvent JavaDoc e);
73 }
74
Popular Tags