Clear Up
SharpKit Reference

KeyMap Class

Handles mapping key events to handling functions for an element or a Component. One KeyMap can be used for multiple actions.

A KeyMap must be configured with a target as an event source which may be an Element or a Component.

If the target is an element, then the keydown event will trigger the invocation of bindings.

It is possible to configure the KeyMap with a custom eventName to listen for. This may be useful when the target is a Component.

The KeyMap's event handling requires that the first parameter passed is a key event. So if the Component's event signature is different, specify a processEvent configuration which accepts the event's parameters and returns a key event.

Functions specified in bindings are called with this signature : (String key, Ext.EventObject e) (if the match is a multi-key combination the callback will still be called only once). A KeyMap can also handle a string representation of keys. By default KeyMap starts enabled.

Usage:

  
// map one key by key code
            var map = new Ext.util.KeyMap({
            target: "my-element",
            key: 13, // or Ext.EventObject.ENTER
            fn: myHandler,
            scope: myObject
            });
            // map multiple keys to one action by string
            var map = new Ext.util.KeyMap({
            target: "my-element",
            key: "a\r\n\t",
            fn: myHandler,
            scope: myObject
            });
            // map multiple keys to multiple actions by strings and array of codes
            var map = new Ext.util.KeyMap({
            target: "my-element",
            binding: [{
            key: [10,13],
            fn: function(){ alert("Return was pressed"); }
            }, {
            key: "abc",
            fn: function(){ alert('a, b or c was pressed'); }
            }, {
            key: "\t",
            ctrl:true,
            shift:true,
            fn: function(){ alert('Control + shift + tab was pressed.'); }
            }]
            });
            

Since 4.1.0, KeyMaps can bind to Components and process key-based events fired by Components.

To bind to a Component, use the single parameter form of constructor and include the Component event name to listen for, and a processEvent implementation which returns the key event for further processing by the KeyMap:

  
var map = new Ext.util.KeyMap({
            target: myGridView,
            eventName: 'itemkeydown',
            processEvent: function(view, record, node, index, event) {
            // Load the event with the extra information needed by the mappings
            event.view = view;
            event.store = view.getStore();
            event.record = record;
            event.index = index;
            return event;
            },
            binding: {
            key: Ext.EventObject.DELETE,
            fn: function(keyCode, e) {
            e.store.remove(e.record);
            // Attempt to select the record that's now in its place
            e.view.getSelectionModel().select(e.index);
            e.view.el.focus();
            }
            }
            });
            

Namespace: Ext.util

Base Types

Constructors

Methods

Name Description
addBinding(object) Add a new binding to this KeyMap. Usage:
// Create a KeyMap
            var map = new Ext.util.KeyMap(document, {
            key: Ext.EventObject.ENTER,
            fn: handleKey,
            scope: this
            });
            //Add a new binding to the existing KeyMap later
            map.addBinding({
            key: 'abc',
            shift: true,
            fn: handleKey,
            scope: this
            });
            
destroy(bool) Destroys the KeyMap instance and removes all handlers.
disable() Disable this KeyMap
enable() Enables this KeyMap
isEnabled() Returns true if this KeyMap is enabled
on(object, Delegate, object) Shorthand for adding a single key listener.
setDisabled(bool) Convenience function for setting disabled/enabled by boolean.

Fields

Name Description
binding Either a single object describing a handling function for s specified key (or set of keys), or an array of such objects.
  • key : String/String[]

    A single keycode or an array of keycodes to handle

  • shift : Boolean

    True to handle key only when shift is pressed, False to handle the key only when shift is not pressed (defaults to undefined)

  • ctrl : Boolean

    True to handle key only when ctrl is pressed, False to handle the key only when ctrl is not pressed (defaults to undefined)

  • alt : Boolean

    True to handle key only when alt is pressed, False to handle the key only when alt is not pressed (defaults to undefined)

  • handler : Function

    The function to call when KeyMap finds the expected key combination

  • fn : Function

    Alias of handler (for backwards-compatibility)

  • scope : Object

    The scope of the callback function

  • defaultEventAction : String

    A default action to apply to the event. Possible values are: stopEvent, stopPropagation, preventDefault. If no value is set no action is performed.

  • eventName The event to listen for to pick up key events. Defaults to: "keydown"
    ignoreInputFields Configure this as true if there are any input fields within the target, and this KeyNav should not process events from input fields, (<input>, <textarea> and elements withcontentEditable="true"`) Defaults to: false
    processEvent An optional event processor function which accepts the argument list provided by the configured event of the target, and returns a keyEvent for processing by the KeyMap. This may be useful when the target is a Component with s complex event signature, where the event is not the first parameter. Extra information from the event arguments may be injected into the event for use by the handler functions before returning it.
    processEventScope The scope (this context) in which the processEvent method is executed. Defaults to: this
    target The object on which to listen for the event specified by the eventName config option.
    © Copyright 2005-2011 SharpKit. All rights reserved.