Keyboard shortcuts and commands

&dactyl.appName; provides a number of commands to change the behavior of key presses. This can mean anything from automatically substituting one key for another or automatically replacing one typed word for another, to launching a dialog or running a command.

Key mapping

Key mappings are the most basic means &dactyl.appName; provides for altering the actions of key presses. Each key mapping is associated with a mode, such as insert, normal, or command-line, and only has effect when that mode is active. Although each mode has a full suite of internal mappings, they may be easily augmented, altered, or removed with the :map command and its variants. These commands, in essence, allow the user to quickly substitute one sequence of key presses for another. For instance,

:map :echo Date()

causes “:echo Date()” to be typed out whenever is pressed, thus echoing the full date to the command line.

Standard key mapping commands are provided for the four most common modes,

n: Normal mode: When browsing normally
v: Visual mode: When selecting text with the cursor keys
i: Insert mode: When interacting with text fields on a website
t: TextEdit mode: When editing text fields in Vim-like NORMAL mode
c: Command-line mode: When typing into the &dactyl.appName; command line

The ordinary :map and :noremap commands add mappings for normal and visual mode. In order to map key bindings in a different mode, any of the mapping commands may be prefixed with one of the above letters. For instance, :imap creates a new key mapping in insert mode, while :cunmap removes a key mapping from command-line mode.

It is important to note that mappings are not automatically saved between sessions. In order to preserve them, they must either be added to your &dactyl.name;rc or saved via the :mk&dactyl.name;rc command.

Map commands

:map :map lhs rhs :nm :nmap :nmap lhs rhs :vm :vmap :vmap lhs rhs :im :imap :imap lhs rhs :tm :tmap :tmap lhs rhs :cm :cmap :cmap lhs rhs

Map the key-sequence lhs to rhs for the applicable mode(s). The keys of rhs respect user-defined mappings, so the following will result in an infinite loop,

:map a b
:map b a

In order to avoid this shortcoming, the :noremap command or the -builtin option may be used.

Map options

Any of the map commands may be given the following options:


-builtin: Execute this mapping as if there were no user-defined mappings (short name -b)
-count: Accept a count before the requisite key press (short name -c)
-descripion: A description of this mapping (short name -d)
-ex: Execute rhs as an Ex command rather than keys (short name -e)
-javascript: Execute rhs as JavaScript rather than keys (short names -js, -j)
-modes: Create this mapping in the given modes (short names -mode, -m)
-nopersist: Do not save this mapping to an auto-generated rc file (short name -n)
-silent: Do not echo any generated keys to the command line (short name -s, also <silent> for Vim compatibility)

:no :noremap :noremap lhs rhs :nn :nnoremap :nnoremap lhs rhs :vn :vnoremap :vnoremap lhs rhs :ino :inoremap :inoremap lhs rhs :tno :tnoremap :tnoremap lhs rhs :cno :cnoremap :cnoremap lhs rhs

Map the key-sequence lhs to rhs for the applicable mode(s). The keys in rhs do not respect user-defined key mappings, so the following effectively reverses the default meanings of the keys d and D

:noremap d D
:noremap D d

:unm :unmap :unmap lhs :nun :nunmap :nunmap lhs :vun :vunmap :vunmap lhs :iu :iunmap :iunmap lhs :tu :tunmap :tunmap lhs :cu :cunmap :cunmap lhs

Remove the mapping of lhs for the applicable mode(s).

:mapc :mapclear :mapclear :nmapc :nmapclear :nmapclear :vmapc :vmapclear :vmapclear :imapc :imapclear :imapclear :tmapc :tmapclear :tmapclear :cmapc :cmapclear :cmapclear

Remove all user-defined mappings for the applicable mode(s).

:map :nmap :vmap :imap :tmap :cmap

List all mappings for the applicable mode(s).

:map_l :map lhs :nmap_l :nmap lhs :vmap_l :vmap lhs :imap_l :imap lhs :tmap_l :tmap lhs :cmap_l :cmap lhs

List all mappings starting with lhs for the applicable mode(s).

Special arguments

:map-<silent>

When the first argument to one of the mapping commands is , the keys in rhs are not shown in the command line as they are generated. Nor, for that matter, is anything else until the command has completed.

Below is an overview of which modes each map command applies to:


:map   :noremap   :unmap   :mapclear  – both Normal and Visual modes
:nmap  :nnoremap  :nunmap  :nmapclear – Normal mode
:vmap  :vnoremap  :vunmap  :vmapclear – Visual mode
:imap  :inoremap  :iunmap  :imapclear – Insert mode
:tmap  :tnoremap  :tunmap  :tmapclear – Text Edit mode
:cmap  :cnoremap  :cunmap  :cmapclear – Command-line mode

Key sequences

Most keys in key sequences are represented simply by the character that you see on the screen when you type them. However, as a number of these characters have special meanings, and a number of keys have no visual representation, a special notation is required.

The first argument to the :map commands must be quoted if it contains spaces, quotation marks or back-slashes. A space may additionally be typed as .
As special key names start with the < character, a literal < must be typed as .
, , , and represent the standard arrow keys.
, , , , , , and work as expected.
or represent the carriage return key.
represents the backspace key.
through work as expected.
through represent keys on the numeric keypad.
, where xxxx is any 4 hexadecimal digits, represents the character at that Unicode codepoint. For instance, represents ☺.

In order to represent key presses using the Control, Alt, Meta, or Shift keys, the following prefixes may be used,

: The control or ctrl key.
: The alt key.
: The meta key, windows key, or command key.
: The shift key.

These prefixes can be combined however you see fit.

Within angle brackets all alphabetic characters are read as lowercase. Uppercase characters can only be specified with the S- modifier.

The following key sequences are interpreted as described:

xc: Type the ‘X’ key followed by the ‘C’ key.
c: Type the ‘X’ key while holding the ‘Control’ key, followed by the ‘C’ key.
: Type the ‘2’ while holding the ‘Control’ key.
: Type the ‘@’ key while holding the ‘Control’ key.
: Press the space bar while holding the ‘Shift’ key.
: Type the ‘J’ key while while holding both the ‘Control’ and ‘Alt’ keys.
: Exactly the same as above.
: Type the ‘J’ key while while holding both the ‘Control’, ‘Alt’, and ‘Shift’ keys.

Special characters

]]> <Nop>

Do nothing. This pseudo-key is useful for disabling a specific builtin mapping. For example, :map will prevent from doing anything.

map_return]]> <CR>

Expand to a line terminator in a key mapping. An Ex command in the rhs of a mapping requires a line terminator after it so that it is executed when the mapping is expanded. should be used for this purpose.

\]]> <Leader>

A pseudo-key which expands to the value of the mapleader option. For example, by default,

:map h :echo Hello

works like

:map \h :echo Hello

but after

it works like

:map ,h :echo Hello

Abbreviations

In addition to basic mappings, &dactyl.appName; can also automatically replace whole words after they've been typed. These shortcuts are known as abbreviations, and are most often useful for correcting spelling of commonly mistyped words, as well as shortening the typing of oft-typed but long words or phrases. There are three basic types of abbreviations, defined by the types of characters they contain,

‘full-id’ abbreviations consist entirely of keyword characters (e.g., ‘teh’, ‘msoft’).
‘end-id’ abbreviations end in keyword character but otherwise contains all non-keyword characters (e.g., ‘'i’).
‘non-id’ abbreviations end in a non-keyword character but otherwise contains any non-whitespace character (e.g., ‘def'’).
Strings which fit none of the above patterns can not be defined as abbreviations (e.g., ‘a'b’ and ‘a b’).

For the purposes of abbreviations, keyword characters include all non-whitespace characters except for single or double quotation marks. Abbreviations are expanded as soon as any non-keyword character, or the key , is typed.

:ab :abbreviate :abbreviate lhs rhs :abbreviate lhs :abbreviate

Abbreviate lhs to rhs. If only lhs is given, list all abbreviations that start with lhs. If no arguments are given, list all abbreviations.

If the -javascript (short names -js, -j) option is given, lhs is expanded to the value returned by the JavaScript code rhs. The code is evaluated with the variable editor set to the editable element that the abbreviation is currently being expanded in. The code should not make any changes to the contents of the editor.

:ca :cabbrev :cabbrev lhs rhs :cabbrev lhs :cabbrev

Abbreviate a key sequence for Command-line mode. Same as :abbreviate, but for command-line mode only.

:ia :iabbrev :iabbrev lhs rhs :iabbrev lhs :iabbrev

Abbreviate a key sequence for Insert mode. Same as :abbreviate, but for insert mode only.

:una :unabbreviate :unabbreviate lhs

Remove an abbreviation.

:cuna :cunabbrev :cunabbrev lhs

Remove an abbreviation for Command-line mode. Same as :unabbreviate, but for command-line mode only.

:iuna :iunabbrev :iunabbrev lhs

Remove an abbreviation for Insert mode. Same as :unabbreviate but for Insert mode only.

:abc :abclear :abclear

Remove all abbreviations.

:cabc :cabclear :cabclear

Remove all abbreviations for command-line mode.

:iabc :iabclear :iabclear

Remove all abbreviations for Insert mode.

User-defined commands

Defining new commands is perhaps the most straightforward way of repeating commonly used actions. User-defined commands may be entered from the command line or scripts exactly like standard commands, and may similarly accept arguments, options, counts, and !s, as well as provide command-line completion. These commands may be defined as either ordinary, macro-interpolated Ex commands, or otherwise as plain JavaScript statements.

:com :command :command

List all user-defined commands.

:command cmd

List all user-defined commands that start with cmd.

:command! attr… cmd rep

Define a new user command. The name of the command is cmd and its replacement text is rep. If a command with this name already exists, an error is reported unless ! is specified, in which case the command is redefined. Unlike Vim, the command may start with a lowercase letter.

The new command is usually defined by a string to be executed as an Ex command. In this case, before execution, strings of the form <var> are interpolated as described below, in order to insert arguments, options, and the like. If the -javascript (short name -js) flag is present, the command is executed as JavaScript, and the arguments are present as variables in its scope instead, and no interpolation is performed.

The command's behavior can be altered by providing attributes when the command is defined.

Argument handling

By default, user commands accept no arguments. This can be changed by specifying the -nargs attribute.

The valid values are:

-nargs=0: No arguments are allowed (default)
-nargs=1: One argument is allowed
-nargs=*: Zero or more arguments are allowed
-nargs=?: Zero or one argument is allowed
-nargs=+: One or more arguments are allowed

Argument completion

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.

altstyle: alternate author style sheets
bookmark: bookmarks
buffer: buffers
color: color schemes
command: Ex commands
dialog: &dactyl.host; dialogs
dir: directories
environment: environment variables
event: autocommand events
file: files
help: help tags
highlight: highlight groups
javascript: JavaScript expressions
macro: named macros
mapping: user mappings
menu: menu items
option: &dactyl.appName; options
preference: &dactyl.host; preferences
search: search engines and keywords
shellcmd: shell commands
sidebar: sidebar panels
url: URLs
usercommand: user commands
custom,func: custom completion, provided by func

Custom completion

Custom completion can be provided by specifying the custom,func argument to -complete. The func is called with two arguments, a completion context, and an object describing the command's arguments. It should set the context's completions property, or return an object, with items and start properties, describing the completions and where the replacement is to start.

start is the index into the word being completed at which the returned values should be applied and completions is a two-dimensional array of the form: [[arg1, description1], [arg2, description2], …]

Count handling

By default, user commands do not accept a count. Use the -count attribute if you'd like to have a count passed to your user command. This will then be available for expansion as <count> in the argument.

Special cases

By default, a user command does not have a special version, i.e. a version executed with the ! modifier. Providing the -bang attribute will enable this and <bang> will be available in the argument.

Command description

The command's description text can be set with -description. Otherwise it will default to "User-defined command".

Replacement text

The replacement text rep is scanned for escape sequences and these are replaced with values from the user-entered command line. The resulting string is then executed as an Ex command.

The valid escape sequences are:

<args>: The command arguments exactly as supplied
<count>: Any supplied count, e.g. 5
<bang>: ! if the command was executed with the ! modifier
<lt>: A literal '<' character to allow for a literal copy of one of the escape sequences. E.g., <lt>args> will expand to a literal <args>

"q-" can be prefixed to the escape sequence so that the value is quoted, making it suitable for expression evaluation. Example: <q-args>

:comc :comclear :comclear

Delete all user-defined commands.

:delc :delcommand :delcommand cmd

Delete the user-defined command cmd.

Examples

Add a :Google command to search via google:

:command -nargs=* Google open google <args>