Config
Table of Contents

Function

O.formatKeyForPlatform( shortcut )

Parameters

shortcutString The keyboard shorcut, in the same format as taken by .

Returns

String The shortcut formatted for display on the user's platform.

"use strict";

( function ( NS ) {

var isMac = NS.UA.isMac;
var platformKeys = {
 alt: isMac ? '⌥' : 'Alt-',
 cmd: isMac ? '⌘' : 'Ctrl-',
 meta: isMac ? '⌘' : 'Meta-',
 shift: isMac ? '⇧' : 'Shift-',
 enter: isMac ? '↵' : 'Enter',
 backspace: isMac ? '⌫' : 'Backspace'
};

NS.formatKeyForPlatform = function ( shortcut ) {
 return shortcut.split( '-' ).map( function ( key ) {
   return platformKeys[ key ] || key.capitalise();
 }).join( '' );
};

var allowedInputs = {
 checkbox: 1,
 radio: 1,
 file: 1,
 submit: 1
};

var handleOnDown = {};

Class

O.GlobalKeyboardShortcuts

Extends
O.Object

This class facilitates adding keyboard shortcuts to your application.

var GlobalKeyboardShortcuts = NS.Class({

 Extends: NS.Object,

Property

O.GlobalKeyboardShortcuts#isEnabled

  • Boolean

Callbacks will only fire if this property is true when the instance handles the event.

Private Property

O.GlobalKeyboardShortcuts#_shortcuts

  • Object
  • private

The map of shortcut key to an array of [object, method] tuples.

Constructor

O.GlobalKeyboardShortcuts()

init: function ( mixin ) {
   this.isEnabled = true;
   this._shortcuts = {};

   GlobalKeyboardShortcuts.parent.init.call( this, mixin );

   var ViewEventsController = NS.ViewEventsController;
   ViewEventsController.kbShortcuts = this;
   ViewEventsController.addEventTarget( this, -10 );
 },

Method

O.GlobalKeyboardShortcuts#destroy()

Destructor.

destroy: function () {
   var ViewEventsController = NS.ViewEventsController;
   if ( ViewEventsController.kbShortcuts === this ) {
     delete NS.ViewEventsController.kbShortcuts;
   }
   ViewEventsController.removeEventTarget( this );
   GlobalKeyboardShortcuts.parent.destroy.call( this );
 },

Method

O.GlobalKeyboardShortcuts#register( key, object, method )

Add a global keyboard shortcut. If a shortcut has already been registered for this key, it will be replaced, but will be restored when the new handler is removed.

Parameters

keyString The key to trigger the callback on. Modifier keys (alt, ctrl, meta, shift) should be prefixed in alphabetical order and with a hypen after each one. Letters should be lower case. e.g. `ctrl-f`. The special modifier "cmd-" may be used, which will map to "meta-" on a Mac (the command key) and "Ctrl-" elsewhere.
objectObject The object to trigger the callback on.
methodString The name of the method to trigger.

Returns

O.GlobalKeyboardShortcuts Returns self.

register: function ( key, object, method ) {
   key = key.replace( 'cmd-', isMac ? 'meta-' : 'ctrl-' );
   var shortcuts = this._shortcuts;
   ( shortcuts[ key ] || ( shortcuts[ key ] = [] ) )
     .push([ object, method ]);
   return this;
 },

Method

O.GlobalKeyboardShortcuts#deregister( key, object, method )

Remove a global keyboard shortcut. Must use identical arguments to those which were used in the call to O.GlobalKeyboardShortcuts#register.

Parameters

keyString The key on which the callback was triggered.
objectObject The object on which the callback was triggered.
methodString The name of the method that was being triggered.

Returns

O.GlobalKeyboardShortcuts Returns self.

deregister: function ( key, object, method ) {
   key = key.replace( 'cmd-', isMac ? 'meta-' : 'ctrl-' );
   var current = this._shortcuts[ key ],
     length = current ? current.length : 0,
     l = length,
     item;
   while ( l-- ) {
     item = current[l];
     if ( item[0] === object && item[1] === method ) {
       if ( length === 1 ) {
         delete this._shortcuts[ key ];
       } else {
         current.splice( l, 1 );
       }
     }
   }
   return this;
 },

Method

O.GlobalKeyboardShortcuts#getHandlerForKey( key )

Get the keyboard shortcut to be triggered by a key combo, represented as a string, as output by <O.DOMEvent#lookupKey>.

Parameters

keyString The key combo to get the handler for.

Returns

Array|null Returns the [ object, method ] tuple to be triggered by the event, or null if nothing is registered for this key press.

getHandlerForKey: function ( key ) {
   var shortcuts = this._shortcuts[ key ];
   if ( shortcuts && this.get( 'isEnabled' ) ) {
     return shortcuts[ shortcuts.length - 1 ];
   }
   return null;
 },

Method

O.GlobalKeyboardShortcuts#trigger( event )

Keypress event handler. Triggers any registered callback.

Parameters

eventDOMEvent The keydown/keypress event.
trigger: function ( event ) {
   var target = event.target,
     nodeName = target.nodeName,
     isSpecialKey = event.ctrlKey || event.metaKey,
     handler, key;
   if ( !isSpecialKey && ( nodeName === 'TEXTAREA' ||
       ( nodeName === 'SELECT' ) ||
       ( nodeName === 'INPUT' && !allowedInputs[ target.type ] ) ||
       ( event.targetView instanceof NS.RichTextView )
      ) ) {
     return;
   }
   key = NS.DOMEvent.lookupKey( event );
   if ( event.type === 'keydown' ) {
     handleOnDown[ key ] = true;
   } else if ( handleOnDown[ key ] ) {
     return;
   }
   handler = this.getHandlerForKey( key );
   if ( handler ) {
     handler[0][ handler[1] ]( event );
     event.preventDefault();
   }
 }.on( 'keydown', 'keypress' )
});

NS.GlobalKeyboardShortcuts = GlobalKeyboardShortcuts;

}( O ) );
Animation
Application
Core
DataStore
DOM
DragDrop
Foundation
IO
Localisation
Selection
Parser
TimeZones
Storage
Touch
CollectionViews
UA
ContainerViews
ControlViews
PanelViews
View