1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
|
-- Copyright 2007-2012 Mitchell mitchell.att.foicica.com. See LICENSE.
local M = {}
--[[ This comment is for LuaDoc.
---
-- Manages key commands in Textadept.
module('keys')]]
-- Markdown:
-- ## 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`](#KEYSYMS) lookup
-- table is used.
--
-- [`string.char()`]: http://www.lua.org/manual/5.2/manual.html#pdf-string.char
--
-- 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.
--
-- [buffer]: buffer.html
-- [view]: view.html
--
-- 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 setting the `keys.CLEAR` field. Naturally, the
-- clear sequence cannot be chained.
--
-- ## Settings
--
-- + `CTRL` [string]
-- The string representing the Control key.
-- The default value is 'c'.
-- + `ALT` [string]
-- The string representing the Alt/option key.
-- The default value is 'a'.
-- + `META` [string]
-- The string representing the Command key on Mac OSX.
-- The default value is 'm'.
-- + `SHIFT` [string]
-- The string representing the Shift key.
-- The default value is 's'.
-- + `ADD` [string]
-- The string representing used to join together a sequence of Control, Alt,
-- Meta, or Shift modifier keys.
-- The default value is ''.
-- * `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.
--
-- ## 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.
local ADD = ''
local CTRL, ALT, META, SHIFT = 'c'..ADD, 'a'..ADD, 'm'..ADD, 's'..ADD
M.CLEAR = 'esc'
M.LANGUAGE_MODULE_PREFIX = (not OSX and CTRL or META)..'l'
-- Optimize for speed.
local OSX = OSX
local string = string
local string_byte, string_char = string.byte, string.char
local table_unpack = table.unpack
local xpcall, next, type = xpcall, next, type
local no_args = {}
local getmetatable = getmetatable
local error = function(e) events.emit(events.ERROR, e) end
---
-- 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.
-- @class table
-- @name KEYSYMS
M.KEYSYMS = { -- from <gdk/gdkkeysyms.h>
[0xFE20] = '\t', -- backtab; will be 'shift'ed
[0xFF08] = '\b',
[0xFF09] = '\t',
[0xFF0D] = '\n',
[0xFF1B] = 'esc',
[0xFFFF] = 'del',
[0xFF50] = 'home',
[0xFF51] = 'left', [0xFF52] = 'up',
[0xFF53] = 'right', [0xFF54] = 'down',
[0xFF55] = 'pgup', [0xFF56] = 'pgdn',
[0xFF57] = 'end',
[0xFF63] = 'ins',
[0xFF95] = 'kphome',
[0xFF96] = 'kpleft', [0xFF97] = 'kpup',
[0xFF98] = 'kpright', [0xFF99] = 'kpdown',
[0xFF9A] = 'kppgup', [0xFF9B] = 'kppgdn',
[0xFF9C] = 'kpend',
[0xFFAA] = 'kpmul', [0xFFAB] = 'kpadd',
[0xFFAD] = 'kpsub', [0xFFAF] = 'kpdiv',
[0xFFAE] = 'kpdec',
[0xFFB0] = 'kp0', [0xFFB1] = 'kp1', [0xFFB2] = 'kp2', [0xFFB3] = 'kp3',
[0xFFB4] = 'kp4', [0xFFB5] = 'kp5', [0xFFB6] = 'kp6', [0xFFB7] = 'kp7',
[0xFFB8] = 'kp8', [0xFFB9] = 'kp9',
[0xFFBE] = 'f1', [0xFFBF] = 'f2', [0xFFC0] = 'f3', [0xFFC1] = 'f4',
[0xFFC2] = 'f5', [0xFFC3] = 'f6', [0xFFC4] = 'f7', [0xFFC5] = 'f8',
[0xFFC6] = 'f9', [0xFFC7] = 'f10', [0xFFC8] = 'f11', [0xFFC9] = 'f12',
}
-- The current key sequence.
local keychain = {}
-- Clears the current key sequence.
local function clear_key_sequence()
if #keychain > 0 then keychain = {} end
gui.statusbar_text = ''
end
-- Runs a given command.
-- This is also used by `modules/textadept/menu.lua`.
-- @param command A function or table as described above.
-- @param command_type Equivalent to `type(command)`.
-- @return the value the command returns.
local function run_command(command, command_type)
local f, args = command_type == 'function' and command or command[1], no_args
if command_type == 'table' then
args = command
-- If the argument is a view or buffer, use the current one instead.
if type(args[2]) == 'table' then
local mt, buffer, view = getmetatable(args[2]), buffer, view
if mt == getmetatable(buffer) then
args[2] = buffer
elseif mt == getmetatable(view) then
args[2] = view
end
end
end
local _, result = xpcall(f, error, table_unpack(args, 2))
return result
end
M.run_command = run_command -- export for menu.lua without creating LuaDoc
-- Return codes for `run_key_command()`.
local INVALID, PROPAGATE, CHAIN, HALT = -1, 0, 1, 2
-- Runs a key command associated with the current keychain.
-- @param lexer Optional lexer name for lexer-specific commands.
-- @return `INVALID`, `PROPAGATE`, `CHAIN`, or `HALT`.
local function run_key_command(lexer)
local key, key_type = keys, type(keys)
if lexer and key_type == 'table' and key[lexer] then key = key[lexer] end
if type(key) ~= 'table' then return INVALID end
key = key[keychain[1]]
for i = 2, #keychain do
if type(key) ~= 'table' then return INVALID end
key = key[keychain[i]]
end
key_type = type(key)
if key_type ~= 'function' and key_type ~= 'table' then return INVALID end
if key_type == 'table' and #key == 0 and next(key) then
gui.statusbar_text = _L['Keychain:']..' '..table.concat(keychain, ' ')
return CHAIN
end
return run_command(key, key_type) == false and PROPAGATE or HALT
end
-- Handles Textadept keypresses.
-- It is called every time a key is pressed, and based on lexer, executes a
-- command. The command is looked up in the `_G.keys` table.
-- @param code The keycode.
-- @param shift Whether or not the Shift modifier is pressed.
-- @param control Whether or not the Control modifier is pressed.
-- @param alt Whether or not the Alt/option modifier is pressed.
-- @param meta Whether or not the Command modifier on Mac OSX is pressed.
-- @return `true` to stop handling the key; `nil` otherwise.
local function keypress(code, shift, control, alt, meta)
local buffer = buffer
local key
--print(code, M.KEYSYMS[ch], shift, control, alt, meta)
if code < 256 then
key = string_char(code)
shift = false -- for printable characters, key is upper case
else
key = M.KEYSYMS[code]
if not key then return end
end
local key_seq = (control and CTRL or '')..(alt and ALT or '')..
(meta and OSX and META or '')..(shift and SHIFT or '')..key
--print(key_seq)
if #keychain > 0 and key_seq == M.CLEAR then
clear_key_sequence()
return true
end
keychain[#keychain + 1] = key_seq
local success
for i = 1, 2 do
local status = run_key_command(i == 1 and buffer:get_lexer(true))
if status > 0 then -- CHAIN or HALT
if status == HALT then
-- Clear the key sequence, but keep any status messages from the key
-- command itself.
keychain = {}
local text = gui.statusbar_text or ''
if text == _L['Invalid sequence'] or text:find(_L['Keychain:']) then
gui.statusbar_text = ''
end
end
return true
end
success = success or status ~= -1
end
local size = #keychain - 1
clear_key_sequence()
if not success and size > 0 then -- INVALID keychain sequence
gui.statusbar_text = _L['Invalid sequence']
return true
end
-- PROPAGATE otherwise.
end
events.connect(events.KEYPRESS, keypress, 1)
-- Returns the GDK integer keycode and modifier mask for a key sequence.
-- This is used for creating menu accelerators.
-- @param key_seq The string key sequence.
-- @return keycode and modifier mask
local function get_gdk_key(key_seq)
if not key_seq then return nil end
local mods, key = key_seq:match('^([cams]*)(.+)$')
if not mods or not key then return nil end
local modifiers = ((mods:find('s') or key:lower() ~= key) and 1 or 0) +
(mods:find('c') and 4 or 0) + (mods:find('a') and 8 or 0) +
(mods:find('m') and 268435456 or 0)
local byte = string_byte(key)
if #key > 1 or byte < 32 then
for i, s in pairs(M.KEYSYMS) do
if s == key and i ~= 0xFE20 then byte = i break end
end
end
return byte, modifiers
end
M.get_gdk_key = get_gdk_key -- export for menu.lua without generating LuaDoc
return M
|