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