com.sun.electric.tool.user
Class KeyBindingManager

java.lang.Object
  extended by com.sun.electric.tool.user.KeyBindingManager

public class KeyBindingManager
extends java.lang.Object

The KeyBindingManager manages key bindings and their associated actions. It implements a KeyListener so it can be added as a key listener to any component.

The inputMap uses KeyStrokes as it's keys, and stores Objects of type Set. The Set contains Strings and the set will guarantee they are not repetead.

Each String is then used as a key into the HashMap actionMap to retrieve a KeyBindings object. Each key bindings object has a list of actions which can then be performed.

This model is similar to jawa.swing.InputMap and java.swing.ActionMap. However, secondary InputMaps allow two-stroke key bindings. Additionally, the KeybindingManager has been enveloped in an object which can then be inserted into the event hierarchy in different ways, instead of having to set a Component's InputMap and ActionMap.

Two-stroke bindings:

The KeyBindingManager has a HashMap prefixedInputMapMaps. A prefixStroke is used as a key to this table to obtain an inputMap (HashMap) based on the prefixStroke. From here it is the same as before with the inputMap and actionMap: A KeyStroke is then used as a key to find a List of Strings. The Strings are then used as a key into actionMap to get a KeyBindings object and perform the associated action. There is only one actionMap.

Author:
gainsley

Nested Class Summary
static class KeyBindingManager.KeyMaps
          Class that converts internal key mappings to InputMap and ActionMap objects.
 
Constructor Summary
KeyBindingManager(java.lang.String prefPrefix, java.util.prefs.Preferences prefs)
          Construct a new KeyBindingManager that can act as a KeyListener on a Component.
 
Method Summary
 void addActionListener(java.lang.String actionDesc, java.awt.event.ActionListener action)
          Add an action listener on actionDesc
 void addDefaultKeyBinding(java.lang.String actionDesc, KeyStrokePair pair)
          Adds a default KeyBinding.
 void addUserKeyBinding(java.lang.String actionDesc, KeyStrokePair pair)
          Adds a user specified KeyBindings.
 void deleteEmptyBindings()
          Check if there are any bindings that do not have any associated actions.
 void finished()
          Called when disposing of this manager, allows memory used to be reclaimed by removing static references to this.
 java.util.List<KeyBindings> getConflictingKeyBindings(KeyStrokePair pair)
          Get a list of KeyBindings that conflict with the key combo prefixStroke, stroke.
static java.util.List<KeyBindings> getConflictsAllManagers(KeyStrokePair pair)
          Get a list of conflicting key bindings from all KeyBindingManagers.
 boolean getEnabled(java.lang.String actionDesc)
          Get the enabled state of the action described by 'actionDesc'.
 KeyBindings getKeyBindings(java.lang.String actionDesc)
          Get bindings for action string
 KeyBindingManager.KeyMaps getKeyMaps()
          Method to return an object that has real InputMap and ActionMap objects.
 void printKeyBindings()
          Method to print existing KeyStrokes in std output for help
 boolean processKeyEvent(java.awt.event.KeyEvent e)
          Process a KeyEvent by finding what actionListeners should be activated as a result of the event.
 void removeKeyBinding(java.lang.String actionDesc, KeyStrokePair k)
          Removes a key binding from the active bindings, and writes new bindings set to preferences.
 void resetKeyBindings(java.lang.String actionDesc)
          Set actionDesc to use default KeyBindings
 void restoreSavedBindings(boolean initialCall)
          Restored saved bindings from preferences.
 void setEnabled(java.lang.String actionDesc, boolean b)
          Sets the enabled state of the action to 'b'.
 void setEventSource(java.lang.String actionDesc, java.lang.Object source)
          Set the faked event source of the KeyBindings object.
static boolean validKeyEvent(java.awt.event.KeyEvent e)
          Says whether or not KeyBindingManager will bind to this key event
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

KeyBindingManager

public KeyBindingManager(java.lang.String prefPrefix,
                         java.util.prefs.Preferences prefs)
Construct a new KeyBindingManager that can act as a KeyListener on a Component.

Method Detail

finished

public void finished()
Called when disposing of this manager, allows memory used to be reclaimed by removing static references to this.


printKeyBindings

public void printKeyBindings()
Method to print existing KeyStrokes in std output for help


validKeyEvent

public static boolean validKeyEvent(java.awt.event.KeyEvent e)
Says whether or not KeyBindingManager will bind to this key event

Parameters:
e - the KeyEvent
Returns:
true if the KeyBindingManager can bind to this event

processKeyEvent

public boolean processKeyEvent(java.awt.event.KeyEvent e)
Process a KeyEvent by finding what actionListeners should be activated as a result of the event. The keyBindingManager keeps one stroke of history so that two-stroke events can be distinguished.

Parameters:
e - the KeyEvent
Returns:
true if event consumed, false if not and nothing done.

getConflictsAllManagers

public static java.util.List<KeyBindings> getConflictsAllManagers(KeyStrokePair pair)
Get a list of conflicting key bindings from all KeyBindingManagers.

Parameters:
pair - the keystrokepair
Returns:
a list of conflicting KeyBindings from all KeyBindingManagers

addDefaultKeyBinding

public void addDefaultKeyBinding(java.lang.String actionDesc,
                                 KeyStrokePair pair)
Adds a default KeyBinding. If any keyBindings are found for k.actionDesc, those are used instead. Note that k cannot be null, but it's stroke and prefixStroke can be null. However, it's actionDesc and action must be valid.

Parameters:
actionDesc - the action description
pair - a key stroke pair

addUserKeyBinding

public void addUserKeyBinding(java.lang.String actionDesc,
                              KeyStrokePair pair)
Adds a user specified KeyBindings. Also adds it to stored user preference.

Parameters:
actionDesc - the action description
pair - a key stroke pair

addActionListener

public void addActionListener(java.lang.String actionDesc,
                              java.awt.event.ActionListener action)
Add an action listener on actionDesc

Parameters:
actionDesc - the action description
action - the action listener to add

removeKeyBinding

public void removeKeyBinding(java.lang.String actionDesc,
                             KeyStrokePair k)
Removes a key binding from the active bindings, and writes new bindings set to preferences.

Parameters:
actionDesc - the describing action
k - the KeyStrokePair to remove

resetKeyBindings

public void resetKeyBindings(java.lang.String actionDesc)
Set actionDesc to use default KeyBindings

Parameters:
actionDesc - the action description

getKeyBindings

public KeyBindings getKeyBindings(java.lang.String actionDesc)
Get bindings for action string

Parameters:
actionDesc - string describing action (KeyBinding.actionDesc)
Returns:
a KeyBindings object, or null.

getKeyMaps

public KeyBindingManager.KeyMaps getKeyMaps()
Method to return an object that has real InputMap and ActionMap objects.

Returns:
a KeyMaps object.

setEventSource

public void setEventSource(java.lang.String actionDesc,
                           java.lang.Object source)
Set the faked event source of the KeyBindings object. See KeyBindings.setEventSource() for details.

Parameters:
actionDesc - the action description used to find the KeyBindings object.
source - the object to use as the source of the event. (Event.getSource()).

getConflictingKeyBindings

public java.util.List<KeyBindings> getConflictingKeyBindings(KeyStrokePair pair)
Get a list of KeyBindings that conflict with the key combo prefixStroke, stroke. A conflict is registered if: an existing stroke is the same as prefixStroke; or an existing stroke is the same stroke (if prefixStroke is null); or an existing prefixStroke,stroke combo is the same as prefixStroke,stroke.

The returned list consists of newly created KeyBindings objects, not KeyBindings objects that are used in the key manager database. This is because not all KeyStrokePairs in an existing KeyBindings object will necessarily conflict. However, there may be more than one KeyStrokePair in a returned KeyBindings object from the list if more than one KeyStrokePair does actually conflict.

Returns an empty list if there are no conflicts.

Parameters:
pair - the KeyStrokePair
Returns:
a list of conflicting KeyBindings. Empty list if no conflicts.

setEnabled

public void setEnabled(java.lang.String actionDesc,
                       boolean b)
Sets the enabled state of the action to 'b'. If b is false, it disables all events that occur when actionDesc takes place. If b is true, it enables all resulting events.

Parameters:
actionDesc - the describing action
b - true to enable, false to disable.

getEnabled

public boolean getEnabled(java.lang.String actionDesc)
Get the enabled state of the action described by 'actionDesc'.

Parameters:
actionDesc - the describing action.
Returns:
true if the action is enabled, false otherwise.

deleteEmptyBindings

public void deleteEmptyBindings()
Check if there are any bindings that do not have any associated actions.


restoreSavedBindings

public void restoreSavedBindings(boolean initialCall)
Restored saved bindings from preferences. Usually called after menu has been created.