Atom

Allows commands to be associated with keystrokes in a context-sensitive way. In Atom, you can access a global instance of this object via atom.keymaps.

Key bindings are plain JavaScript objects containing CSS selectors as their top level keys, then keystroke patterns mapped to commands.

'.workspace':
  'ctrl-l': 'package:do-something'
  'ctrl-z': 'package:do-something-else'
'.mini.editor':
  'enter': 'core:confirm'

When a keystroke sequence matches a binding in a given context, a custom DOM event with a type based on the command is dispatched on the target of the keyboard event.

To match a keystroke sequence, the keymap starts at the target element for the keyboard event. It looks for key bindings associated with selectors that match the target element. If multiple match, the most specific is selected. If there is a tie in specificity, the most recently added binding wins. If no bindings are found for the events target, the search is repeated again for the target's parent node and so on recursively until a binding is found or we traverse off the top of the document.

When a binding is found, its command event is always dispatched on the original target of the keyboard event, even if the matching element is higher up in the DOM. In addition, .preventDefault() is called on the keyboard event to prevent the browser from taking action. .preventDefault is only called if a matching binding is found.

Command event objects have a non-standard method called .abortKeyBinding(). If your command handler is invoked but you programmatically determine that no action can be taken and you want to allow other bindings to be matched, call .abortKeyBinding() on the event object. An example of where this is useful is binding snippet expansion to tab. If snippets:expand is invoked when the cursor does not follow a valid snippet prefix, we abort the binding and allow tab to be handled by the default handler, which inserts whitespace.

Multi-keystroke bindings are possible. If a sequence of one or more keystrokes partially matches a multi-keystroke binding, the keymap enters a pending state. The pending state is terminated on the next keystroke, or after ::getPartialMatchTimeout milliseconds has elapsed. When the pending state is terminated via a timeout or a keystroke that leads to no matches, the longest ambiguous bindings that caused the pending state are temporarily disabled and the previous keystrokes are replayed. If there is ambiguity again during the replay, the next longest bindings are disabled and the keystrokes are replayed again.

Create a keydown DOM event for testing purposes.

key

The key or keyIdentifier of the event. For example, 'a', '1', 'escape', 'backspace', etc.

options

optional

An Object containing any of the following:

.ctrl

A Boolean indicating the ctrl modifier key

.alt

A Boolean indicating the alt modifier key

.shift

A Boolean indicating the shift modifier key

.cmd

A Boolean indicating the cmd modifier key

.which

A Number indicating which value of the event. See the docs for KeyboardEvent for more information.

.target

The target element of the event.

Create a new KeymapManager.

options

An Object containing properties to assign to the keymap. You can pass custom properties to be used by extension methods. The following properties are also supported:

.defaultTarget

This will be used as the target of events whose target is document.body to allow for a catch-all element when nothing is focused.

Clear all registered key bindings and enqueued keystrokes. For use in tests.

Unwatch all watched paths.

Invoke the given callback when one or more keystrokes completely match a key binding.

callback(event)

Function to be called when keystrokes match a binding.

event

Object with the following keys:

.keystrokes

String of keystrokes that matched the binding.

.binding

KeyBinding that the keystrokes matched.

.keyboardEventTarget

DOM element that was the target of the most recent keyboard event.

Returns a Disposable on which .dispose() can be called to unsubscribe.

Invoke the given callback when one or more keystrokes partially match a binding.

callback(event)

Function to be called when keystrokes partially match a binding.

event

Object with the following keys:

.keystrokes

String of keystrokes that matched the binding.

.partiallyMatchedBindings

KeyBindings that the keystrokes partially matched.

.keyboardEventTarget

DOM element that was the target of the most recent keyboard event.

Returns a Disposable on which .dispose() can be called to unsubscribe.

Invoke the given callback when one or more keystrokes fail to match any bindings.

callback(event)

Function to be called when keystrokes fail to match any bindings.

event

Object with the following keys:

.keystrokes

String of keystrokes that matched the binding.

.keyboardEventTarget

DOM element that was the target of the most recent keyboard event.

Returns a Disposable on which .dispose() can be called to unsubscribe.

Invoke the given callback when a keymap file not able to be loaded.

callback(error)

Function to be called when a keymap file is unloaded.

error

Object with the following keys:

.message

String the error message.

.stack

String the error stack trace.

Returns a Disposable on which .dispose() can be called to unsubscribe.

Construct KeyBindings from an object grouping them by CSS selector.

source

A String (usually a path) uniquely identifying the given bindings so they can be removed later.

bindings

An Object whose top-level keys point at sub-objects mapping keystroke patterns to commands.

priority

A Number used to sort keybindings which have the same specificity. Defaults to 0.

Add sets of key bindings grouped by CSS selector.

source

A String (usually a path) uniquely identifying the given bindings so they can be removed later.

bindings

An Object whose top-level keys point at sub-objects mapping keystroke patterns to commands.

priority

A Number used to sort keybindings which have the same specificity. Defaults to 0.

Get all current key bindings.

Returns an Array of KeyBindings.

Get the key bindings for a given command and optional target.

params

An Object whose keys constrain the binding search:

.keystrokes

A String representing one or more keystrokes, such as 'ctrl-x ctrl-s'

.command

A String representing the name of a command, such as 'editor:backspace'

.target

An optional DOM element constraining the search. If this parameter is supplied, the call will only return bindings that can be invoked by a KeyboardEvent originating from the target element.

Returns an Array of key bindings.

Load the key bindings from the given path.

path

A String containing a path to a file or a directory. If the path is a directory, all files inside it will be loaded.

options

An Object containing the following optional keys:

.watch

If true, the keymap will also reload the file at the given path whenever it changes. This option cannot be used with directory paths.

.priority

A Number used to sort keybindings which have the same specificity.

Cause the keymap to reload the key bindings file at the given path whenever it changes.

This method doesn't perform the initial load of the key bindings file. If that's what you're looking for, call ::loadKeymap with watch: true.

path

A String containing a path to a file or a directory. If the path is a directory, all files inside it will be loaded.

options

An Object containing the following optional keys:

.priority

A Number used to sort keybindings which have the same specificity.

Dispatch a custom event associated with the matching key binding for the given KeyboardEvent if one can be found.

If a matching binding is found on the event's target or one of its ancestors, .preventDefault() is called on the keyboard event and the binding's command is emitted as a custom event on the matching element.

If the matching binding's command is 'native!', the method will terminate without calling .preventDefault() on the keyboard event, allowing the browser to handle it as normal.

If the matching binding's command is 'unset!', the search will continue from the current element's parent.

If the matching binding's command is 'abort!', the search will terminate without dispatching a command event.

If the event's target is document.body, it will be treated as if its target is .defaultTarget if that property is assigned on the keymap.

event

A KeyboardEvent of type 'keydown'

Translate a keydown event to a keystroke string.

event

A KeyboardEvent of type 'keydown'

Returns a String describing the keystroke.

Customize translation of raw keyboard events to keystroke strings. This API is useful for working around Chrome bugs or changing how Atom resolves certain key combinations. If multiple resolvers are installed, the most recently-added resolver returning a string for a given keystroke takes precedence.

resolver(keystroke, event, layoutName, keymap)

A Function that returns a keystroke String and is called with an object containing the following keys:

keystroke

The currently resolved keystroke string. If your function returns a falsy value, this is how Atom will resolve your keystroke.

event

The raw DOM 3 KeyboardEvent being resolved. See the DOM API documentation for more details.

layoutName

The OS-specific name of the current keyboard layout.

keymap

An object mapping DOM 3 KeyboardEvent.code values to objects with the typed character for that key in each modifier state, based on the current operating system layout.

Returns a Disposable that removes the added resolver.

Get the number of milliseconds allowed before pending states caused by partial matches of multi-keystroke bindings are terminated.

Returns a Number

KeymapManager extended

Class Methods

.buildKeydownEvent(key, [options])

Construction and Destruction

::constructor(options)

::clear()

::destroy()

Event Subscription

::onDidMatchBinding(callback)

::onDidPartiallyMatchBindings(callback)

::onDidFailToMatchBinding(callback)

::onDidFailToReadFile(callback)

Adding and Removing Bindings

::build(source, bindings, priority)

::add(source, bindings, priority)

Accessing Bindings

::getKeyBindings()

::findKeyBindings(params)

Managing Keymap Files

::loadKeymap(path, options)

::watchKeymap(path, options)

Managing Keyboard Events

::handleKeyboardEvent(event)

::keystrokeForKeyboardEvent(event)

::addKeystrokeResolver(resolver)

::getPartialMatchTimeout()