vona.ui

Class ActionMapper

java.lang.Object

vona.ui.ActionMapper

@ThreadSafe
public class ActionMapper
extends java.lang.Object

Configurable prioritized mappings from user key and mouse actions to handlers.

An ActionMapper maintains zero or more ordered ActionMapper.ActionMaps which map action specs to ActionMapper.Actions. The set of maps and the content of each map are mutable, and maps and actions can be individually disabled/enabled.

An ActionMapper can be added to zero or more AWT components, and itself can be enabled/disabled.

The only effect of disabling an ActionMapper.Action, ActionMapper.ActionMap, or ActionMapper is that corresponding ActionMapper.Action.run(java.lang.String, java.awt.Component, vona.ui.ActionMapper.ComponentState) calls are not made.

Normal action specs (see below for wildcard specs) are case-sensitive strings of the pattern

[S-][C-][A-]{ks|{1|2|3}-mc|[1-][2-][3-]mm|mw}

where

• the [S-][C-][A-] prefix indicates the state of the Shift, Ctrl, and Alt modifiers to match, respectively; the presence of the character indicates that the corresponding key must be pressed, and the absence of the character indicates that the corresponding key must not be pressed;
• ks, if included, is a key spec to match, which is either
  • the string returned by KeyEvent.getKeyText() for the desired key code, converted to lower case and with spaces replaced by underscores
  • OR, the string equivalent of the char returned by KeyEvent.getKeyChar(), in which case the S- prefix is not allowed;
• i-mc matches a click of mouse button i;
• mm matches a mouse move while holding the indicated, possibly empty, set of buttons;
• mw matches a mouse wheel move.

There are three wildcard action specs:

any other key|*-mc|*-mm

If present, these match any keypress, mouse click, or mouse move action, respectively, that is not matched by any non-wildcard spec.

A user key or mouse action on any attached AWT component generates an action spec which is looked up in each ActionMapper.ActionMap in order. The first enabled ActionMapper.Action found, if any, is executed, in the AWT event thread. ActionMapper.Actions in earlier maps therefore take priority over those with the same spec in later maps. This can be used to implement e.g. layered input modes and submodes.

Synchronization Policies

This class is designed to be thread safe:

• ActionMapper.Action.run(java.lang.String, java.awt.Component, vona.ui.ActionMapper.ComponentState) is always called from within the AWT event thread, and the passed ActionMapper.ComponentStates (from componentStateMap) are also confined to the AWT event thread.
• The set of actionMaps is internally synchronized.
• The contents of each ActionMapper.ActionMap are guarded by that map.
• The only mutable state of an ActionMapper.Action is ActionMapper.Action.enabled, which is volatile.

TBD

• TBD workaround for bug ID 4153069 (open) "keyReleased behaviour incorrect" to normalize/neutralize platform typematic systems (cf RXSInteractor), or wait for official bugfix
• TBD refactor RXSInteractor to use ActionMapper

Copyright (C) 2007 Marsette A. Vona, III

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

Author:

Marsette (Marty) A. Vona, III

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	ActionMapper.Action An action.
static class	ActionMapper.ActionMap a map taking action specs to ActionMapper.Actions
static class	ActionMapper.ApplyingAction Generic ActionMapper.Action impl that delegates to an object implementing an apply(Object[]) method.
static class	ActionMapper.ComponentState Collects the state of an AWT Component.

Field Summary

Fields

Modifier and Type	Field and Description
protected java.util.List<ActionMapper.ActionMap>	actionMaps The currently installed ActionMapper.ActionMaps, in insertion order from highest to lowest priority.
protected java.awt.event.ComponentListener	componentListener listener for ComponentEvents
protected java.util.Map<java.awt.Component,ActionMapper.ComponentState>	componentStateMap map from AWT Component to ActionMapper.ComponentState
private static java.lang.String	cvsid
static int	DBG_ALL dbgFlags
static int	DBG_COMPONENT_STATE dbgFlags
static int	DBG_ENABLED dbgFlags
static int	DBG_MOUSE_MOTION dbgFlags
int	dbgFlags enable for debug spew
boolean	enabled enable for this entire ActionMapper
static int	ET_KEYPRESS event type indices
static int	ET_MOUSE_CLICK event type indices
static int	ET_MOUSE_MOTION event type indices
static int	ET_MOUSE_WHEEL event type indices
static java.lang.String[]	EVENT_TYPE_NAME event type names indexed by event type
static java.util.Map<java.lang.Integer,java.lang.String>	eventTypeFromID mapping from AWT event ID to human readable event type
protected java.awt.event.FocusListener	focusListener listener for FocusEvents
protected java.awt.event.KeyListener	keyListener listener for KeyEvents
protected boolean[]	mostRecentActionResult The most recent action result for each event type.
protected java.lang.String[]	mostRecentActionSpec The most recently handled action spec for each event type, or null if none.
protected java.lang.ref.WeakReference<java.awt.Component>[]	mostRecentComponent The most recently handled component for each event type, or null if none.
protected int[]	mostRecentEventID The most recent event ID for each event type for each event type.
protected long[]	mostRecentTimestamp The most recent timestamp for each event type.
protected java.awt.event.MouseListener	mouseListener listener for MouseEvents
protected java.awt.event.MouseMotionListener	mouseMotionListener listener for MouseEvents related to motion
protected java.awt.event.MouseWheelListener	mouseWheelListener listener for MouseWheelEvents
static int	NUM_EVENT_TYPES number of event types
static java.lang.String[]	WILDCARD_SPEC wildcard action specs indexed by event type

Constructor Summary

Constructors

Constructor and Description
ActionMapper()

Method Summary

Methods

Modifier and Type	Method and Description
boolean	addComponent(java.awt.Component c) Add an AWT Component to the listen list.
void	dump() covers dumpActions()
void	dump(java.io.PrintStream s) covers dumpActions(PrintStream)
void	dumpActions() Covers dumpActions(PrintStream, String, boolean), uses default nomenclature, System.out, and sorts.
void	dumpActions(boolean sort) Covers dumpActions(PrintStream, String, boolean), uses default nomenclature and System.out.
void	dumpActions(java.io.PrintStream s) Covers dumpActions(PrintStream, String, boolean), uses default nomenclature and sorts.
void	dumpActions(java.io.PrintStream s, boolean sort) Covers dumpActions(PrintStream, String, boolean), uses default nomenclature.
void	dumpActions(java.io.PrintStream s, java.lang.String actionMapName, boolean sort) Dump all and only enabled ActionMapper.Actions.
void	dumpActions(java.lang.String actionMapName) Covers dumpActions(PrintStream, String, boolean), uses System.out and sorts.
void	dumpActions(java.lang.String actionMapName, boolean sort) Covers dumpActions(PrintStream, String, boolean), uses System.out.
static java.lang.String	getBaseSpec(java.lang.String spec) extract the base spec
static int	getEventType(java.lang.String spec) get the event type for spec
protected static java.lang.String	getKeyText(int code) Fix KeyEvent.getKeyText() on OS X.
ActionMapper.ActionMap	getMap(int index) get the map at the specified index
boolean	handleAction(java.lang.String baseSpec, java.awt.Component c, ActionMapper.ComponentState s, int eventID, long timestamp, int eventType) Covers handleAction(String, Component, ComponentState, int, long, int, boolean), does not ignore shift down.
boolean	handleAction(java.lang.String baseSpec, java.awt.Component c, ActionMapper.ComponentState s, int eventID, long timestamp, int eventType, boolean ignoreShiftDown) Add modifier specs to make an action spec from baseSpec, lookupAction(java.lang.String, boolean), and execute the ActionMapper.Action, if any.
protected boolean	handleKeyReleased(java.awt.Component c, ActionMapper.ComponentState s, int code, int eventID, long timestamp) handleAction(java.lang.String, java.awt.Component, vona.ui.ActionMapper.ComponentState, int, long, int, boolean) for a key release
protected boolean	handleKeyTyped(java.awt.Component c, ActionMapper.ComponentState s, char ch, int eventID, long timestamp) handleAction(java.lang.String, java.awt.Component, vona.ui.ActionMapper.ComponentState, int, long, int, boolean) for a key typed
protected boolean	handleMouseClick(java.awt.Component c, ActionMapper.ComponentState s, int btn, int eventID, long timestamp) handleAction(java.lang.String, java.awt.Component, vona.ui.ActionMapper.ComponentState, int, long, int, boolean) for a mouse click
protected boolean	handleMouseMove(java.awt.Component c, ActionMapper.ComponentState s, int eventID, long timestamp) handleAction(java.lang.String, java.awt.Component, vona.ui.ActionMapper.ComponentState, int, long, int, boolean) for a mouse move
protected boolean	handleMouseWheelMove(java.awt.Component c, ActionMapper.ComponentState s, int eventID, long timestamp) handleAction(java.lang.String, java.awt.Component, vona.ui.ActionMapper.ComponentState, int, long, int, boolean) for a mouse wheel move
static boolean	isWildcard(java.lang.String spec) check if spec is a wildcard
ActionMapper.Action	lookupAction(java.lang.String spec) lookupAction(String, boolean), use wildcards
ActionMapper.Action	lookupAction(java.lang.String spec, boolean useWildcards) Match an action spec to the corresponding ActionMapper.Action.
protected ActionMapper.ComponentState	lookupComponentState(java.awt.Component c) Fetch the ActionMapper.ComponentState for AWT Component c from componentStateMap.
int	numComponents() get the current number of components
int	numMaps() get the current number of maps
ActionMapper.ActionMap	popMap() Remove the first (i.e.
void	pushMap(ActionMapper.ActionMap m) Add an ActionMapper.ActionMap as the first (i.e.
boolean	removeComponent(java.awt.Component c) Remove an AWT Component from the listen list.

Methods inherited from class java.lang.Object

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

Field Detail

cvsid

private static final java.lang.String cvsid

See Also:

Constant Field Values

DBG_ENABLED

public static final int DBG_ENABLED

dbgFlags

See Also:

Constant Field Values

DBG_MOUSE_MOTION

public static final int DBG_MOUSE_MOTION

dbgFlags

See Also:

Constant Field Values

DBG_COMPONENT_STATE

public static final int DBG_COMPONENT_STATE

dbgFlags

See Also:

Constant Field Values

DBG_ALL

public static final int DBG_ALL

dbgFlags

See Also:

Constant Field Values

dbgFlags

public volatile int dbgFlags

enable for debug spew

enabled

public volatile boolean enabled

enable for this entire ActionMapper

ET_KEYPRESS

public static final int ET_KEYPRESS

event type indices

See Also:

Constant Field Values

ET_MOUSE_MOTION

public static final int ET_MOUSE_MOTION

event type indices

See Also:

Constant Field Values

ET_MOUSE_CLICK

public static final int ET_MOUSE_CLICK

event type indices

See Also:

Constant Field Values

ET_MOUSE_WHEEL

public static final int ET_MOUSE_WHEEL

event type indices

See Also:

Constant Field Values

NUM_EVENT_TYPES

public static final int NUM_EVENT_TYPES

number of event types

See Also:

Constant Field Values

EVENT_TYPE_NAME

public static final java.lang.String[] EVENT_TYPE_NAME

event type names indexed by event type

WILDCARD_SPEC

public static final java.lang.String[] WILDCARD_SPEC

wildcard action specs indexed by event type

eventTypeFromID

public static final java.util.Map<java.lang.Integer,java.lang.String> eventTypeFromID

mapping from AWT event ID to human readable event type

mostRecentComponent

protected java.lang.ref.WeakReference<java.awt.Component>[] mostRecentComponent

The most recently handled component for each event type, or null if none.

Confined to the GUI event thread.

mostRecentActionSpec

protected java.lang.String[] mostRecentActionSpec

The most recently handled action spec for each event type, or null if none.

Confined to the GUI event thread.

mostRecentEventID

protected int[] mostRecentEventID

The most recent event ID for each event type for each event type.

Confined to the GUI event thread.

mostRecentTimestamp

protected long[] mostRecentTimestamp

The most recent timestamp for each event type.

Confined to the GUI event thread.

mostRecentActionResult

protected boolean[] mostRecentActionResult

The most recent action result for each event type.

Confined to the GUI event thread.

actionMaps

protected final java.util.List<ActionMapper.ActionMap> actionMaps

The currently installed ActionMapper.ActionMaps, in insertion order from highest to lowest priority.

componentStateMap

protected final java.util.Map<java.awt.Component,ActionMapper.ComponentState> componentStateMap

map from AWT Component to ActionMapper.ComponentState

componentListener

protected final java.awt.event.ComponentListener componentListener

listener for ComponentEvents

focusListener

protected final java.awt.event.FocusListener focusListener

listener for FocusEvents

keyListener

protected final java.awt.event.KeyListener keyListener

listener for KeyEvents

mouseListener

protected final java.awt.event.MouseListener mouseListener

listener for MouseEvents

mouseMotionListener

protected final java.awt.event.MouseMotionListener mouseMotionListener

listener for MouseEvents related to motion

mouseWheelListener

protected final java.awt.event.MouseWheelListener mouseWheelListener

listener for MouseWheelEvents

Constructor Detail

ActionMapper

public ActionMapper()

Method Detail

addComponent

public boolean addComponent(java.awt.Component c)

Add an AWT Component to the listen list.

Returns:

true iff c was not already present

removeComponent

public boolean removeComponent(java.awt.Component c)

Remove an AWT Component from the listen list.

Returns:

true iff c was present

pushMap

public void pushMap(ActionMapper.ActionMap m)

Add an ActionMapper.ActionMap as the first (i.e. highest priority) map in the list.

popMap

public ActionMapper.ActionMap popMap()

Remove the first (i.e. highest priority) ActionMapper.ActionMap, if any.

Returns:

the removed map, or null if none

numMaps

public int numMaps()

get the current number of maps

getMap

public ActionMapper.ActionMap getMap(int index)

get the map at the specified index

numComponents

public int numComponents()

get the current number of components

lookupAction

public ActionMapper.Action lookupAction(java.lang.String spec,
                               boolean useWildcards)

Match an action spec to the corresponding ActionMapper.Action.

See class header doc for detailed semantics.

Returns:

the Action corresponding to spec or null if none

lookupAction

public ActionMapper.Action lookupAction(java.lang.String spec)

lookupAction(String, boolean), use wildcards

dumpActions

public void dumpActions(java.io.PrintStream s,
               java.lang.String actionMapName,
               boolean sort)

Dump all and only enabled ActionMapper.Actions.

An ActionMapper.Action is enabled only if its own enable flag, the enable flag of its enclosing ActionMapper.ActionMap, and the enabled flag of this ActionMapper are all set.

If more than one ActionMapper.Action is enabled for a given spec then only the highest-priority ActionMapper.Action is dumped.

Parameters:

actionMapName - if non-null then this is the application-specific nomenclature for an ActionMapper.ActionMap (e.g. "mode"); if null then the default nomenclature "action map" is used

sort - whether to sort the actions by insertion order (sort = false) or using ActionMapper.Action.COMPARATOR (sort = true)

dumpActions

public void dumpActions(java.io.PrintStream s,
               boolean sort)

Covers dumpActions(PrintStream, String, boolean), uses default nomenclature.

dumpActions

public void dumpActions(java.io.PrintStream s)

Covers dumpActions(PrintStream, String, boolean), uses default nomenclature and sorts.

dump

public void dump(java.io.PrintStream s)

covers dumpActions(PrintStream)

dumpActions

public void dumpActions(java.lang.String actionMapName,
               boolean sort)

Covers dumpActions(PrintStream, String, boolean), uses System.out.

dumpActions

public void dumpActions(java.lang.String actionMapName)

Covers dumpActions(PrintStream, String, boolean), uses System.out and sorts.

dumpActions

public void dumpActions(boolean sort)

Covers dumpActions(PrintStream, String, boolean), uses default nomenclature and System.out.

dumpActions

public void dumpActions()

Covers dumpActions(PrintStream, String, boolean), uses default nomenclature, System.out, and sorts.

dump

public void dump()

covers dumpActions()

lookupComponentState

protected ActionMapper.ComponentState lookupComponentState(java.awt.Component c)

Fetch the ActionMapper.ComponentState for AWT Component c from componentStateMap.

Issues a warning if the state is not found.

Sets the component dimensions if unset.

Returns:

the ActionMapper.ComponentState corresponding to c or null if not found

getKeyText

protected static java.lang.String getKeyText(int code)

Fix KeyEvent.getKeyText() on OS X.

handleKeyReleased

protected boolean handleKeyReleased(java.awt.Component c,
                        ActionMapper.ComponentState s,
                        int code,
                        int eventID,
                        long timestamp)

handleAction(java.lang.String, java.awt.Component, vona.ui.ActionMapper.ComponentState, int, long, int, boolean) for a key release

handleKeyTyped

protected boolean handleKeyTyped(java.awt.Component c,
                     ActionMapper.ComponentState s,
                     char ch,
                     int eventID,
                     long timestamp)

handleAction(java.lang.String, java.awt.Component, vona.ui.ActionMapper.ComponentState, int, long, int, boolean) for a key typed

handleMouseClick

protected boolean handleMouseClick(java.awt.Component c,
                       ActionMapper.ComponentState s,
                       int btn,
                       int eventID,
                       long timestamp)

handleAction(java.lang.String, java.awt.Component, vona.ui.ActionMapper.ComponentState, int, long, int, boolean) for a mouse click

handleMouseMove

protected boolean handleMouseMove(java.awt.Component c,
                      ActionMapper.ComponentState s,
                      int eventID,
                      long timestamp)

handleAction(java.lang.String, java.awt.Component, vona.ui.ActionMapper.ComponentState, int, long, int, boolean) for a mouse move

handleMouseWheelMove

protected boolean handleMouseWheelMove(java.awt.Component c,
                           ActionMapper.ComponentState s,
                           int eventID,
                           long timestamp)

handleAction(java.lang.String, java.awt.Component, vona.ui.ActionMapper.ComponentState, int, long, int, boolean) for a mouse wheel move

handleAction

public boolean handleAction(java.lang.String baseSpec,
                   java.awt.Component c,
                   ActionMapper.ComponentState s,
                   int eventID,
                   long timestamp,
                   int eventType,
                   boolean ignoreShiftDown)

Add modifier specs to make an action spec from baseSpec, lookupAction(java.lang.String, boolean), and execute the ActionMapper.Action, if any.

Returns:

true iff ActionMapper.Action.run(java.lang.String, java.awt.Component, vona.ui.ActionMapper.ComponentState) returns true and ActionMapper.Action.consuming. false if no ActionMapper.Action was found, ActionMapper.Action.run(java.lang.String, java.awt.Component, vona.ui.ActionMapper.ComponentState) returned false, ActionMapper.Action.consuming false, or if the action spec is a repeat of the most recent one but with a different event ID (this avoids duplication in cases where a single physical action triggers multiple events, such as a keypress that triggers both KeyReleased and KeyTyped events)

handleAction

public boolean handleAction(java.lang.String baseSpec,
                   java.awt.Component c,
                   ActionMapper.ComponentState s,
                   int eventID,
                   long timestamp,
                   int eventType)

Covers handleAction(String, Component, ComponentState, int, long, int, boolean), does not ignore shift down.

getBaseSpec

public static java.lang.String getBaseSpec(java.lang.String spec)

extract the base spec

isWildcard

public static boolean isWildcard(java.lang.String spec)

check if spec is a wildcard

getEventType

public static int getEventType(java.lang.String spec)

get the event type for spec