mxKeyHandler

Event handler that listens to keystroke events. This is not a singleton, however, it is normally only required once if the target is the document element (default).

This handler installs a key event listener in the topmost DOM node and processes all events that originate from descandants of <mxGraph.container> or from the topmost DOM node. The latter means that all unhandled keystrokes are handled by this object regardless of the focused state of the graph.

Example

The following example creates a key handler that listens to the delete key (46) and deletes the selection cells if the graph is enabled.

var keyHandler = new mxKeyHandler(graph);
keyHandler.bindKey(46, function(evt)
{
  if (graph.isEnabled())
  {
    graph.removeCells();
  }
});

Keycodes

See http://tinyurl.com/yp8jgl or http://tinyurl.com/229yqw for a list of keycodes or install a key event listener into the document element and print the key codes of the respective events to the console.

To support the Command key and the Control key on the Mac, the following code can be used.

keyHandler.getFunction = function(evt)
{
  if (evt != null)
  {
    return (mxEvent.isControlDown(evt) || (mxClient.IS_MAC && evt.metaKey)) ? this.controlKeys[evt.keyCode] : this.normalKeys[evt.keyCode];
  }

  return null;
};

Summary

mxKeyHandler	Event handler that listens to keystroke events.
Functions
mxKeyHandler	Constructs an event handler that executes functions bound to specific keystrokes.
Variables
graph	Reference to the mxGraph associated with this handler.
target	Reference to the target DOM, that is, the DOM node where the key event listeners are installed.
normalKeys	Maps from keycodes to functions for non-pressed control keys.
shiftKeys	Maps from keycodes to functions for pressed shift keys.
controlKeys	Maps from keycodes to functions for pressed control keys.
controlShiftKeys	Maps from keycodes to functions for pressed control and shift keys.
enabled	Specifies if events are handled.
Functions
isEnabled	Returns true if events are handled.
setEnabled	Enables or disables event handling by updating enabled.
bindKey	Binds the specified keycode to the given function.
bindShiftKey	Binds the specified keycode to the given function.
bindControlKey	Binds the specified keycode to the given function.
bindControlShiftKey	Binds the specified keycode to the given function.
isControlDown	Returns true if the control key is pressed.
getFunction	Returns the function associated with the given key event or null if no function is associated with the given event.
isGraphEvent	Returns true if the event should be processed by this handler, that is, if the event source is either the target, one of its direct children, a descendant of the <mxGraph.container>, or the mxGraph.cellEditor of the graph.
keyDown	Handles the event by invoking the function bound to the respective keystroke if mxGraph.isEnabled, isEnabled and isGraphEvent all return true for the given event and mxGraph.isEditing returns false.
escape	Hook to process ESCAPE keystrokes.
destroy	Destroys the handler and all its references into the DOM.

Functions

mxKeyHandler

function mxKeyHandler( graph,
target )

Constructs an event handler that executes functions bound to specific keystrokes.

Parameters

graph	Reference to the associated mxGraph.
target	Optional reference to the event target. If null, the document element is used as the event target, that is, the object where the key event listener is installed.

Variables

graph

mxKeyHandler.prototype.graph

Reference to the mxGraph associated with this handler.

target

mxKeyHandler.prototype.target

Reference to the target DOM, that is, the DOM node where the key event listeners are installed.

normalKeys

mxKeyHandler.prototype.normalKeys

Maps from keycodes to functions for non-pressed control keys.

shiftKeys

mxKeyHandler.prototype.shiftKeys

Maps from keycodes to functions for pressed shift keys.

controlKeys

mxKeyHandler.prototype.controlKeys

Maps from keycodes to functions for pressed control keys.

controlShiftKeys

mxKeyHandler.prototype.controlShiftKeys

Maps from keycodes to functions for pressed control and shift keys.

enabled

mxKeyHandler.prototype.enabled

Specifies if events are handled. Default is true.

Functions

isEnabled

mxKeyHandler.prototype.isEnabled = function()

Returns true if events are handled. This implementation returns enabled.

setEnabled

mxKeyHandler.prototype.setEnabled = function( enabled )

Enables or disables event handling by updating enabled.

Parameters

enabled

Boolean that specifies the new enabled state.

bindKey

mxKeyHandler.prototype.bindKey = function( code,
funct )

Binds the specified keycode to the given function. This binding is used if the control key is not pressed.

Parameters

code	Integer that specifies the keycode.
funct	JavaScript function that takes the key event as an argument.

bindShiftKey

mxKeyHandler.prototype.bindShiftKey = function( code,
funct )

Binds the specified keycode to the given function. This binding is used if the shift key is pressed.

Parameters

code	Integer that specifies the keycode.
funct	JavaScript function that takes the key event as an argument.

bindControlKey

mxKeyHandler.prototype.bindControlKey = function( code,
funct )

Binds the specified keycode to the given function. This binding is used if the control key is pressed.

Parameters

code	Integer that specifies the keycode.
funct	JavaScript function that takes the key event as an argument.

bindControlShiftKey

mxKeyHandler.prototype.bindControlShiftKey = function( code,
funct )

Binds the specified keycode to the given function. This binding is used if the control and shift key are pressed.

Parameters

code	Integer that specifies the keycode.
funct	JavaScript function that takes the key event as an argument.

isControlDown

mxKeyHandler.prototype.isControlDown = function( evt )

Returns true if the control key is pressed. This uses mxEvent.isControlDown.

Parameters

evt	Key event whose control key pressed state should be returned.

getFunction

mxKeyHandler.prototype.getFunction = function( evt )

Returns the function associated with the given key event or null if no function is associated with the given event.

Parameters

evt	Key event whose associated function should be returned.

isGraphEvent

mxKeyHandler.prototype.isGraphEvent = function( evt )

Returns true if the event should be processed by this handler, that is, if the event source is either the target, one of its direct children, a descendant of the <mxGraph.container>, or the mxGraph.cellEditor of the graph.

Parameters

evt	Key event that represents the keystroke.

keyDown

mxKeyHandler.prototype.keyDown = function( evt )

Handles the event by invoking the function bound to the respective keystroke if mxGraph.isEnabled, isEnabled and isGraphEvent all return true for the given event and mxGraph.isEditing returns false. If the graph is editing only the <enter> and escape cases are handled by calling the respective hooks.

Parameters

evt	Key event that represents the keystroke.

escape

mxKeyHandler.prototype.escape = function( evt )

Hook to process ESCAPE keystrokes. This implementation invokes mxGraph.stopEditing to cancel the current editing, connecting and/or other ongoing modifications.

Parameters

evt	Key event that represents the keystroke. Possible keycode in this case is 27 (ESCAPE).

destroy

mxKeyHandler.prototype.destroy = function()

Destroys the handler and all its references into the DOM. This does normally not need to be called, it is called automatically when the window unloads (in IE).