mirror of
https://github.com/Foundry376/Mailspring.git
synced 2025-01-01 13:14:16 +08:00
148 lines
6.1 KiB
HTML
148 lines
6.1 KiB
HTML
---
|
|
layout: docs
|
|
title: CommandRegistry
|
|
edit_url: "https://github.com/nylas/N1/blob/master/src/command-registry.coffee"
|
|
---
|
|
|
|
<h2>Summary</h2>
|
|
|
|
<div class="markdown-from-sourecode">
|
|
<p><p>Associates listener functions with commands in a
|
|
context-sensitive way using CSS selectors. You can access a global instance of
|
|
this class via <code>atom.commands</code>, and commands registered there will be
|
|
presented in the command palette.</p>
|
|
<p>The global command registry facilitates a style of event handling known as
|
|
<em>event delegation</em> 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 <code>atom.commands</code> and constrain them to
|
|
specific kinds of elements with CSS selectors.</p>
|
|
<p>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 <code>this</code> always points at
|
|
<code>event.currentTarget</code>. As is normally the case with DOM events,
|
|
<code>stopPropagation</code> and <code>stopImmediatePropagation</code> can be used to terminate the
|
|
bubbling process and prevent invocation of additional listeners.</p>
|
|
<h2 id="example">Example</h2>
|
|
<p>Here is a command that inserts the current date in an editor:</p>
|
|
<pre><code class="lang-coffee">atom<span class="hljs-class">.commands</span><span class="hljs-class">.add</span> <span class="hljs-string">'atom-text-editor'</span>,
|
|
<span class="hljs-string">'user:insert-date'</span>: (event) ->
|
|
editor = @<span class="hljs-function"><span class="hljs-title">getModel</span><span class="hljs-params">()</span></span>
|
|
editor.<span class="hljs-function"><span class="hljs-title">insertText</span><span class="hljs-params">(new Date()</span></span>.<span class="hljs-function"><span class="hljs-title">toLocaleString</span><span class="hljs-params">()</span></span>)
|
|
</code></pre>
|
|
</p>
|
|
</div>
|
|
|
|
<ul>
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
|
<h3>Instance Methods</h3>
|
|
|
|
<h4 id=add class="function-name">
|
|
add(<span class="args"></span>) <a href="#add" class="link"></a>
|
|
</h4>
|
|
|
|
<div class="function-description markdown-from-sourecode">
|
|
<p><p>Add one or more command listeners associated with a selector.</p>
|
|
</p>
|
|
</div>
|
|
|
|
|
|
<strong>Returns</strong>
|
|
<table class="arguments">
|
|
<tr>
|
|
<th>Return Values</th>
|
|
</tr>
|
|
<tr><td class="markdown-from-sourecode"><p>Returns a {Disposable} on which <code>.dispose()</code> can be called to remove the
|
|
added command handler(s).</p>
|
|
</td></tr>
|
|
</table>
|
|
<h4 id=findCommands class="function-name">
|
|
findCommands(<span class="args"><span class="arg">params</span></span>) <a href="#findCommands" class="link"></a>
|
|
</h4>
|
|
|
|
<div class="function-description markdown-from-sourecode">
|
|
<p><p>Find all registered commands matching a query.</p>
|
|
</p>
|
|
</div>
|
|
|
|
<strong>Parameters</strong>
|
|
<table class="arguments">
|
|
<tr>
|
|
<th>Argument</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
<tr>
|
|
<td style="width:15%;">
|
|
<em>params</em>
|
|
</td>
|
|
<td class="markdown-from-sourecode">
|
|
|
|
<p>An <a href='https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/object'>Object</a> containing one or more of the following keys:</p>
|
|
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<strong>Returns</strong>
|
|
<table class="arguments">
|
|
<tr>
|
|
<th>Return Values</th>
|
|
</tr>
|
|
<tr><td class="markdown-from-sourecode"><p>Returns an <a href='https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/array'>Array</a> of <a href='https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/object'>Object</a>s containing the following keys:</p>
|
|
<ul>
|
|
<li><code>name</code> The name of the command. For example, <code>user:insert-date</code>.</li>
|
|
<li><code>displayName</code> The display name of the command. For example,
|
|
<code>User: Insert Date</code>.</li>
|
|
<li><code>jQuery</code> Present if the command was registered with the legacy
|
|
<code>$::command</code> method.</li>
|
|
</ul>
|
|
</td></tr>
|
|
</table>
|
|
<h4 id=dispatch class="function-name">
|
|
dispatch(<span class="args"><span class="arg">target</span><span class="arg">commandName</span></span>) <a href="#dispatch" class="link"></a>
|
|
</h4>
|
|
|
|
<div class="function-description markdown-from-sourecode">
|
|
<p><p>Simulate the dispatch of a command on a DOM node.</p>
|
|
<p>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.</p>
|
|
</p>
|
|
</div>
|
|
|
|
<strong>Parameters</strong>
|
|
<table class="arguments">
|
|
<tr>
|
|
<th>Argument</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
<tr>
|
|
<td style="width:15%;">
|
|
<em>target</em>
|
|
</td>
|
|
<td class="markdown-from-sourecode">
|
|
|
|
<p>The DOM node at which to start bubbling the command event.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="width:15%;">
|
|
<em>commandName</em>
|
|
</td>
|
|
<td class="markdown-from-sourecode">
|
|
|
|
<p><a href='https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/string'>String</a> indicating the name of the command to dispatch. </p>
|
|
|
|
</td>
|
|
</tr>
|
|
</table>
|