Module _m.textadept.keys
Manages and defines key commands in Textadept. This set of key commands is pretty standard among other text editors.
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 action table.
- A string language name and its associated
keys-like table. - A string style name and its associated
keys-like table. - A string representing a key command and its associated
keys-like table. (This is a keychain sequence.)
A key command string is built from a combination of the CTRL, SHIFT,
ALT, and ADD constants as well as the pressed key itself. The value of
ADD is inserted between each of CTRL, SHIFT, ALT, and the key.
For example:
-- keys.lua:
CTRL = 'Ctrl'
SHIFT = 'Shift'
ALT = 'Alt'
ADD = '+'
-- pressing control, shift, alt and 'a' yields: 'Ctrl+Shift+Alt+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.
An action table is a table consisting of either:
- A Lua function followed by a list of arguments to pass to that function.
A string representing a buffer or view function followed by its respective
'buffer'or'view'string and then any arguments to pass to the resulting function.buffer.functionby itself cannot be used because at the time of evaluation,buffer.functionwould apply only to the current buffer, not for all buffers. By using this string reference system, the correctbuffer.functionwill be evaluated every time. The same applies toview.
Language names are the names of the lexer files in lexers/ such as cpp
and lua. Style names are different lexer styles, most of which are in
lexers/lexer.lua; examples are whitespace, comment, and string.
Key commands can be chained like in Emacs using keychain sequences. By
default, the Esc key cancels the current keychain, but it can be redefined
by setting the keys.clear_sequence field. Naturally, the clear sequence
cannot be chained.
Settings
SCOPES_ENABLED: Flag indicating whether scopes/styles can be used for key commands.CTRL: The string representing the Control key.SHIFT: The string representing the Shift key.ALT: The string representing the Alt key (the Apple key on Mac OSX).ADD: The string representing used to join together a sequence of Control, Shift, or Alt modifier keys.
Key Command Precedence
When searching for a key command to execute in the keys table, key commands
in the current style have priority, followed by the ones in the current lexer,
and finally the ones in the global table.
Example
keys = {
['ctrl+f'] = { 'char_right', 'buffer' },
['ctrl+b'] = { 'char_left', 'buffer' },
lua = {
['ctrl+c'] = { 'add_text', 'buffer', '-- ' },
whitespace = {
['ctrl+f'] = { function() print('whitespace') 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 with the very last one only being available in Lua's whitespace
style. If ctrl+f is pressed when the current style is whitespace in the
lua lexer, the global key command with the same shortcut is overridden and
whitespace is printed to standard out.
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.
Configuration
It is not recommended to edit Textadept's modules/textadept/keys.lua.
Instead you can modify _G.keys from within your ~/.textadept/init.lua or
from a file required by your init.lua.
Tables
| KEYSYMS | Lookup table for key values higher than 255. |
| _G.keys | Provides access to key commands from _G. |