Configurable-keys

Simplify making AWT mouse-handlers configurable. Works along the lines of the InputMap / ActionMap mechanism. The syntax for defining key and mouse "triggers" is described in the InputTrigger-syntax wiki page InputTrigger-syntax wiki page. They are also repeated below.

Overview

ui-behaviour is a library for binding behaviours by keys or mouse-actions. The idea is similar to Swing's InputMap/ActionMap framework. The difference is that actions are atomic while behaviours (possibly) stretch over a period of time. For example, a DragBehaviour is initialized (e.g., with a mouse click) at certain coordinates, goes through a series of coordinate updates, and then ends (when the mouse is released).

The combination of modifiers, keys, mouse buttons etc. that initiates a behaviour is called a "trigger" and is constructed from a string description.

The basic syntax for a trigger description is a sequence of modifier and key names separated by whitespace. Examples are "SPACE", "button1", "shift alt scroll", and "ctrl F G".

Additionally, one can specify a combination of modifiers, keys, mouse buttons etc. that should be ignored when triggering the behaviour. This is a another sequence of modifier and key names separated from the trigger description by "|". For example, "ctrl button1 | shift alt" is triggered by pressing the left mouse-button while holding the ctrl key. If the shift and/or alt key are pressed simultaneously, the trigger still matches. To ignore all other modifiers and keys, the special name "all" is used. So, "A | all" is a trigger that matches when the A key is pressed, regardless which other modifiers, keys, or buttons are active at the same time.

Chaining principle

In Swing, a JComponent has an InputMap. Each InputMap can have a parent, and if a mapping for a given key is not found in the InputMap, it asks the parent.

For BigDataViewer, we thought that this concept is nice for adding InputMap/ActionMap pairs with related actions to the viewer. For example one map with navigation shortcuts, then one map for bookmarking, and then each user extension could also create its own InputMap/ActionMap pair and just chain it to the existing maps.

The slight complication with this is, that if you have a situation like this:

 component → map2 → map1
 

and you want to add another one, "map3", it should look like this:

 component → map3 → map2 → map1
 

So, "map3" should be inserted between "component" and "map2".

This is resolved in ui-behaviours InputActionBindings by having a theInputMap/theActionMap pair that acts as an empty leaf map with exchangeable parents. From the component side it always looks like

 component → theMap
 

and then internally the InputActionBindings maintains a list [map1, map2, ...] which is then assembled into a new chain whenever something changes. So

 theMap → map2 → map1
 

becomes

 theMap → map3 → map2 → map1
 

when "map3" is added.

And the behaviours framework doesn't have to care about the Swing particulars (e.g., actually each JComponent has 3 different inputmaps for different situations).

Blocking maps

On top of this, InputActionBindings adds a few convenience features.

For every map pair that you append to InputActionBindings you specify a unique name that can later be used to remove the map pair again.

E.g., if map2 would have the name "bookmarking", then

 InputActionBindings.removeInputMap( "bookmarking" )
 

would reassemble

 theMap → map3 → map2 → map1
 

to

 theMap → map3 → map1
 

Finally, given that all maps have unique names, when you add a map you can specify a set of other maps to block.

For example, let's say that you want to temporarily add your own specific keys that maybe conflict with the bookmarking keys.

Starting from this situation:

 theMap → map3 → map2 → map1
 

the following

 InputActionBindings.addInputMap( map4, "myMap", "navigation", "bookmarking" )
 // "myMap" blocks "navigation", "bookmarking"
 

will result in

 theMap → map4 → map3
 

that is, map1 and map2 were blocked.

However, InputActionsBindings still knows about map1 and map2. Once the blocking "myMap" is removed, they will be reinstated.

As a concrete example: this whole machinery is used for bookmarking in BDV. You set a bookmark by pressing "shift B" and then some other key, that is the name for the bookmark. For example, you can press "shift B" "1" to set a bookmark named "1".

After you press "shift B", a temporary inputmap is installed that blocks all other inputmaps. So "1" will not trigger switching to bdv source 1. After the bookmark name "1" is received, the temporary inputmap is removed again.

For Behaviours, the chaining and blocking concepts are exactly the same

Modifier names.

The following modifiers can be used:

• ctrl
• alt
• altGraph
• shift
• meta
• win (the windows key)
• double-click (The trigger matches a double-click. This can include "double-clicks" on keys, e.g., shift double-click A works as expected.)

Mouse buttons and scrolling.

• button1 (left mouse button)
• button2 (middle mouse button)
• button3 (right mouse button)
• scroll (The trigger matches scroll events (both horizontal and vertical). Additional keys and modifiers may be present, e.g., shift A scroll matches when scrolling while pressing the shift and A keys. This modifier can only be used to trigger ScrollBehaviours.)

Key names.

Key names are the usual alphanumeric and function keys:

• A ... Z (Note that letter keys are always upper-case.)
• 0 ... 9
• F1 ... F24

Moreover the following special key names are supported (as in the AWTKeyStroke.getAWTKeyStroke(String) method):

• ENTER
• BACK_SPACE
• TAB
• CANCEL
• CLEAR
• COMPOSE
• PAUSE
• CAPS_LOCK
• ESCAPE
• SPACE
• PAGE_UP
• PAGE_DOWN
• END
• HOME
• BEGIN
• COMMA
• PERIOD
• SLASH
• SEMICOLON
• EQUALS
• OPEN_BRACKET
• BACK_SLASH
• CLOSE_BRACKET

These are names for cursor keys:

• LEFT
• UP
• RIGHT
• DOWN

These are names for the numpad keys:

• NUMPAD0 ... NUMPAD9
• MULTIPLY
• ADD
• SEPARATOR
• SUBTRACT
• DECIMAL
• DIVIDE
• DELETE
• NUM_LOCK
• SCROLL_LOCK