Contents

keys

Manages key bindings in Textadept.

Overview

Key bindings are defined in the global table keys. Each key-value pair in keys consists of either a string key sequence and its associated command, a string lexer language (from the lexers/ directory) with a table of key sequences and commands, or a key sequence with a table of more sequences and commands. The latter is part of what is called a “key chain”. When searching for a command to run based on a key sequence, key bindings in the current lexer have priority, followed by the ones in the global table. This means if there are two commands with the same key sequence, the one specific to the current lexer is run. However, if the command returns the boolean value false, the lower-priority command is also run. (This is useful for language-specific modules to override commands like Adeptsense autocompletion, but fall back to word autocompletion if the first command fails.)

Key Sequences

Key sequences are strings built from a combination of modifier keys and the key itself. Modifier keys are “Control”, “Shift”, and “Alt” on Windows, Linux, BSD, and in ncurses. On Mac OSX they are “Command” (), “Alt/Option” (), “Control” (^), and “Shift” (). These modifiers have the following string representations:

Modifier Linux / Win32 Mac OSX Terminal
Control 'c' 'm' 'c'
Alt 'a' 'a' 'm'
Shift 's' 's' 's'
Command N/A 'c' N/A

For key values less than 255, their string representation is the character that would normally be inserted if the “Control”, “Alt”, and “Command” modifiers were not held down. Therefore, a combination of Ctrl+Alt+Shift+A has the key sequence caA on Windows and Linux, but a combination of Ctrl+Shift+Tab has the key sequence cs\t. On a United States English keyboard, since the combination of Ctrl+Shift+, has the key sequence c< (Shift+, inserts a <), the key binding is referred to as Ctrl+<. This allows key bindings to be language and layout agnostic. For key values greater than 255, the KEYSYMS lookup table is used. Therefore, Ctrl+Right Arrow has the key sequence cright. Uncommenting the print() statements in core/keys.lua will print key sequences to standard out (stdout) for inspection.

Commands

Commands associated with key sequences can be either Lua functions, or tables containing Lua functions with a set of arguments to call the function with. Examples are:

keys['cn'] = new_buffer
keys['cs'] = buffer.save
keys['a('] = {_M.textadept.editing.enclose, '(', ')'}

Note that buffer references are handled properly.

Key Chains

Key chains are a powerful concept. They allow multiple key bindings to be assigned to one key sequence. Language-specific modules use key chains for their functions. By default, the Esc ( on Mac OSX | Esc in ncurses) key cancels a key chain, but it can be redefined via CLEAR. An example key chain looks like:

keys['aa'] = {
  a = function1,
  b = function2,
  c = {function3, arg1, arg2}
}

Fields


CLEAR (string)

The string representing the key sequence that clears the current key chain. It cannot be part of a key chain. The default value is 'esc' for the Esc ( on Mac OSX | Esc in ncurses) key.


LANGUAGE_MODULE_PREFIX (string)

The starting key of the key chain reserved for language-specific modules. The default value is 'cl' on platforms other than Mac OSX, 'ml' otherwise. Equivalent to Ctrl+L (⌘L on Mac OSX | M-L in ncurses).


Tables


KEYSYMS

Lookup table for string representations of key codes higher than 255. Key codes can be identified by temporarily uncommenting the print() statements in core/keys.lua.


_G.keys

Map of key bindings to commands, with language-specific key tables assigned to a lexer name key.