CommandRegistry

Summary

Associates listener functions with commands in a context-sensitive way using CSS selectors. You can access a global instance of this class via atom.commands, and commands registered there will be presented in the command palette.

The global command registry facilitates a style of event handling known as event delegation that was popularized by jQuery. Atom commands are expressed as custom DOM events that can be invoked on the currently focused element via a key binding or manually via the command palette. Rather than binding listeners for command events directly to DOM nodes, you instead register command event listeners globally on atom.commands and constrain them to specific kinds of elements with CSS selectors.

As the event bubbles upward through the DOM, all registered event listeners with matching selectors are invoked in order of specificity. In the event of a specificity tie, the most recently registered listener is invoked first. This mirrors the "cascade" semantics of CSS. Event listeners are invoked in the context of the current DOM node, meaning this always points at event.currentTarget. As is normally the case with DOM events, stopPropagation and stopImmediatePropagation can be used to terminate the bubbling process and prevent invocation of additional listeners.

Example

Here is a command that inserts the current date in an editor:

atom.commands.add 'atom-text-editor',
  'user:insert-date': (event) ->
    editor = @getModel()
    editor.insertText(new Date().toLocaleString())

Instance Methods

add()

Add one or more command listeners associated with a selector.

Returns
Return Values

Returns a {Disposable} on which .dispose() can be called to remove the added command handler(s).

findCommands(params)

Find all registered commands matching a query.

Parameters
Argument Description
params

An Object containing one or more of the following keys:
Returns
Return Values

Returns an Array of Objects containing the following keys:

  • name The name of the command. For example, user:insert-date.
  • displayName The display name of the command. For example, User: Insert Date.
  • jQuery Present if the command was registered with the legacy $::command method.

dispatch(targetcommandName)

Simulate the dispatch of a command on a DOM node.

This can be useful for testing when you want to simulate the invocation of a command on a detached DOM node. Otherwise, the DOM node in question needs to be attached to the document so the event bubbles up to the root node to be processed.

Parameters
Argument Description
target

The DOM node at which to start bubbling the command event.
commandName

String indicating the name of the command to dispatch.