KeyService
KeyService is an Angular Factory in the Util module with the name keys.js
. It provides an API to bind key presses to functions. To use these functions, see the documentation on injecting Angular services.
Name | Summary |
---|---|
bindQhs | Binds the QuickHelpService to the KeyService. |
installOn | Installs the key listener on a d3 selection of an element and sets up global key bindings. |
keyBindings | Get or set keybindings for a view. |
unbindKeys | Unbind keybindings for a view. |
gestureNotes | Get or set notes about other view gestures besides keybindings. |
enableKeys | Enable or disable keybindings. |
Function Descriptions
bindQhs
Binds the QuickHelpService to the KeyService. This is called for you when onos.js runs, so you won't have to call this yourself.
Example Usage | Arguments | Return Value |
---|---|---|
ks.bindQhs(qhs ); | qhs - the injected QuickHelpService from the setup onos.js created | none |
installOn
Installs the key listener on a d3 selection of an element and sets up global keybindings. This is called for you when onos.js runs, so you won't have to call this yourself.
Example Usage | Arguments | Return Value |
---|---|---|
ks.installOn(elem ); | elem - d3 selection of the 'body' element from onos.js | none |
keyBindings
Get or set keybindings for a view.
Example Usage | Arguments | Return Value |
---|---|---|
ks.keyBindings(x ); | This function is getter / setter. x -
| if x is globalKeys: array of strings representing the globally bound keys maskedKeys: array of strings representing keys the view can't use viewKeys: array of strings representing the view bound keys viewFunction: boolean of whether the view has a general key handler if x is defined, no return value |
There are two options for setting up keybindings – giving an object with key mappings or a function reference for a general key handler.
Key Mappings
The general format for setting key mappings is the name of the key as the object property name, and an array as the object property value.
var keys = { // the first array member is a function reference to be executed on keydown // the second array member is a string A: [aFunction, 'Description for aFunction'], B: [bFunction, 'Description for bFunction'], leftArrow: [leftFunction, 'Description for leftFunction'], alt: [altFunction, 'Description for altFunction'], // the _helpFormat property tells the QuickHelpService how to display the help information // it's an array of arrays _helpFormat: [ // list all of your bindings. '-' will create a separator // each array is a new section ['A', '-', 'B'], ['leftArrow', 'alt'] ] }; ks.keyBindings(keys); // bind the keys
The descriptions end up in the QuickHelp panel to give a helpful hint to the user as to what the button does.
The object property must be the name of the key that you want the function to be executed on. In addition to all of the letter and function (e.g. F12) keys, you can have the following object property names for other keys:
'enter', 'shift', 'ctrl', 'alt', 'esc', 'space', 'leftArrow', 'upArrow', 'rightArrow', 'downArrow', 'cmdLeft', 'cmdRight', 'equals', 'comma', 'dash', 'dot', 'slash', 'backQuote', 'backSlash'
Function Reference
You can also provide a function reference that will be executed when any key is pressed. You can map key bindings and have a general function that will run on keydown by calling ks.keyBindings(x
); twice – once with x
as the key mappings and once with x
as the function reference. If the key mapping is defined for the pressed key, that function will be called. If it's not defined, then the general function will be called instead.
unbindKeys
Unbind keybindings for a view. You typically want to call this when your view is destroyed.
Example Usage | Arguments | Return Value |
---|---|---|
ks.unbindKeys(); | none | none |
gestureNotes
Get or set notes on the QuickHelp Panel about other view gestures besides keybindings.
Example Usage | Arguments | Return Value |
---|---|---|
ks.gestureNotes(g ); | g - undefined or array of notes (see below) | if if g is defined, will not return anything |
// array of arrays for formatting the notes on the QuickHelp Panel ks.gestureNotes([ // each array is one line // first member is the name of the gesture // second member is the description ['click', 'select an item'], ['cmd-click', 'selects multiple items'], ['esc', 'deselect item(s)'] ]);
enableKeys
Enable or disable keybindings. Enabled allows the bound key functions to execute; disabled doesn't execute the functions.
Example Usage | Arguments | Return Value |
---|---|---|
ks.enableKeys(b ); | b - truthy values enable keybindings, falsy values disable keybindings | none, but keybindings are enabled or disabled |
Global Keybindings
There a few reserved keys that are shared among all views.
Key | Function |
---|---|
\ or / | Show / hide quickhelp |
esc | Dismiss quickhelp, hide navigation, cancel selections * |
T | Toggle theme |
* You can still bind a function to the 'esc' key. Your function will be called after the quickhelp and navigation (the global functions) have been hidden.