Class: Bindings

Bindings

Bindings is responsible for managing the mapping of behavior to Combos. In addition, it is responsible for listening in on keyup/keydown/keypress events document-wide, and if a Combo is matched, execute any associated handlers while also preventing the default behavior. It allows for persistance or transport by serializing the bindings currently managed, but not the handlers. Deserializing an instance of Bindings requires you to re-register all handlers.

new Bindings()

Creates a new instance of the Bindings manager

Source:
  • keys.js, line 791
Example
  // Toggle variable
  var toggled = false;

  // Initialize manager
  var bindings = new Bindings();

  bindings.add('displayAlert', new Combo(Key.A, [ Key.CTRL, Key.SHIFT ]));
  bindings.add('toggleFlag', 'Optional description text.', new Combo(Key.F, [ Key.CTRL, Key.META ]));

  // Map behavior to the displayAlert
  bindings.registerHandler('displayAlert', function() { alert('Hello!'); });

  // Map behavior to the toggleFlag binding
  var toggleOn  = function() { toggled = true; };
  var toggleOff = function() { toggled = false; };
  bindings.registerToggle('toggleFlag', toggleOn, toggleOff);

  See `examples/example.html` for a live demonstration of these concepts.

Methods

add(name, description, combos)

Adds a new binding.

Parameters:
Name Type Description
name string

The name of the binding.

description string

A description of the binding's purpose (optional)

combos Combo

One or more Keys or Combos which trigger this binding

Source:
  • keys.js, line 1068

deserialize(serialized)

Deserialize a set of bindings into the current Bindings instance

Parameters:
Name Type Description
serialized string

The JSON object to deserialize

Source:
  • keys.js, line 1326

disable(bindingNames*)

Disable Keys.js or a specific binding or bindings, depending on the number of arguments. None will disable Key.js if it is currently disabled. One or more will disable each of the bindings matched by the names provided.

Parameters:
Name Type Description
bindingNames* string

One or more binding names to disable

Source:
  • keys.js, line 932

enable(bindingNames*)

Re-enable Keys.js or a specific binding or bindings, depending on the number of arguments. None will re-enable Key.js if it is currently disabled. One or more will re-enable each of the bindings matched by the names provided.

Parameters:
Name Type Description
bindingNames* string

One or more binding names to re-enable

Source:
  • keys.js, line 883

get(name) → {object}

Fetches a binding by it's name.

Parameters:
Name Type Description
name string

Name of the binding

Source:
  • keys.js, line 977
Returns:

The binding, if found, otherwise null

Type
object

getHandlersForCombo(combo)

Gets the set of handlers for the given Combo

Parameters:
Name Type Description
combo Combo

The Combo to match handlers to.

Source:
  • keys.js, line 1354

registerHandler(bindingName, eventType, handler, isGlobal)

Register a handler for when a Combo is executed.

Parameters:
Name Type Description
bindingName string

The name of the binding to watch, is optional when handler is a named function.

eventType string

(optional) Either keyup or keydown, depending on needs. Defaults to keydown.

handler function

The function to call when the Combo is executed.

isGlobal Boolean

(optional) True to execute the handler regardless of context, false to prevent execution when in the context of an input control. Defaults to false.

Source:
  • keys.js, line 1129
Example
     function displayAlert() { alert('Hello!'); }
     // Full specification syntax
     bindings.registerHandler('displayAlert', 'keyup', function() { alert('Hello!'); }, true);
     // Partial specification, inferred eventType
     bindings.registerHandler('displayAlert', function() { alert('Hello!'); }, true);
     // Partial specification, inferred bindingName (must use named function)
     bindings.registerHandler('keyup', displayAlert, true);
     // Partial specification, inferred eventType and bindingName
     bindings.registerHandler(displayAlert, true);
     // Minimal specification, inferred eventType and bindingName, isGlobal defaults to false
     bindings.registerHandler(displayAlert);

registerHandlers(handlers, eventType)

For easier initialization, allow binding a group of handlers at one time using object notation

Parameters:
Name Type Description
handlers object | array

Either an object defining the handlers to register, using the schema shown in the example, or an array of named functions, which will all use either 'keydown' or the provided default eventType.

eventType string

The default eventType to use for handlers provided {optional}

Source:
  • keys.js, line 1219
Example
     function displayAlert() { alert('Hello!'); }
     function logEvent() { console.log('logEvent triggered!'); }
     // Object notation
     bindings.registerHandlers({
         displayAlert: {
             eventType: 'keyup',
             handler:   displayAlert,
             isGlobal:  true
         },
         logEvent: logEvent
     });
     // Array notation
     bindings.registerHandlers([ displayAlert, logEvent ]);
     // Array notation with default eventType
     bindings.registerHandlers([ displayAlert, logEvent ], 'keyup');

registerToggle(bindingName, toggleOn, toggleOff, isGlobal)

Register a toggle for when a Combo is executed.

Parameters:
Name Type Description
bindingName string

The name of the binding to watch

toggleOn function

The function to execute when toggling on

toggleOff function

The function to execute when toggling off

isGlobal Boolean

(optional) True to execute the toggle regardless of context, false to prevent execution when in the context of an input control. Defaults to false.

Source:
  • keys.js, line 1276

serialize() → {string}

Serialize the current set of bindings (not the handlers)

Source:
  • keys.js, line 1313
Returns:
  • The Bindings instance as a JSON encoded string
Type
string