Module modules.scite.keys
Manages key commands in SciTE. Key commands are defined in a separate key_commands.lua file that is located in the same directory or package.path. There are several option variables used: PLATFORM: OS platform (linux or windows) 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. ADD: The string representing used to join together a sequence of Control, Shift, or Alt modifier keys. KEYCHAIN_PROP: The SciTE property that will be updated each time the keychain is modified.
Usage
Syntax:
Key commands are defined in a user-defined table 'keys'. Scopes and Lexers
(discussed below) are indices of the keys table and are tables themselves.
Each string index in each of these tables is the key command. The table
containing the command to execute and an optional parameter is equated to
this key command. You can have global key commands of course.
For example:
local m_editing = modules.scite.editing
local m_snippets = modules.scite.snippets
keys = {
['ctrl+f'] = { editor.CharRight, editor },
['ctrl+b'] = { editor.CharLeft, editor },
ruby = {
['ctrl+e'] = { m_editing.ruby_exec },
whitespace = { -- whitespace scope (via lexer.lua)
['ctrl+f'] = { m_snippets.insert, 'function ${1:name}' }
}
}
}
The top-level key commands are global, the 'ruby' commands are global to a
buffer with Ruby syntax highlighting enabled, and the ruby.whitespace
command is executed in that buffer only when currently in Ruby's whitespace
scope.
Scopes and Lexers:
In the previous example, 'ruby' is the lexer's name and any named keys
are scopes in that lexer. See /lexers/lexer.lua for default named scopes.
Each individual lexer uses the 'add_style' function to add additional
styles/scopes to it, so use the string argument passed as the scope's
name.
Scope-insensitive key commands should be placed in the lexer table, and
lexer-insensitive key commands should be placed in the keys table.
By default scopes are enabled. To disable them, set the SCOPES_ENABLED
variable to false.
Order of execution precedence: Scope, Lexer, Global.
Key commands in the current scope have the first priority, commands in
the current lexer have the second, and global commands have the least
priority.
Declaring key commands: ['key_seq'] = { command [, arg] }
( e.g. ['ctrl+i'] = { modules.scite.snippets.insert } )
key_seq is the key sequence string compiled from the CTRL, SHIFT, ALT,
and ADD options (discussed below), command is the Lua function or SciTE
menu command number (defined in SciTE.h), and arg is an optional
argument. If I wanted to redefine the 'Open' menu command to be 'ctrl+r',
then I would do something like ['ctrl+r'] = { 102 } -- open.
Editor pane commands are kind of tricky at first. Their argument is the
editor pane itself. You can see this in the original example above.
The key character is ALWAYS lower case. There will be no such command as
['ctrl+I'].
The string representation of characters is used, so ['ctrl+/'] is a valid
key sequence. (See limitations of this below.)
The order of CTRL, SHIFT, and ALT is important. (C, CS, CA, CSA, etc.)
Chaining key commands:
Key commands can be chained like in Emacs. All you have to do create
nested tables as values of key commands.
For Example:
keys = {
['ctrl+x'] = {
['ctrl+s'] = { 106 } -- save
['ctrl+c'] = { 140 } -- quit
}
}
Remember to define a clear_sequence key sequence in the keys table
(Escape by default) in order to stop the current chain.
If a show_completions key sequence is defined, a list of completions for
the current chain will be displayed in the output pane.
The current key sequence is contained in the SciTE variable KeyChain.
(Appropriate for statusbar display)
Additional syntax options:
The text for CTRL, SHIFT, ALT, and ADD can be changed. ADD is the text
inserted between modifiers ('+' in the example above). They can be as
simple as c, s, a, [nothing] respectively. ( ['csao'] would be
ctrl+shift+alt+o )
Extensibility:
You don't have to define all of your key commands in one place. I have
Ruby-specific key commands in my ruby.lua file for example. All you need to
do is add to the keys table. ( e.g. keys.ruby = { ... } )
Note: additions to the keys table should be at the end of your *.lua file.
(See the reason behind this below.)
Limitations:
Certain keys that have values higher than 255 can not be used, except for
the keys that are located in the KEYSYMS table. When a key value higher
than 255 is encountered, its string value is looked up in KEYSYMS and
used in the sequence string.
In order for key commands to execute Lua functions properly, the Lua
functions must be defined BEFORE the key command references to it. This
is why the keys.lua module should be loaded LAST, and key commands added
at the bottom of *.lua scripts, after all global functions are defined.
The clear_sequence and show_completions key sequences cannot be chained.
Notes:
Redefining any menu Alt+key sequences will override them. So for example if
'alt+f' is defined, using Alt+F to access SciTE's File menu will no
longer work.
Setting ALTERNATIVE_KEYS to true enables my nano-emacs hybrid key layout.
Functions
| _G.OnKey (code, shift, control, alt) |
SciTE OnKey Lua extension function. |
| clear_key_sequence () |
Clears the current key sequence. |
| show_completions () |
Determines the possible completions for the current key sequence and prints them out. |
| try_get_cmd (active_table) |
[Local function] Helper function to get commands with the current keychain. |
| try_get_cmd1 (key_seq, lexer, scope) |
[Local function] Tries to get a key command based on the lexer and current scope. |
| try_get_cmd2 (key_seq, lexer) |
[Local function] Tries to get a key command based on the lexer. |
| try_get_cmd3 (key_seq) |
[Local function] Tries to get a global key command. |
Tables
| KEYSYMS |
[Local table] Lookup table for key values higher than 255. |
| keychain |
[Local table] The current key sequence. |
| keys |
Global container that holds all key commands. |
Functions
- _G.OnKey (code, shift, control, alt)
-
SciTE OnKey Lua extension function. It is called every time a key is pressed and determines which commands to execute or which new key in a chain to enter based on the current key sequence, lexer, and scope.
Parameters
-
code:
-
shift:
-
control:
-
alt:
Return value:
OnKey returns what the commands it executes return. If nothing is returned, OnKey returns true by default. A true return value will tell SciTE not to handle the key afterwords.
- clear_key_sequence ()
-
Clears the current key sequence.
- show_completions ()
-
Determines the possible completions for the current key sequence and prints them out. (Only prints key combinations, not command names.)
- try_get_cmd (active_table)
-
[Local function] Helper function to get commands with the current keychain. If the current item in the keychain is part of a chain, throw an error value of -1. This way, pcall will return false and -1, where the -1 can easily and efficiently be checked rather than using a string error message.
Parameters
- try_get_cmd1 (key_seq, lexer, scope)
-
[Local function] Tries to get a key command based on the lexer and current scope.
Parameters
- try_get_cmd2 (key_seq, lexer)
-
[Local function] Tries to get a key command based on the lexer.
Parameters
- try_get_cmd3 (key_seq)
-
[Local function] Tries to get a global key command.
Parameters
Tables
- KEYSYMS
- [Local table] Lookup table for key values higher than 255. If a key value given to OnKey is higher than 255, this table is used to return a string representation of the key if it exists.
- keychain
- [Local table] The current key sequence.
- keys
- Global container that holds all key commands.