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
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
|
-- Copyright 2007-2020 Mitchell mitchell.att.foicica.com. See LICENSE.
local M = {}
--[[ This comment is for LuaDoc.
---
-- Textadept's core event structure and handlers.
--
-- Textadept emits events when you do things like create a new buffer, press a
-- key, click on a menu, etc. You can even emit events yourself using Lua. Each
-- event has a set of event handlers, which are simply Lua functions called in
-- the order they were connected to an event. For example, if you created a
-- module that needs to do something each time Textadept creates a new buffer,
-- connect a Lua function to the [`events.BUFFER_NEW`]() event:
--
-- events.connect(events.BUFFER_NEW, function()
-- -- Do something here.
-- end)
--
-- Events themselves are nothing special. You do not have to declare one before
-- using it. Events are simply strings containing arbitrary event names. When
-- either you or Textadept emits an event, Textadept runs all event handlers
-- connected to the event, passing any given arguments to the event's handler
-- functions. If an event handler explicitly returns a value that is not `nil`,
-- Textadept will not call subsequent handlers. This is useful if you want to
-- stop the propagation of an event like a keypress if your event handler
-- handled it, or if you want to use the event framework to pass values.
--
-- @field APPLEEVENT_ODOC (string)
-- Emitted when macOS tells Textadept to open a file.
-- Arguments:
--
-- * _`uri`_: The UTF-8-encoded URI to open.
-- @field AUTO_C_CHAR_DELETED (string)
-- Emitted after deleting a character while an autocompletion or user list is
-- active.
-- @field AUTO_C_CANCELED (string)
-- Emitted when canceling an autocompletion or user list.
-- @field AUTO_C_COMPLETED (string)
-- Emitted after inserting an item from an autocompletion list into the
-- buffer.
-- Arguments:
--
-- * _`text`_: The selection's text.
-- * _`position`_: The autocompleted word's beginning position.
-- @field AUTO_C_SELECTION (string)
-- Emitted after selecting an item from an autocompletion list, but before
-- inserting that item into the buffer.
-- Automatic insertion can be canceled by calling
-- [`buffer:auto_c_cancel()`]() before returning from the event handler.
-- Arguments:
--
-- * _`text`_: The selection's text.
-- * _`position`_: The autocompleted word's beginning position.
-- @field AUTO_C_SELECTION_CHANGE (string)
-- Emitted as items are highlighted in an autocompletion or user list.
-- Arguments:
--
-- * _`id`_: Either the *id* from [`buffer.user_list_show()`]() or `0` for an
-- autocompletion list.
-- * _`text`_: The current selection's text.
-- * _`position`_: The position the list was displayed at.
-- @field BUFFER_AFTER_SWITCH (string)
-- Emitted right after switching to another buffer.
-- The buffer being switched to is `buffer`.
-- Emitted by [`view.goto_buffer()`]().
-- @field BUFFER_BEFORE_SWITCH (string)
-- Emitted right before switching to another buffer.
-- The buffer being switched from is `buffer`.
-- Emitted by [`view.goto_buffer()`]().
-- @field BUFFER_DELETED (string)
-- Emitted after deleting a buffer.
-- Emitted by [`buffer.delete()`]().
-- @field BUFFER_NEW (string)
-- Emitted after creating a new buffer.
-- The new buffer is `buffer`.
-- Emitted on startup and by [`buffer.new()`]().
-- @field CALL_TIP_CLICK (string)
-- Emitted when clicking on a calltip.
-- Arguments:
--
-- * _`position`_: `1` if the up arrow was clicked, 2 if the down arrow was
-- clicked, and 0 otherwise.
-- @field CHAR_ADDED (string)
-- Emitted after the user types a text character into the buffer.
-- Arguments:
--
-- * _`code`_: The text character's character code.
-- @field COMMAND_TEXT_CHANGED (string)
-- Emitted when the text in the command entry changes.
-- `ui.command_entry:get_text()` returns the current text.
-- @field DOUBLE_CLICK (string)
-- Emitted after double-clicking the mouse button.
-- Arguments:
--
-- * _`position`_: The position double-clicked.
-- * _`line`_: The line number of the position double-clicked.
-- * _`modifiers`_: A bit-mask of any modifier keys used: `view.MOD_CTRL`,
-- `view.MOD_SHIFT`, `view.MOD_ALT`, and `view.MOD_META`.
-- On macOS, the Command modifier key is reported as `view.MOD_CTRL` and
-- Ctrl is `view.MOD_META`.
-- Note: If you set `view.rectangular_selection_modifier` to
-- `view.MOD_CTRL`, the "Control" modifier is reported as *both* "Control"
-- and "Alt" due to a Scintilla limitation with GTK.
-- @field CSI (string)
-- Emitted when the terminal version receives an unrecognized CSI sequence.
-- Arguments:
--
-- * _`cmd`_: The 24-bit CSI command value. The lowest byte contains the
-- command byte. The second lowest byte contains the leading byte, if any
-- (e.g. '?'). The third lowest byte contains the intermediate byte, if any
-- (e.g. '$').
-- * _`args`_: Table of numeric arguments of the CSI sequence.
-- @field DWELL_END (string)
-- Emitted after `DWELL_START` when the user moves the mouse, presses a key,
-- or scrolls the view.
-- Arguments:
--
-- * _`position`_: The position closest to *x* and *y*.
-- * _`x`_: The x-coordinate of the mouse in the view.
-- * _`y`_: The y-coordinate of the mouse in the view.
-- @field DWELL_START (string)
-- Emitted when the mouse is stationary for [`view.mouse_dwell_time`]()
-- milliseconds.
-- Arguments:
--
-- * _`position`_: The position closest to *x* and *y*.
-- * _`x`_: The x-coordinate of the mouse in the view.
-- * _`y`_: The y-coordinate of the mouse in the view.
-- @field ERROR (string)
-- Emitted when an error occurs.
-- Arguments:
--
-- * _`text`_: The error message text.
-- @field FIND (string)
-- Emitted to find text via the Find & Replace Pane.
-- Arguments:
--
-- * _`text`_: The text to search for.
-- * _`next`_: Whether or not to search forward.
-- @field FIND_TEXT_CHANGED (string)
-- Emitted when the text in the "Find" field of the Find & Replace Pane
-- changes.
-- `ui.find.find_entry_text` contains the current text.
-- @field FOCUS (string)
-- Emitted when Textadept receives focus.
-- This event is never emitted when Textadept is running in the terminal.
-- @field INDICATOR_CLICK (string)
-- Emitted when clicking the mouse on text that has an indicator present.
-- Arguments:
--
-- * _`position`_: The clicked text's position.
-- * _`modifiers`_: A bit-mask of any modifier keys used: `view.MOD_CTRL`,
-- `view.MOD_SHIFT`, `view.MOD_ALT`, and `view.MOD_META`.
-- On macOS, the Command modifier key is reported as `view.MOD_CTRL` and
-- Ctrl is `view.MOD_META`.
-- Note: If you set `view.rectangular_selection_modifier` to
-- `view.MOD_CTRL`, the "Control" modifier is reported as *both* "Control"
-- and "Alt" due to a Scintilla limitation with GTK.
-- @field INDICATOR_RELEASE (string)
-- Emitted when releasing the mouse after clicking on text that has an
-- indicator present.
-- Arguments:
--
-- * _`position`_: The clicked text's position.
-- @field INITIALIZED (string)
-- Emitted after Textadept finishes initializing.
-- @field KEYPRESS (string)
-- Emitted when pressing a key.
-- If any handler returns `true`, the key is not inserted into the buffer.
-- Arguments:
--
-- * _`code`_: The numeric key code.
-- * _`shift`_: The "Shift" modifier key is held down.
-- * _`ctrl`_: The "Control" modifier key is held down.
-- * _`alt`_: The "Alt"/"Option" modifier key is held down.
-- * _`cmd`_: The "Command" modifier key on macOS is held down.
-- * _`caps_lock`_: The "Caps Lock" modifier is on.
-- @field MARGIN_CLICK (string)
-- Emitted when clicking the mouse inside a sensitive margin.
-- Arguments:
--
-- * _`margin`_: The margin number clicked.
-- * _`position`_: The beginning position of the clicked margin's line.
-- * _`modifiers`_: A bit-mask of any modifier keys used: `view.MOD_CTRL`,
-- `view.MOD_SHIFT`, `view.MOD_ALT`, and `view.MOD_META`.
-- On macOS, the Command modifier key is reported as `view.MOD_CTRL` and
-- Ctrl is `view.MOD_META`.
-- Note: If you set `view.rectangular_selection_modifier` to
-- `view.MOD_CTRL`, the "Control" modifier is reported as *both* "Control"
-- and "Alt" due to a Scintilla limitation with GTK.
-- @field MENU_CLICKED (string)
-- Emitted after selecting a menu item.
-- Arguments:
--
-- * _`menu_id`_: The numeric ID of the menu item, which was defined in
-- [`ui.menu()`]().
-- @field MOUSE (string)
-- Emitted by the terminal version for an unhandled mouse event.
-- A handler should return `true` if it handled the event. Otherwise Textadept
-- will try again. (This side effect for a `false` or `nil` return is useful
-- for sending the original mouse event to a different view that a handler
-- has switched to.)
-- Arguments:
--
-- * _`event`_: The mouse event: `view.MOUSE_PRESS`, `view.MOUSE_DRAG`, or
-- `view.MOUSE_RELEASE`.
-- * _`button`_: The mouse button number.
-- * _`y`_: The y-coordinate of the mouse event, starting from 1.
-- * _`x`_: The x-coordinate of the mouse event, starting from 1.
-- * _`shift`_: The "Shift" modifier key is held down.
-- * _`ctrl`_: The "Control" modifier key is held down.
-- * _`alt`_: The "Alt"/"Option" modifier key is held down.
-- @field QUIT (string)
-- Emitted when quitting Textadept.
-- When connecting to this event, connect with an index of 1 if the handler
-- needs to run before Textadept closes all open buffers. If a handler returns
-- `true`, Textadept does not quit. It is not recommended to return `false`
-- from a quit handler, as that may interfere with Textadept's normal shutdown
-- procedure.
-- Emitted by [`quit()`]().
-- @field REPLACE (string)
-- Emitted to replace selected (found) text.
-- Arguments:
--
-- * _`text`_: The replacement text.
-- @field REPLACE_ALL (string)
-- Emitted to replace all occurrences of found text.
-- Arguments:
--
-- * _`find_text`_: The text to search for.
-- * _`repl_text`_: The replacement text.
-- @field RESET_AFTER (string)
-- Emitted after resetting the Lua state.
-- Emitted by [`reset()`]().
-- Arguments:
--
-- * _`persist`_: Table of data persisted by `events.RESET_BEFORE`. All
-- handlers will have access to this same table.
-- @field RESET_BEFORE (string)
-- Emitted before resetting the Lua state.
-- Emitted by [`reset()`]().
-- Arguments:
--
-- * _`persist`_: Table to store persistent data in for use by
-- `events.RESET_AFTER`. All handlers will have access to this same table.
-- @field RESUME (string)
-- Emitted when resuming Textadept from a suspended state.
-- This event is only emitted by the terminal version.
-- @field SAVE_POINT_LEFT (string)
-- Emitted after leaving a save point.
-- @field SAVE_POINT_REACHED (string)
-- Emitted after reaching a save point.
-- @field SUSPEND (string)
-- Emitted when suspending Textadept. If any handler returns `true`, Textadept
-- does not suspend.
-- This event is only emitted by the terminal version.
-- @field TAB_CLICKED (string)
-- Emitted when the user clicks on a buffer tab.
-- When connecting to this event, connect with an index of 1 if the handler
-- needs to run before Textadept switches between buffers.
-- Note that Textadept always displays a context menu on right-click.
-- Arguments:
--
-- * _`index`_: The numeric index of the clicked tab.
-- * _`button`_: The mouse button number that was clicked, either `1` (left
-- button), `2` (middle button), `3` (right button), `4` (wheel up), or `5`
-- (wheel down).
-- * _`shift`_: The "Shift" modifier key is held down.
-- * _`ctrl`_: The "Control" modifier key is held down.
-- * _`alt`_: The "Alt"/"Option" modifier key is held down.
-- * _`cmd`_: The "Command" modifier key on macOS is held down.
-- @field UPDATE_UI (string)
-- Emitted after the view is visually updated.
-- Arguments:
--
-- * _`updated`_: A bitmask of changes since the last update.
--
-- + `buffer.UPDATE_CONTENT`
-- Buffer contents, styling, or markers have changed.
-- + `buffer.UPDATE_SELECTION`
-- Buffer selection has changed (including caret movement).
-- + `view.UPDATE_V_SCROLL`
-- Buffer has scrolled vertically.
-- + `view.UPDATE_H_SCROLL`
-- Buffer has scrolled horizontally.
-- @field URI_DROPPED (string)
-- Emitted after dragging and dropping a URI into a view.
-- Arguments:
--
-- * _`text`_: The UTF-8-encoded URI dropped.
-- @field USER_LIST_SELECTION (string)
-- Emitted after selecting an item in a user list.
-- Arguments:
--
-- * _`id`_: The *id* from [`buffer.user_list_show()`]().
-- * _`text`_: The selection's text.
-- * _`position`_: The position the list was displayed at.
-- @field VIEW_NEW (string)
-- Emitted after creating a new view.
-- The new view is `view`.
-- Emitted on startup and by [`view.split()`]().
-- @field VIEW_BEFORE_SWITCH (string)
-- Emitted right before switching to another view.
-- The view being switched from is `view`.
-- Emitted by [`ui.goto_view()`]().
-- @field VIEW_AFTER_SWITCH (string)
-- Emitted right after switching to another view.
-- The view being switched to is `view`.
-- Emitted by [`ui.goto_view()`]().
-- @field ZOOM (string)
-- Emitted after changing [`view.zoom`]().
-- Emitted by [`view.zoom_in()`]() and [`view.zoom_out()`]().
module('events')]]
-- Map of event names to tables of handler functions.
-- Handler tables are auto-created as needed.
-- @class table
-- @name handlers
local handlers = setmetatable({}, {__index = function(t, k)
t[k] = {}
return t[k]
end})
---
-- Adds function *f* to the set of event handlers for event *event* at position
-- *index*.
-- If *index* not given, appends *f* to the set of handlers. *event* may be any
-- arbitrary string and does not need to have been previously defined.
-- @param event The string event name.
-- @param f The Lua function to connect to *event*.
-- @param index Optional index to insert the handler into.
-- @usage events.connect('my_event', function(msg) ui.print(msg) end)
-- @see disconnect
-- @name connect
function M.connect(event, f, index)
assert_type(event, 'string', 1)
assert_type(f, 'function', 2)
assert_type(index, 'number/nil', 3)
M.disconnect(event, f) -- in case it already exists
table.insert(handlers[event], index or #handlers[event] + 1, f)
end
---
-- Removes function *f* from the set of handlers for event *event*.
-- @param event The string event name.
-- @param f The Lua function connected to *event*.
-- @see connect
-- @name disconnect
function M.disconnect(event, f)
assert_type(f, 'function', 2)
for i = 1, #handlers[assert_type(event, 'string', 1)] do
if handlers[event][i] == f then table.remove(handlers[event], i) break end
end
end
local error_emitted = false
---
-- Sequentially calls all handler functions for event *event* with the given
-- arguments.
-- *event* may be any arbitrary string and does not need to have been previously
-- defined. If any handler explicitly returns a value that is not `nil`,
-- `emit()` returns that value and ceases to call subsequent handlers. This is
-- useful for stopping the propagation of an event like a keypress after it has
-- been handled, or for passing back values from handlers.
-- @param event The string event name.
-- @param ... Arguments passed to the handler.
-- @return `nil` unless any any handler explicitly returned a non-`nil` value;
-- otherwise returns that value
-- @usage events.emit('my_event', 'my message')
-- @name emit
function M.emit(event, ...)
local event_handlers = handlers[assert_type(event, 'string', 1)]
local i = 1
while i <= #event_handlers do
local handler = event_handlers[i]
local ok, result = pcall(handler, ...)
if not ok then
if not error_emitted then
error_emitted = true
M.emit(events.ERROR, result)
error_emitted = false
else
io.stderr:write(result) -- prevent infinite loop
end
end
if result ~= nil then return result end
if event_handlers[i] == handler then i = i + 1 end -- unless M.disconnect()
end
end
-- Handles Scintilla notifications.
M.connect('SCN', function(notification)
local f = _SCINTILLA.events[notification.code]
if not f then return end
local args = {}
for i = 2, #f do args[i - 1] = notification[f[i]] end
return M.emit(f[1], table.unpack(args))
end)
-- Set event constants.
for _, v in pairs(_SCINTILLA.events) do M[v[1]:upper()] = v[1] end
local textadept_events = {'appleevent_odoc','buffer_after_switch','buffer_before_switch','buffer_deleted','buffer_new','csi','command_text_changed','error','find','find_text_changed','focus','initialized','keypress','menu_clicked','mouse','quit','replace','replace_all','reset_after','reset_before','resume','suspend', 'tab_clicked','view_after_switch','view_before_switch','view_new'}
for _, v in pairs(textadept_events) do M[v:upper()] = v end
return M
|