01: /*
02: *
03: * Copyright 1990-2006 Sun Microsystems, Inc. All Rights Reserved.
04: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
05: *
06: * This program is free software; you can redistribute it and/or
07: * modify it under the terms of the GNU General Public License version
08: * 2 only, as published by the Free Software Foundation.
09: *
10: * This program is distributed in the hope that it will be useful, but
11: * WITHOUT ANY WARRANTY; without even the implied warranty of
12: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13: * General Public License version 2 for more details (a copy is
14: * included at /legal/license.txt).
15: *
16: * You should have received a copy of the GNU General Public License
17: * version 2 along with this work; if not, write to the Free Software
18: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
19: * 02110-1301 USA
20: *
21: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
22: * Clara, CA 95054 or visit www.sun.com if you need additional
23: * information or have any questions.
24: */
25: package java.awt;
26:
27: import java.awt.event.KeyEvent;
28:
29: /**
30: * A KeyEventDispatcher cooperates with the current KeyboardFocusManager in the
31: * targeting and dispatching of all KeyEvents. KeyEventDispatchers registered
32: * with the current KeyboardFocusManager will receive KeyEvents before they are
33: * dispatched to their targets, allowing each KeyEventDispatcher to retarget
34: * the event, consume it, dispatch the event itself, or make other changes.
35: * <p>
36: * Note that KeyboardFocusManager itself implements KeyEventDispatcher. By
37: * default, the current KeyboardFocusManager will be the sink for all KeyEvents
38: * not dispatched by the registered KeyEventDispatchers. The current
39: * KeyboardFocusManager cannot be completely deregistered as a
40: * KeyEventDispatcher. However, if a KeyEventDispatcher reports that it
41: * dispatched the KeyEvent, regardless of whether it actually did so, the
42: * KeyboardFocusManager will take no further action with regard to the
43: * KeyEvent. (While it is possible for client code to register the current
44: * KeyboardFocusManager as a KeyEventDispatcher one or more times, this is
45: * usually unnecessary and not recommended.)
46: *
47: * @author David Mendenhall
48: * @version 1.4, 01/23/03
49: *
50: * @see KeyboardFocusManager#addKeyEventDispatcher
51: * @see KeyboardFocusManager#removeKeyEventDispatcher
52: * @since 1.4
53: */
54: public interface KeyEventDispatcher {
55: /**
56: * This method is called by the current KeyboardFocusManager requesting
57: * that this KeyEventDispatcher dispatch the specified event on its behalf.
58: * This KeyEventDispatcher is free to retarget the event, consume it,
59: * dispatch it itself, or make other changes. This capability is typically
60: * used to deliver KeyEvents to Components other than the focus owner. This
61: * can be useful when navigating children of non-focusable Windows in an
62: * accessible environment, for example. Note that if a KeyEventDispatcher
63: * dispatches the KeyEvent itself, it must use <code>redispatchEvent</code>
64: * to prevent the current KeyboardFocusManager from recursively requesting
65: * that this KeyEventDispatcher dispatch the event again.
66: * <p>
67: * If an implementation of this method returns <code>false</code>, then
68: * the KeyEvent is passed to the next KeyEventDispatcher in the chain,
69: * ending with the current KeyboardFocusManager. If an implementation
70: * returns <code>true</code>, the KeyEvent is assumed to have been
71: * dispatched (although this need not be the case), and the current
72: * KeyboardFocusManager will take no further action with regard to the
73: * KeyEvent. In such a case,
74: * <code>KeyboardFocusManager.dispatchEvent</code> should return
75: * <code>true</code> as well. If an implementation consumes the KeyEvent,
76: * but returns <code>false</code>, the consumed event will still be passed
77: * to the next KeyEventDispatcher in the chain. It is important for
78: * developers to check whether the KeyEvent has been consumed before
79: * dispatching it to a target. By default, the current KeyboardFocusManager
80: * will not dispatch a consumed KeyEvent.
81: *
82: * @param e the KeyEvent to dispatch
83: * @return <code>true</code> if the KeyboardFocusManager should take no
84: * further action with regard to the KeyEvent; <code>false</code>
85: * otherwise
86: * @see KeyboardFocusManager#redispatchEvent
87: */
88: boolean dispatchKeyEvent(KeyEvent e);
89: }
|