<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="dactyl://content/help.xsl"?>
-<!DOCTYPE document SYSTEM "dactyl://content/modes.dtd">
+<!DOCTYPE document SYSTEM "dactyl://cache/modes.dtd">
<document
name="map"
For instance,
</p>
-<code><ex>:map <k name="F2" link="false"/></ex> <ex>:echo Date()<k name="CR"/></ex></code>
+<code><ex>:map <k name="F2" link="false"/></ex> <ex>:styletoggle</ex> <em>-name</em> <k name="A-Tab" link="c_<Tab>"/></code>
<p>
- causes “<ex>:echo Date()<k name="CR"/></ex>” to be typed out
- whenever <k name="F2" link="false"/> is pressed, thus echoing the full date
- to the command line.
+ causes “<tt><ex>:styletoggle</ex> <em>-name</em> <k name="A-Tab" link="c_<Tab"/></tt>” to be typed out
+ whenever <k name="F2" link="false"/> is pressed, providing a way to toggle
+ a tab-completed named user style.
+</p>
+
+<p>
+ You can also map keys to <link topic="ex-scripts">Ex</link> or
+ <link topic=":js">JavaScript</link> commands, see the
+ <link topic="map-examples">examples</link>.
</p>
<p tag=":map-modes">
<dt>i</dt> <dd>Insert mode: When interacting with text fields on a website</dd>
<dt>t</dt> <dd>Text Edit mode: When editing text fields in Vim-like Normal mode</dd>
<dt>c</dt> <dd>Command Line mode: When typing into the &dactyl.appName; command line</dd>
+ <dt>o</dt> <dd>Operator mode: When moving the cursor</dd>
</dl>
<p>
prefixed with one of the above letters. For instance,
<ex>:imap</ex> creates a new key mapping in Insert mode, while
<ex>:cunmap</ex> removes a key mapping from Command Line mode.
- Other modes can be specified using the -modes option described below.
+ Other modes can be specified using the <em>-modes</em> option described below.
</p>
<warning>
<dt></dt> <dd></dd>
<dt>-arg</dt> <dd>Accept an argument after the requisite key press. Sets the <tt>arg</tt> parameter to the result. (short name <em>-a</em>)</dd>
- <dt>-builtin</dt> <dd>Execute this mapping as if there were no user-defined mappings (short name <em>-b</em>)</dd>
+ <dt>-builtin</dt> <dd>Execute this mapping as if there were no user-defined mappings. (short name <em>-b</em>)</dd>
<dt>-count</dt> <dd>Accept a count before the requisite key press. Sets the <tt>count</tt> parameter to the result. (short name <em>-c</em>)</dd>
- <dt>-description</dt> <dd>A description of this mapping (short name <em>-d</em>)</dd>
- <dt>-ex</dt> <dd>Execute <a>rhs</a> as an Ex command rather than keys (short name <em>-e</em>)</dd>
+ <dt>-description</dt> <dd>A description of this mapping. (short name <em>-d</em>)</dd>
+ <dt>-ex</dt> <dd>Execute <a>rhs</a> as an Ex command rather than keys. (short name <em>-e</em>)</dd>
<dt>-group=<a>group</a></dt> <dd>Add this command to the given <t>group</t> (short name <em>-g</em>). When listing commands this limits the output to the specified group.</dd>
- <dt>-javascript</dt> <dd>Execute <a>rhs</a> as JavaScript rather than keys (short names <em>-js</em>, <em>-j</em>)</dd>
+ <dt>-javascript</dt> <dd>Execute <a>rhs</a> as JavaScript rather than keys. (short names <em>-js</em>, <em>-j</em>)</dd>
<dt>-literal=<a>n</a></dt> <dd>Parse the <a>n</a>th argument without specially processing any quote or meta characters. (short name <em>-l</em>)</dd>
- <dt>-modes=<a>modes</a></dt> <dd>Create this mapping in the given modes (short names <em>-mode</em>, <em>-m</em>)</dd>
- <dt>-nopersist</dt> <dd>Do not save this mapping to an auto-generated rc file (short name <em>-n</em>)</dd>
- <dt>-silent</dt> <dd>Do not echo any generated keys to the command line (short name <em>-s</em>, also <em><silent></em> for Vim compatibility)</dd>
+ <dt>-modes=<a>modes</a></dt> <dd>Create this mapping in the given modes. (short names <em>-mode</em>, <em>-m</em>)</dd>
+ <dt>-nopersist</dt> <dd>Do not save this mapping to an auto-generated rc file. (short name <em>-n</em>)</dd>
+ <dt>-silent</dt> <dd>Do not echo any generated keys to the command line. (short name <em>-s</em>, also <em><silent></em> for Vim compatibility)</dd>
</dl>
<item>
</description>
</item>
+<h3 tag="map-examples">Mapping examples</h3>
+
+<p>Make <k name="A-n" link="false"/> do the same as <k name="Down" link="false"/> in input <t>modes</t>:</p>
+
+<code><ex>:map</ex> <em>-b</em> <em>-m</em> input <k name="A-n" link="false"/> <k name="Down" link="false"/></code>
+
+<p>Toggle the tab line with <k name="A-t" link="false"/>:</p>
+
+<code><ex>:map</ex> <em>-ex</em> <k name="A-t" link="false"/> <se opt="showtabline" op="!="><str delim="">always</str>,<str delim="">never</str></se></code>
+
+<p>Make <k name="A-i" link="false"/> toggle image display:</p>
+
+<code><ex>:map</ex> <k name="A-i" link="false"/> <em>-js</em> <<<em>EOF</em>
+let (pref = <str>permissions.default.image</str>)
+ prefs.set(pref, prefs.get(pref) == 1 ? 2 : 1);
+tabs.reload(config.browser.mCurrentTab);
+<em>EOF</em></code>
+
+
+<h2 tag="bypassing-&dactyl.name;">Bypassing &dactyl.appName;</h2>
+
+&dactyl.appName; overrides nearly all &dactyl.host; keys in order to
+make browsing more pleasant for Vim users. On the occasions when you
+want to bypass &dactyl.appName;'s key handling and pass keys directly to
+&dactyl.host; or to a web page, you have several options:
+
+<item>
+ <tags><![CDATA[<pass-next-key-builtin> <A-b>]]></tags>
+ <spec><![CDATA[<A-b>]]></spec>
+ <description>
+ <p>
+ Process the next key as a builtin mapping, ignoring any user defined
+ mappings and <o>passkeys</o> settings.
+ </p>
+ </description>
+</item>
+
+<item>
+ <tags><![CDATA[send-key <pass-next-key> <C-v>]]></tags>
+ <spec><![CDATA[<C-v>]]></spec>
+ <description>
+ <p>
+ Pass the next key press directly to &dactyl.host;.
+ </p>
+ </description>
+</item>
+
+<item>
+ <tags><![CDATA[pass-through <pass-all-keys> <C-z>]]></tags>
+ <spec><![CDATA[<C-z>]]></spec>
+ <description>
+ <p>
+ Pass all keys except for <k name="Esc"/> directly to
+ &dactyl.host;. When <k name="Esc"/> is pressed,
+ resume normal key handling. This is especially useful
+ for web sites which make heavy use of key bindings.
+ </p>
+ </description>
+</item>
+
+<p>
+ See also <o>passkeys</o> and <o>passunknown</o> for ways to permanently pass
+ all or particular keys under certain conditions.
+</p>
+
<h2 tag="abbreviations">Abbreviations</h2>
<p>
<p>
By default, user commands accept no arguments. This can be changed by specifying
- the <tt>-nargs</tt> option.
+ the <em>-nargs</em> option.
</p>
<p>The valid values are:</p>
<p>
Completion for arguments to user-defined commands is not available by default.
Completion can be enabled by specifying one of the following arguments to the
- -complete option when defining the command.
+ <em>-complete</em> option when defining the command.
</p>
<dl tag=":command-complete-arg-list"/>
<p>
Custom completion can be provided by specifying the
- <str>custom,<a>thing</a></str> argument to <tt>-complete</tt>. If
+ <str>custom,<a>thing</a></str> argument to <em>-complete</em>. If
<a>thing</a> evaluates to a function (i.e., it is a variable holding
a function value, or a string containing the definition itself), it
is called with two arguments: a completion context, and an object
<h3 tag="E177 E178 :command-count">Count handling</h3>
<p>
- By default, user commands do not accept a count. Use the -count option if
+ By default, user commands do not accept a count. Use the <em>-count</em> option if
you'd like to have a count passed to your user command. This will then be
available for expansion as <count> in the replacement.
</p>
<p>
By default, a user command does not have a special version, i.e. a version
- executed with the ! modifier. Providing the -bang option will enable this
+ executed with the ! modifier. Providing the <em>-bang</em> option will enable this
and <bang> will be available in the replacement.
</p>
<h3 tag=":command-description">Command description</h3>
<p>
- The command's description text can be set with -description. Otherwise it will
+ The command's description text can be set with <em>-description</em>. Otherwise it will
default to "User-defined command".
</p>
</description>
</item>
-<h2 tag="command-examples">Examples</h2>
+<h3 tag="command-examples">Command examples</h3>
+
+<p>A command to search via DuckDuckGo:</p>
+
+<code><ex>:command</ex> <em>-nargs</em>=* <str delim="">ddg</str> open ddg <args></code>
-<p>Add a :Google command to search via google:</p>
-<code><ex>:command -nargs=* Google open google <args></ex></code>
+<p>
+ A command to search for contents of the current selection using a
+ tab-completed search engine in the current or a new tab (depending on how
+ much you bang on the keyboard):
+</p>
-<!-- TODO: add decent examples -->
+<code><ex>:com!</ex> <str delim="">search-selection</str>,<str delim="">ss</str> <em>-bang</em> <em>-nargs</em>=? <em>-complete</em> search
+ \ <em>-js</em> commands.execute((bang ? <str>open </str> : <str>tabopen </str>)
+ \ + args + <str> </str> + buffer.currentWord)</code>
</document>
projects / dactyl.git / blobdiff