Contents

keys

Manages key commands in Textadept.

Overview

Key commands are defined in the global table keys. Each key-value pair in keys consists of either:

Language names are the names of the lexer files in lexers/ such as cpp and lua.

A key command string is built from a combination of the CTRL, ALT, META, SHIFT, and ADD constants as well as the pressed key itself. The value of ADD is inserted between each of CTRL, ALT, META, SHIFT, and the key. For example:

-- keys.lua:
CTRL = 'Ctrl'
ALT = 'Alt'
SHIFT = 'Shift'
META = 'Meta'
ADD = '+'
-- pressing control, alt, shift, and 'a' yields: 'Ctrl+Alt+Shift+A'

For key values less than 255, Lua’s string.char() is used to determine the key’s string representation. Otherwise, the KEYSYMS lookup table is used.

Normally, Lua functions are assigned to key commands, but those functions are called without any arguments. In order to pass arguments to a function, assign a table to the key command. This table contains the function followed by its arguments in order. Any buffer or view references are handled correctly at runtime.

Key commands can be chained like in Emacs using keychain sequences. By default, the Esc key (Apple+Esc on Mac OSX) cancels the current keychain, but it can be redefined by re-defining CLEAR. Naturally, the clear sequence cannot be chained.

Precedence

When searching for a key command to execute in the keys table, key commands in the current lexer have priority, followed by the ones in the global table.

Propagation

Normally when the same key command is assigned to two separate functions of different precedence, the higher priority key command is run and the lower priority one is not. However, it is sometimes desirable to have the lower priority command run after the higher one. For example, Ctrl+Enter may trigger Adeptsense autocompletion in lexers that have Adeptsense, but should fall back on autocompleting words in the buffer if no Adeptsense completions are available. In order for this to happen, the first function has to return false (and only false; nil is not sufficient) when it wants to allow a lower priority function to run. Any other return value halts propagation and the key is consumed.

Example

keys = {
  ['ctrl+f'] = buffer.char_right
  ['ctrl+b'] = buffer.char_left,
  lua = {
    ['ctrl+f'] = { buffer.add_text, buffer, 'function' },
    ['ctrl+b'] = function() return false end
  }
}

The first two key commands are global and call buffer:char_right() and buffer:char_left() respectively. The last two commands apply only in the Lua lexer. If ctrl+f is pressed in a Lua file, the global key command with the same shortcut is overridden and function is added to the buffer. However, ctrl+b in a Lua file does not override its global command because of the false return. Instead, propagation occurs as described above.

Problems

All Lua functions must be defined before they are reference in key commands. Therefore, any module containing key commands should be loaded after all other modules, whose functions are being referenced, have been loaded.


Fields


CLEAR (string)

The string representing the key sequence that clears the current keychain. The default value is 'esc' (Escape).


LANGUAGE_MODULE_PREFIX (string)

The starting key command of the keychain reserved for language-specific modules. The default value is Ctrl/Cmd+L.


Tables


KEYSYMS

Lookup table for key codes higher than 255. If a key code given to keypress() is higher than 255, this table is used to return a string representation of the key if it exists.