Textadept
- Home |
- Download |
- Lua API |
- Source |
- Language Modules |
- Stats |
- Wiki |
- Mailing List
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:
- A string representing a key command and an associated function or table.
- A string language name and its associated
keys
-like table. - A string representing a key command and its associated
keys
-like table. (This is a keychain sequence.)
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.