keyboard Class Reference

This library creates convenient methods for adding keyboard shortcuts to an application. More...

#include "remoto!stdlib:js/include/keyboard.js"

Public Member Functions
	keyboard (obj, _defaultHandler)
	destroy ()
	destroy this keyboard listener instance More...
	init ()
	Return a new instance of a keyboard handler. More...
	keyHandler (e)
	listen (jq, _defaultHandler)
	preventDefault (e)
	registerCommand (c, f, l, r, p)
	Register a command with a keyboard listener. More...
	unregisterCommand (c, r)
	Unregister a command from a keyboard listener. More...

Detailed Description

This library creates convenient methods for adding keyboard shortcuts to an application.

To use keyboard commands, listen to a DOM element and attach commands to callbacks:

define( [
           'remoto!stdlib:js/include/keyboard.js',
   ],
   function(keyboard)
   {
           'use strict';
 
           function mySpecialClass()
           {
                   this._html = null;
 
                   this.createHTML();
 
                   k = keyboard.listen(this._html);
                   k.registerCommand("shift-q", function() { console.log("you hit shift-q"); return true; });
                   k.registerCommand("a", this.hitCommand.bind(this,"a"));
                   k.registerCommand("ctrl-shift-alt-meta-1,shift-2", this.questionUser.bind(this));
                   k.registerCommand("alt", function() { console.log("you released alt!"); return false; }, false, true );         //return false so that other things can also catch it
           }
 
           mySpecialClass.prototype.createHTML = function()
           {
                   if (this._html) return this._html;
 
                   this._html = $("<div>");
 
                   return this._html;
           }
 
           mySpecialClass.prototype.hitCommand = function(letter)
           {
                   switch(letter)
                   {
                           case "a":       console.log("you hit 'a'");
                                           return true;
                                           break;
 
                           default:        break;
                   }
 
                   return false;
           }
 
           mySpecialClass.prototype.questionUser = function()
           {
                   alert("Why did you hit such an odd keyboard combination?");
 
                   return true;
           }
 
           return mySpecialClass;
   }
);

Alternatively, you can add global commands:

keyboard.registerCommand("shift-meta-q", function() { alert("You hit the magic key!"); });

The default instance of keyboard works in the global scope and is created by the paneManager. Be careful when adding global commands. They will be received when no other handler has accepted them and may apply to non-existent objects.

DOCME: describe command syntax, comma separation of strokes ("alt-s,shift-alt-f4"), and also meta keys like shift,command,alt,esc,delete

DOCME: For commands to work, you will need to have an element with focus.

DOCME: there are also options for keydown and keyup

DOCME: when an element has focus and does recognize a keyboard event, it should return true to prevent the command from propagating to other potential callbacks. For instance, ctrl-c should catch at the first opportunity and not propagate to any other potential listeners

DOCME: keyboard event priority

DOCME: keyboard.listen

Constructor & Destructor Documentation

keyboard()

keyboard	(		obj,
			_defaultHandler
	)

Parameters

obj
_defaultHandler

DOCME

Member Function Documentation

destroy()

destroy

(

)

destroy this keyboard listener instance

Release memory associated with this keyboard handler instance, which means removing all callbacks by clearing the _command array.

init()

init

(

)

Return a new instance of a keyboard handler.

Returns

The new keyboard handler

This method is called when the keyboard library is requested by require.js. You should never have to call this method manually.

Some default commands are included by default in this initializer:

• meta-a : prevent an html "select all", which is the default for most browsers
• del,backspace : prevent a delete or backspace from using the browser history's "back" feature
• meta-s,ctrl-s,alt-s : prevent the browser from trying to save a "web archive" of the current state of the html on the page

keyHandler()

keyHandler

(

e

)

Parameters

e

Returns

DOCME

listen()

listen	(		jq,
			_defaultHandler
	)

Parameters

jq
_defaultHandler

Returns

DOCME

preventDefault()

preventDefault

(

e

)

Parameters

e

Returns

DOCME

registerCommand()

registerCommand	(		c,
			f,
			l,
			r,
			p
	)

Register a command with a keyboard listener.

Parameters

c	The command, as a stroke string ("ctrl-a","space","alt-meta-esc")
f	The callback, which will probably want to be bound()
l	boolean always
r	boolean release only
p	priority (1=first)

This is really a factory for keyboardCommand objects.

Normally a command is ignored if it happens in an input field inside the listener object. The always flag will cause it to not be ignored. For instance, if a textarea is inside of your listener, you probably want to be able to type in there, rather than a space key stroke to trigger something.

See also

keyboardCommand()

unregisterCommand()

unregisterCommand	(		c,
			r
	)

Unregister a command from a keyboard listener.

Parameters

c	The command, as a stroke string ("ctrl-a","space","alt-meta-esc"), which was previously registered
r	boolean release only

Searches for registered commands that have a matching keystroke. If release only is true, it will only remove a release-only command.

Returns true if all commands were unregistered.

See also

keyboard::registerCommand()

---

The documentation for this class was generated from the following file:

• keyboard.js