com.threerings.util
Class KeyboardManager

java.lang.Object
  com.threerings.util.KeyboardManager

All Implemented Interfaces:

WindowFocusListener, KeyEventDispatcher, EventListener, AncestorListener

public class KeyboardManager
extends Object
implements KeyEventDispatcher, AncestorListener, WindowFocusListener

The keyboard manager observes keyboard actions on a particular component and posts commands associated with the key presses to the Controller hierarchy. It allows specifying the key repeat rate, and will begin repeating a key immediately after it is held down rather than depending on the system-specific key repeat delay/rate.

Nested Class Summary

protected class	KeyboardManager.KeyInfo
static interface	KeyboardManager.KeyObserver An interface to be implemented by those that care to be notified whenever an event (either a key press or a key release) occurs for any key while the keyboard manager is active.
protected static class	KeyboardManager.KeyObserverOp An observer operation to notify observers of a key event.

Field Summary

protected HashMap<Character,KeyboardManager.KeyInfo>	_chars A hashtable mapping characters to KeyboardManager.KeyInfo objects.
protected static RuntimeAdjust.BooleanAdjust	_debugTyping A debug hook that toggles excessive logging to help debug keyTyped behavior.
protected boolean	_enabled Whether the keyboard manager is accepting keyboard input.
protected boolean	_focus Whether the keyboard manager currently has the keyboard focus.
protected KeyboardManager.KeyObserverOp	_keyOp The operation used to notify observers of actual key events.
protected HashIntMap<KeyboardManager.KeyInfo>	_keys A hashtable mapping key codes to KeyboardManager.KeyInfo objects.
protected boolean	_nativeRepeat Whether native key auto-repeating was enabled when the keyboard manager was last enabled.
protected ObserverList<KeyboardManager.KeyObserver>	_observers The list of key observers.
protected long	_repeatDelay The expected approximate milliseconds between each key release/press event while the key is being auto-repeated.
protected boolean	_shouldDisableNativeRepeat Whether we want to disable native key auto-repeating.
protected JComponent	_target The component that receives keyboard events and that we associate with posted controller commands.
protected Window	_window The window containing our target component whose focus events we care to observe, or null if we're not observing a window.
protected KeyTranslator	_xlate The translator that maps keyboard events to controller commands.
protected static boolean	DEBUG_EVENTS Whether to output debugging info for individual key events.
protected static boolean	DEBUG_INTERVAL Whether to output debugging info for interval callbacks.
protected static long	DEFAULT_REPEAT_DELAY The default repeat delay.

Constructor Summary

KeyboardManager()
Constructs a keyboard manager that is initially disabled.

Method Summary

void	ancestorAdded(AncestorEvent e)
void	ancestorMoved(AncestorEvent e)
void	ancestorRemoved(AncestorEvent e)
boolean	dispatchKeyEvent(KeyEvent e)
protected void	gainedFocus() Called when the keyboard manager gains focus and should begin handling keys again if it was previously enabled.
protected boolean	keyPressed(KeyEvent e) Called when Swing notifies us that a key has been pressed while the keyboard manager is active.
protected boolean	keyReleased(KeyEvent e) Called when Swing notifies us that a key has been released while the keyboard manager is active.
protected boolean	keyTyped(KeyEvent e) Called when Swing notifies us that a key has been typed while the keyboard manager is active.
protected void	logKey(String msg, KeyEvent e) Logs the given message and key.
protected void	lostFocus() Called when the keyboard manager loses focus and should cease handling keys.
protected void	notifyObservers(int id, int keyCode, long timestamp) Notifies all registered key observers of the supplied key event.
void	registerKeyObserver(KeyboardManager.KeyObserver obs) Registers a key observer that will be notified of all key events while the keyboard manager is active.
void	releaseAllKeys() Releases all keys and ceases any hot repeating action that may be going on.
void	removeKeyObserver(KeyboardManager.KeyObserver obs) Removes the supplied key observer from the list of observers to be notified of all key events while the keyboard manager is active.
void	reset() Resets the keyboard manager, clearing any target and key translator in use and disabling the keyboard manager if it is currently active.
void	setEnabled(boolean enabled) Sets whether the keyboard manager processes keyboard input.
void	setRepeatDelay(long delay) Sets the expected delay in milliseconds between each key press/release event the keyboard manager should expect to receive while a key is repeating.
void	setTarget(JComponent target, KeyTranslator xlate) Initializes the keyboard manager with the supplied target component and key translator and disables the keyboard manager if it is currently active.
void	windowGainedFocus(WindowEvent e)
void	windowLostFocus(WindowEvent e)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEBUG_EVENTS

protected static final boolean DEBUG_EVENTS

Whether to output debugging info for individual key events.

See Also:

Constant Field Values

DEBUG_INTERVAL

protected static final boolean DEBUG_INTERVAL

Whether to output debugging info for interval callbacks.

See Also:

Constant Field Values

DEFAULT_REPEAT_DELAY

protected static final long DEFAULT_REPEAT_DELAY

The default repeat delay.

See Also:

Constant Field Values

_repeatDelay

protected long _repeatDelay

The expected approximate milliseconds between each key release/press event while the key is being auto-repeated.

_keys

protected HashIntMap<KeyboardManager.KeyInfo> _keys

A hashtable mapping key codes to KeyboardManager.KeyInfo objects.

_chars

protected HashMap<Character,KeyboardManager.KeyInfo> _chars

A hashtable mapping characters to KeyboardManager.KeyInfo objects.

_focus

protected boolean _focus

Whether the keyboard manager currently has the keyboard focus.

_enabled

protected boolean _enabled

Whether the keyboard manager is accepting keyboard input.

_window

protected Window _window

The window containing our target component whose focus events we care to observe, or null if we're not observing a window.

_target

protected JComponent _target

The component that receives keyboard events and that we associate with posted controller commands.

_xlate

protected KeyTranslator _xlate

The translator that maps keyboard events to controller commands.

_observers

protected ObserverList<KeyboardManager.KeyObserver> _observers

The list of key observers.

_keyOp

protected KeyboardManager.KeyObserverOp _keyOp

The operation used to notify observers of actual key events.

_nativeRepeat

protected boolean _nativeRepeat

Whether native key auto-repeating was enabled when the keyboard manager was last enabled.

_shouldDisableNativeRepeat

protected boolean _shouldDisableNativeRepeat

Whether we want to disable native key auto-repeating. If we're dealing with wacky keys that send only key typed events, we might need to fall back to letting that happen so things work right.

_debugTyping

protected static RuntimeAdjust.BooleanAdjust _debugTyping

A debug hook that toggles excessive logging to help debug keyTyped behavior.

Constructor Detail

KeyboardManager

public KeyboardManager()

Constructs a keyboard manager that is initially disabled. The keyboard manager should not be enabled until it has been supplied with a target component and translator via setTarget(javax.swing.JComponent, com.threerings.util.KeyTranslator).

Method Detail

reset

public void reset()

Resets the keyboard manager, clearing any target and key translator in use and disabling the keyboard manager if it is currently active.

setTarget

public void setTarget(JComponent target,
                      KeyTranslator xlate)

Initializes the keyboard manager with the supplied target component and key translator and disables the keyboard manager if it is currently active.

Parameters:

target - the component whose keyboard events are to be observed.

xlate - the key translator used to map keyboard events to controller action commands.

registerKeyObserver

public void registerKeyObserver(KeyboardManager.KeyObserver obs)

Registers a key observer that will be notified of all key events while the keyboard manager is active.

removeKeyObserver

public void removeKeyObserver(KeyboardManager.KeyObserver obs)

Removes the supplied key observer from the list of observers to be notified of all key events while the keyboard manager is active.

setEnabled

public void setEnabled(boolean enabled)

Sets whether the keyboard manager processes keyboard input.

setRepeatDelay

public void setRepeatDelay(long delay)

Sets the expected delay in milliseconds between each key press/release event the keyboard manager should expect to receive while a key is repeating.

releaseAllKeys

public void releaseAllKeys()

Releases all keys and ceases any hot repeating action that may be going on.

gainedFocus

protected void gainedFocus()

Called when the keyboard manager gains focus and should begin handling keys again if it was previously enabled.

lostFocus

protected void lostFocus()

Called when the keyboard manager loses focus and should cease handling keys.

dispatchKeyEvent

public boolean dispatchKeyEvent(KeyEvent e)

Specified by:

dispatchKeyEvent in interface KeyEventDispatcher

keyPressed

protected boolean keyPressed(KeyEvent e)

Called when Swing notifies us that a key has been pressed while the keyboard manager is active.

Returns:

true to swallow the key event

keyTyped

protected boolean keyTyped(KeyEvent e)

Called when Swing notifies us that a key has been typed while the keyboard manager is active.

Returns:

true to swallow the key event

keyReleased

protected boolean keyReleased(KeyEvent e)

Called when Swing notifies us that a key has been released while the keyboard manager is active.

Returns:

true to swallow the key event

notifyObservers

protected void notifyObservers(int id,
                               int keyCode,
                               long timestamp)

Notifies all registered key observers of the supplied key event. This method provides a thread-safe manner in which to notify the observers, which is necessary since the KeyboardManager.KeyInfo objects do various antics from the interval manager thread whilst we may do other notification from the AWT thread when normal key events are handled.

logKey

protected void logKey(String msg,
                      KeyEvent e)

Logs the given message and key.

ancestorAdded

public void ancestorAdded(AncestorEvent e)

Specified by:

ancestorAdded in interface AncestorListener

ancestorMoved

public void ancestorMoved(AncestorEvent e)

Specified by:

ancestorMoved in interface AncestorListener

ancestorRemoved

public void ancestorRemoved(AncestorEvent e)

Specified by:

ancestorRemoved in interface AncestorListener

windowGainedFocus

public void windowGainedFocus(WindowEvent e)

Specified by:

windowGainedFocus in interface WindowFocusListener

windowLostFocus

public void windowLostFocus(WindowEvent e)

Specified by:

windowLostFocus in interface WindowFocusListener