gumbo.graphic.input.impl.swing
Class SwingKeyboardSensor

java.lang.Object
  |
  +--gumbo.util.AbstractDisposable
        |
        +--gumbo.graphic.input.AbstractKeyboardSensor
              |
              +--gumbo.graphic.input.impl.swing.SwingKeyboardSensor

All Implemented Interfaces:

Disposable, KeyboardSensor

public class SwingKeyboardSensor

extends AbstractKeyboardSensor

An AWT/Swing keyboard sensor. Sensor targets must have a Component graphic. Senses keyboard events when a target has focus. Focus can transfer to the target directly, through manual focus (key click, focus navigation), or indirectly, using getKeyboardFocusIn(). The key state is cleared but not output upon loss of focus, and it is set according to getKeyboardFocusKeysIn() upon request or gain of focus.

Swing does not allow monitoring of the keyboard directly. Instead, each target graphic with keyboard focus must be monitored for key inputs. Also, Swing does not provide the keyboard state upon gaining focus. As such, this class uses getKeyboardFocusKeysIn() for the initial state when a critical event occurs (target enetered, button changed) prior to requesting or gaining focus (see SwingMouseSensor). To be safe, it also recognizes key releases without a prior corresponding key press.

Version:

$Revision: 1.3 $

Author:

Jon Barrilleaux (jonb@jmbaai.com) of JMB and Associates Inc.

Constructor Summary

SwingKeyboardSensor()
Creates an instance, with keyRepeat false.

SwingKeyboardSensor(boolean keyRepeat)
Creates an instance.

Method Summary

protected void	addedSensorTarget(SpaceNode target) Throws an exception if target graphic not a Component.
BooleanField.EventOut	getKeyboardActiveOut() Sends an event when the sensor starts or stops being active on a given sensor target.
BooleanField.EventIn	getKeyboardEnableIn() Enables/disables this sensor.
SpaceNodeField.EventIn	getKeyboardFocusIn() Tries to gain keyboard focus for a sensor target, but only if the target's window is active.
CollectionField.EventIn	getKeyboardFocusKeysIn() The state (KeyboardSensors.KEY_???) of the keyboard keys before keyboard focus is requested or gained.
BooleanField.EventIn	getKeyboardPickActiveIn() If going true while this sensor is active, resends the keyboard keys.
SpaceNodeField.EventOut	getKeyboardSpaceOut() Sends an event when the sensor starts being active in a new sensor target space.
protected void	implDispose() Called by dispose() before the disposed flag is set, when it is time for subclasses to dispose themselves.
protected void	removedSensorTarget(SpaceNode target) Called by the system when a non-missing target is removed, after updating the graphic map.

Methods inherited from class gumbo.graphic.input.AbstractKeyboardSensor

addKeyboardTarget, getGraphicMap, getKeyboardCharOut, getKeyboardKeysOut, getKeyState, isKeyRepeat, removeKeyboardTarget

Methods inherited from class gumbo.util.AbstractDisposable

dispose, isDisposed

Methods inherited from class java.lang.Object

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

Methods inherited from interface gumbo.util.Disposable

dispose, isDisposed

Constructor Detail

SwingKeyboardSensor

public SwingKeyboardSensor()

Creates an instance, with keyRepeat false.

SwingKeyboardSensor

public SwingKeyboardSensor(boolean keyRepeat)

Creates an instance. Master constructor.

Parameters:

keyRepeat - If false, a key out event is sent only if its data value changes. Does not affect character out.

Method Detail

getKeyboardFocusKeysIn

public CollectionField.EventIn getKeyboardFocusKeysIn()

The state (KeyboardSensors.KEY_???) of the keyboard keys before keyboard focus is requested or gained. This is needed since, in Swing, there is no way to obtain the key state upon gaining focus. When starting activation the key state is updated with the last valid value of this field before the key state is output. Should be routed from SwingMouseSensor.getMouseEnteredKeysOut() if mouse over triggers keyboard focus. Empty state if null.

getKeyboardPickActiveIn

public BooleanField.EventIn getKeyboardPickActiveIn()

If going true while this sensor is active, resends the keyboard keys. This is needed for "click through" where picking may be activated as a result of a window becoming active (and gaining focus) as a result of a mouse click. Only needed if the picker's active input is not directly controlled by this keyboard sensor, in which case it should be relayed to this input.

addedSensorTarget

protected void addedSensorTarget(SpaceNode target)

Throws an exception if target graphic not a Component.

Specified by:

addedSensorTarget in class AbstractKeyboardSensor

Parameters:

target - Reference to the target. Never null.

removedSensorTarget

protected void removedSensorTarget(SpaceNode target)

Description copied from class: AbstractKeyboardSensor

Called by the system when a non-missing target is removed, after updating the graphic map.

Specified by:

removedSensorTarget in class AbstractKeyboardSensor

Parameters:

target - Reference to the target. Never null.

getKeyboardEnableIn

public BooleanField.EventIn getKeyboardEnableIn()

Description copied from interface: KeyboardSensor

Enables/disables this sensor. When disabled, status outputs (active) will go false if not already false. While disabled, keyboard inputs are ignored and there are no outputs. The default is true.

getKeyboardFocusIn

public SpaceNodeField.EventIn getKeyboardFocusIn()

Description copied from interface: KeyboardSensor

Tries to gain keyboard focus for a sensor target, but only if the target's window is active. Typically used to focus the keyboard while a mouse sensor is active in the space (see MouseSensor.getMouseSpaceOut()). Ignored if the target space is unrecognized.

getKeyboardSpaceOut

public SpaceNodeField.EventOut getKeyboardSpaceOut()

Description copied from interface: KeyboardSensor

Sends an event when the sensor starts being active in a new sensor target space. Sent after active out but before any other output events. Never null while active.

getKeyboardActiveOut

public BooleanField.EventOut getKeyboardActiveOut()

Description copied from interface: KeyboardSensor

Sends an event when the sensor starts or stops being active on a given sensor target. While true, the sensor is actively sending events. Will go true before and false after all other output eventss. Should reflect the true system status as to whether or not the sensor target has keyboard focus.

implDispose

protected void implDispose()

Description copied from class: AbstractDisposable

Called by dispose() before the disposed flag is set, when it is time for subclasses to dispose themselves. Implentors should disconnect and/or dispose any relations (while the object is still valid), then null out any external references, and then call super.implDispose() to assure that the super class is disposed of properly.

Specified by:

implDispose in class AbstractDisposable