1 /* 2 * @(#)KeyEventPostProcessor.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; 10 11 12 /** 13 * A KeyEventPostProcessor cooperates with the current KeyboardFocusManager 14 * in the final resolution of all unconsumed KeyEvents. KeyEventPostProcessors 15 * registered with the current KeyboardFocusManager will receive KeyEvents 16 * after the KeyEvents have been dispatched to and handled by their targets. 17 * KeyEvents that would have been otherwise discarded because no Component in 18 * the application currently owns the focus will also be forwarded to 19 * registered KeyEventPostProcessors. This will allow applications to implement 20 * features that require global KeyEvent post-handling, such as menu shortcuts. 21 * <p> 22 * Note that the KeyboardFocusManager itself implements KeyEventPostProcessor. 23 * By default, the current KeyboardFocusManager will be the final 24 * KeyEventPostProcessor in the chain. The current KeyboardFocusManager cannot 25 * be completely deregistered as a KeyEventPostProcessor. However, if a 26 * KeyEventPostProcessor reports that no further post-processing of the 27 * KeyEvent should take place, the AWT will consider the event fully handled 28 * and will take no additional action with regard to the event. (While it is 29 * possible for client code to register the current KeyboardFocusManager as 30 * a KeyEventPostProcessor one or more times, this is usually unnecessary and 31 * not recommended.) 32 * 33 * @author David Mendenhall 34 * @version 1.5, 12/19/03 35 * 36 * @see KeyboardFocusManager#addKeyEventPostProcessor 37 * @see KeyboardFocusManager#removeKeyEventPostProcessor 38 * @since 1.4 39 */ 40 public interface KeyEventPostProcessor { 41 42 /** 43 * This method is called by the current KeyboardFocusManager, requesting 44 * that this KeyEventPostProcessor perform any necessary post-processing 45 * which should be part of the KeyEvent's final resolution. At the time 46 * this method is invoked, typically the KeyEvent has already been 47 * dispatched to and handled by its target. However, if no Component in 48 * the application currently owns the focus, then the KeyEvent has not 49 * been dispatched to any Component. Typically, KeyEvent post-processing 50 * will be used to implement features which require global KeyEvent 51 * post-handling, such as menu shortcuts. Note that if a 52 * KeyEventPostProcessor wishes to dispatch the KeyEvent, it must use 53 * <code>redispatchEvent</code> to prevent the AWT from recursively 54 * requesting that this KeyEventPostProcessor perform post-processing 55 * of the event again. 56 * <p> 57 * If an implementation of this method returns <code>false</code>, then the 58 * KeyEvent is passed to the next KeyEventPostProcessor in the chain, 59 * ending with the current KeyboardFocusManager. If an implementation 60 * returns <code>true</code>, the KeyEvent is assumed to have been fully 61 * handled (although this need not be the case), and the AWT will take no 62 * further action with regard to the KeyEvent. If an implementation 63 * consumes the KeyEvent but returns <code>false</code>, the consumed 64 * event will still be passed to the next KeyEventPostProcessor in the 65 * chain. It is important for developers to check whether the KeyEvent has 66 * been consumed before performing any post-processing of the KeyEvent. By 67 * default, the current KeyboardFocusManager will perform no post- 68 * processing in response to a consumed KeyEvent. 69 * 70 * @param e the KeyEvent to post-process 71 * @return <code>true</code> if the AWT should take no further action with 72 * regard to the KeyEvent; <code>false</code> otherwise 73 * @see KeyboardFocusManager#redispatchEvent 74 */ 75 boolean postProcessKeyEvent(KeyEvent e); 76 } 77