Textadept
- Home |
- Download |
- Lua API |
- Source |
- Language Modules |
- Stats |
- Wiki |
- Mailing List
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, a string key mode 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”, to be discussed below. When
searching for a command to run based on a key sequence, key bindings in the
current key mode have priority. If no key mode is active, 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 curses. 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 bound to 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'] = buffer.new
keys['cs'] = buffer.save
keys['a('] = {_M.textadept.editing.enclose, '(', ')'}
keys['cu'] = function() io.snapopen(_USERHOME) end
(The function and function table syntax are functionally equivalent. You can use either.)
buffer
references are handled properly in static contexts.
Modes
Sets of key bindings can be grouped together into modes. When a key mode is active, all key bindings defined outside the mode are ignored until the mode is unset. Here is a simple vi mode example:
keys.command_mode = {
['h'] = buffer.char_left,
['j'] = buffer.line_up,
['k'] = buffer.line_down,
['l'] = buffer.char_right,
['i'] = function()
keys.MODE = nil
gui.statusbar_text = 'INSERT MODE'
end
}
keys['esc'] = function() keys.MODE = 'command_mode' end
events.connect(events.UPDATE_UI, function()
if keys.MODE == 'command_mode' then return end
gui.statusbar_text = 'INSERT MODE'
end)
keys.MODE = 'command_mode' -- default mode
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 curses) 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
curses) 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 curses).
MODE
(string)
The current key mode.
When non-nil
, all key bindings defined outside of keys[MODE]
are
ignored.
The default value is nil
.
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.