CommandRegistry essential
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.
Command names must follow the namespace:action
pattern, where namespace
will typically be the name of your package, and action
describes the
behavior of your command. If either part consists of multiple words, these
must be separated by hyphens. E.g. awesome-package:turn-it-up-to-eleven
.
All words should be lowercased.
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:
atomcommandsadd 'atom-text-editor''user:insert-date':editor = @getModeleditorinsertTexttoLocaleString
Methods
::add(target, commandName, listener)
Add one or more command listeners associated with a selector.
Registering One Command
add(target, commandName, listener) |
|
---|---|
Argument | Description |
target |
A String containing a CSS selector or a DOM element. If you pass a selector, the command will be globally associated with all matching elements. The |
commandName |
A String containing the name of a command you want to handle such as |
listener(displayName, description, hiddenInCommandPalette) |
A listener which handles the event. Either a Function to call when the given command is invoked on an element matching the selector, or an Object with a |
displayName |
Overrides any generated |
description |
Used by consumers to display detailed information about the command. |
hiddenInCommandPalette |
If |
Registering Multiple Commands
add(target, commands) |
|
---|---|
Argument | Description |
target |
A String containing a CSS selector or a DOM element. If you pass a selector, the commands will be globally associated with all matching elements. The |
commands |
An Object mapping command names like |
Return values |
---|
Returns a Disposable on which |
::findCommands(params)
Find all registered commands matching a query.
Argument | Description |
---|---|
params |
An Object containing one or more of the following keys: |
.target |
A DOM node that is the hypothetical target of a given command. |
Return values |
---|
Returns an Array of
|
::dispatch(target, commandName)
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.
Argument | Description |
---|---|
target |
The DOM node at which to start bubbling the command event. |
commandName |
String indicating the name of the command to dispatch. |
::onWillDispatch(callback)
Invoke the given callback before dispatching a command event.
Argument | Description |
---|---|
callback(event) |
Function to be called before dispatching each command |
event |
The Event that will be dispatched |
::onDidDispatch(callback)
Invoke the given callback after dispatching a command event.
Argument | Description |
---|---|
callback(event) |
Function to be called after dispatching each command |
event |
The Event that was dispatched |