diff options
Diffstat (limited to 'core/events.lua')
| -rw-r--r-- | core/events.lua | 254 |
1 files changed, 137 insertions, 117 deletions
diff --git a/core/events.lua b/core/events.lua index e5a73c8e..022ccad1 100644 --- a/core/events.lua +++ b/core/events.lua @@ -29,121 +29,128 @@ module('events', package.seeall) -- -- ## Textadept Events -- --- The following is a list of all Scintilla events generated by Textadept in --- `event_name(arguments)` format: +-- This is the set of default events that Textadept emits with the arguments +-- they pass. Events that modules emit are listed on their respective LuaDoc +-- pages. -- --- * **char\_added** (ch)<br /> --- Called when an ordinary text character is added to the buffer. --- - ch: the ASCII representation of the character. --- * **save\_point\_reached** ()<br /> --- Called when a save point is entered. --- * **save\_point\_left** ()<br /> --- Called when a save point is left. --- * **double\_click** (modifiers, position, line)<br /> --- Called when the mouse button is double-clicked. --- - modifiers: the appropriate combination of `SCI_SHIFT`, `SCI_CTRL`, --- and `SCI_ALT` to indicate the keys that were held down at the time of --- the double click. --- - position: the text position the click occured at. --- - line: the line number the click occured at. --- * **update\_ui** ()<br /> --- Called when the text or styling of the buffer has changed or the selection --- range has changed. --- * **margin\_click** (margin, modifiers, position)<br /> --- Called when the mouse is clicked inside a margin. --- - margin: the margin number that was clicked. --- - modifiers: the appropriate combination of `SCI_SHIFT`, `SCI_CTRL`, --- and `SCI_ALT` to indicate the keys that were held down at the time of --- the margin click. --- - position: The position of the start of the line in the buffer that +-- * `APPLEEVENT_ODOC`: Called when Mac OSX tells Textadept to open a document. +-- <br /> +-- * `uri`: The URI to open. +-- * `AUTO_C_CHAR_DELETED`: Called when the user deleted a character while the +-- autocompletion list was active. +-- * `AUTO_C_RELEASE`: Called when the user has cancelled the autocompletion +-- list. +-- * `AUTO_C_SELECTION`: Called when the user has selected an item in an +-- autocompletion list and before the selection is inserted. Automatic +-- insertion can be cancelled by calling `buffer:auto_c_cancel()` before +-- returning from the event handler.<br /> +-- * `text`: The text of the selection. +-- * `position`: The start position of the word being completed. +-- * `BUFFER_AFTER_SWITCH`: Called right after a buffer is switched to. +-- * `BUFFER_BEFORE_SWITCH`: Called right before another buffer is switched to. +-- * `BUFFER_DELETED`: Called after a buffer was deleted. +-- * `BUFFER_NEW`: Called when a new buffer is created. +-- * `CALL_TIP_CLICK`: Called when the user clicks on a calltip. +-- <br /> +-- * `position`: Set to 1 if the click is in an up arrow, 2 if in a down +-- arrow, and 0 if elsewhere. +-- * `CHAR_ADDED`: Called when an ordinary text character is added to the +-- buffer.<br /> +-- * `ch`: The text character byte. +-- * `COMMAND_ENTRY_COMMAND`: Called when a command is entered into the Command +-- Entry.<br /> +-- * `command`: The command text. +-- * `COMMAND_ENTRY_KEYPRESS`: Called when a key is pressed in the Command +-- Entry.<br /> +-- * `code`: The key code. +-- * `shift`: The Shift key is held down. +-- * `ctrl`: The Control key is held down. +-- * `alt`: The Alt/Apple key is held down. +-- * `DOUBLE_CLICK`: Called when the mouse button is double-clicked.<br /> +-- * `position`: The text position of the double click. +-- * `line`: The line of the double click. +-- * `modifiers`: The key modifiers held down. It is a combination of zero +-- or more of `_SCINTILLA.constants.SCMOD_ALT`, +-- `_SCINTILLA.constants.SCMOD_CTRL`, +-- `_SCINTILLA.constants.SCMOD_SHIFT`, and +-- `_SCINTILLA.constants.SCMOD_META`. +-- * `ERROR`: Called when an error occurs.<br /> +-- * `text`: The error text. +-- * `FIND`: Called when finding text via the Find dialog box.<br /> +-- * `text`: The text to search for. +-- * `next`: Search forward. +-- * `HOTSPOT_CLICK`: Called when the user clicks on text that is in a style +-- with the hotspot attribute set.<br /> +-- * `position`: The text position of the click. +-- * `modifiers`: The key modifiers held down. It is a combination of zero +-- or more of `_SCINTILLA.constants.SCMOD_ALT`, +-- `_SCINTILLA.constants.SCMOD_CTRL`, +-- `_SCINTILLA.constants.SCMOD_SHIFT`, and +-- `_SCINTILLA.constants.SCMOD_META`. +-- * `HOTSPOT_DOUBLE_CLICK`: Called when the user double clicks on text that is +-- in a style with the hotspot attribute set.<br /> +-- * `position`: The text position of the double click. +-- * `modifiers`: The key modifiers held down. It is a combination of zero +-- or more of `_SCINTILLA.constants.SCMOD_ALT`, +-- `_SCINTILLA.constants.SCMOD_CTRL`, +-- `_SCINTILLA.constants.SCMOD_SHIFT`, and +-- `_SCINTILLA.constants.SCMOD_META`. +-- * `HOTSPOT_RELEASE_CLICK`: Called when the user releases the mouse on text +-- that is in a style with the hotspot attribute set.<br /> +-- * `position`: The text position of the release. +-- * `INDICATOR_CLICK`: Called when the user clicks the mouse on text that has +-- an indicator.<br /> +-- * `position`: The text position of the click. +-- * `modifiers`: The key modifiers held down. It is a combination of zero +-- or more of `_SCINTILLA.constants.SCMOD_ALT`, +-- `_SCINTILLA.constants.SCMOD_CTRL`, +-- `_SCINTILLA.constants.SCMOD_SHIFT`, and +-- `_SCINTILLA.constants.SCMOD_META`. +-- * `INDICATOR_RELEASE`: Called when the user releases the mouse on text that +-- has an indicator.<br /> +-- * `position`: The text position of the release. +-- * `KEYPRESS`: Called when a key is pressed.<br /> +-- * `code`: The key code. +-- * `shift`: The Shift key is held down. +-- * `ctrl`: The Control key is held down. +-- * `alt`: The Alt/Apple key is held down. +-- * `MARGIN_CLICK`: Called when the mouse is clicked inside a margin.<br /> +-- * `margin`: The margin number that was clicked. +-- * `position`: The position of the start of the line in the buffer that -- corresponds to the margin click. --- * **user\_list\_selection** (wParam, text, position)<br /> --- Called when the user has selected an item in a user list. --- - wParam: the list_type parameter from --- [`buffer:user_list_show()`][buffer_user_list_show]. --- - text: the text of the selection. --- - position: the position the list was displayed at. --- * **uri\_dropped** (text)<br /> --- Called when the user has dragged a URI such as a file name or web address --- into Textadept. --- - text: URI text. --- * **hotspot\_click** (position, modifiers)<br /> --- Called when the user clicks on a hotspot. --- - position: the position in the buffer that the user clicked --- - modifiers: the appropriate combination of `SCI_SHIFT`, `SCI_CTRL`, --- and `SCI_ALT` to indicate the keys that were held down at the time of --- the hotspot click. --- * **hotspot\_double\_click** (position, modifiers)<br /> --- Called when the user double-clicks on a hotspot. --- - position: the position in the buffer that the user double-clicked --- - modifiers: the appropriate combination of `SCI_SHIFT`, `SCI_CTRL`, --- and `SCI_ALT` to indicate the keys that were held down at the time of --- the hotspot double-click. --- * **call\_tip\_click** (position)<br /> --- Called when the user clicks on a calltip. --- - position: 1 if the click is in an up arrow, 2 if in a down arrow, and --- 0 if elsewhere. --- * **auto\_c\_selection** (text, position)<br /> --- Called when the user has selected an item in an autocompletion list. --- - text: the text of the selection. --- - position: the start position of the word being completed. --- * **indicator\_click** (position, modifiers)<br /> --- Called when the user clicks on an indicator. --- - position: the position in the buffer that the user clicked. --- - modifiers: the appropriate combination of `SCI_SHIFT`, `SCI_CTRL`, --- and `SCI_ALT` to indicate the keys that were held down at the time of --- the indicator click. --- * **indicator\_release** (position)<br /> --- Called when the user releases the mouse button after clicking on an --- indicator. --- - position: the position in the buffer that the user clicked. --- * **auto\_c\_cancelled** ()<br /> --- Called when the user has cancelled the autocompletion list. --- * **auto\_c\_char\_deleted** ()<br /> --- Called when the user deleted a character while the autocompletion list was --- active. --- * **hotspot\_release\_click** (position)<br /> --- Called when the user releases the mouse button after clicking on a hotspot. --- - position: the position in the buffer that the user clicked. --- --- [buffer_user_list_show]: ../modules/buffer.html#buffer:user_list_show --- --- The following is a list of gui events generated in --- `event_name(arguments)` format: --- --- * **buffer\_new** ()<br /> --- Called when a new [buffer][buffer] is created. --- * **buffer\_deleted** ()<br /> --- Called when a [buffer][buffer] has been deleted. --- * **buffer\_before\_switch** ()<br /> --- Called right before another [buffer][buffer] is switched to. --- * **buffer\_after\_switch** ()<br /> --- Called right after a [buffer][buffer] was switched to. --- * **view\_new** ()<br /> --- Called when a new [view][view] is created. --- * **view\_before\_switch** ()<br /> --- Called right before another [view][view] is switched to. --- * **view\_after\_switch** ()<br /> --- Called right after [view][view] was switched to. --- * **reset\_before** ()<br /> --- Called before resetting the Lua state during a call to [`reset()`][reset]. --- * **reset\_after** ()<br /> --- Called after resetting the Lua state during a call to [`reset()`][reset]. --- * **quit** ()<br /> --- Called when quitting Textadept.<br /> --- Note: Any quit handlers added must be inserted at index 1 because the --- default quit handler in `core/events.lua` returns `true`, which ignores all --- subsequent handlers. --- * **error** (text)<br /> --- Called when an error occurs in the C code. --- - text: The error text. --- * **appleevent\_odoc** (uri)<br /> --- Called when Mac OSX instructs Textadept to open a document. --- - uri: The URI to open. --- --- [buffer]: ../modules/buffer.html --- [view]: ../modules/view.html --- [reset]: ../modules/_G.html#reset +-- * `modifiers`: The appropriate combination of +-- `_SCINTILLA.constants.SCI_SHIFT`, `_SCINTILLA.constants.SCI_CTRL`, +-- and `_SCINTILLA.constants.SCI_ALT` to indicate the keys that were +-- held down at the time of the margin click. +-- * `MENU_CLICKED`: Called when a menu item is selected.<br /> +-- * `menu_id`: The numeric ID of the menu item set in `gui.gtkmenu()`. +-- * `QUIT`: Called when quitting Textadept. When connecting to this event, +-- connect with an index of 1 or the handler will be ignored. +-- * `REPLACE`: Called to replace selected (found) text.<br /> +-- * `text`: The text to replace selected text with. +-- * `REPLACE_ALL`: Called to replace all occurances of found text.<br /> +-- * `find_text`: The text to search for. +-- * `repl_text`: The text to replace found text with. +-- * `RESET_AFTER`: Called after resetting the Lua state. This is triggered by +-- `_G.reset()`. +-- * `RESET_BEFORE`: Called before resetting the Lua state. This is triggered by +-- `_G.reset()`. +-- * `SAVE_POINT_LEFT`: Called when a save point is left. +-- * `SAVE_POINT_REACHED`: Called when a save point is entered. +-- * `UPDATE_UI`: Called when either the text or styling of the buffer has +-- changed or the selection range has changed. +-- * `URI_DROPPED`: Called when the user has dragged a URI such as a file name +-- onto the view.<br /> +-- * `text`: The URI text. +-- * `USER_LIST_SELECTION`: Called when the user has selected an item in a user +-- list.<br /> +-- * `list_type`: This is set to the list_type parameter from the +-- `buffer:user_list_show()` call that initiated the list. +-- * `text`: The text of the selection. +-- * `position`: The position the list was displayed at. +-- * `VIEW_NEW`: Called when a new view is created. +-- * `VIEW_BEFORE_SWITCH`: Called right before another view is switched to. +-- * `VIEW_AFTER_SWITCH`: Called right after another view is switched to. -- -- ## Example -- @@ -154,7 +161,7 @@ module('events', package.seeall) -- end -- -- events.connect('my_event', my_event_handler) --- events.emit('my_event', 'my message') +-- events.emit('my_event', 'my message') -- prints 'my message' to a view --- -- A table of event names and a table of functions connected to them. @@ -173,6 +180,7 @@ local handlers = handlers -- @return Index of handler. -- @see disconnect function connect(event, f, index) + if not event then error(L('Undefined event name')) end if not handlers[event] then handlers[event] = {} end local h = handlers[event] if index then table.insert(h, index, f) else h[#h + 1] = f end @@ -200,6 +208,7 @@ local error_emitted = false -- @param ... Arguments passed to the handler. -- @return true or false if any handler explicitly returned such; nil otherwise. function emit(event, ...) + if not event then error(L('Undefined event name')) end local h = handlers[event] if not h then return end local pcall, unpack, type = _G.pcall, _G.unpack, _G.type @@ -208,7 +217,7 @@ function emit(event, ...) if not ok then if not error_emitted then error_emitted = true - emit('error', result) + emit(events.ERROR, result) error_emitted = false else io.stderr:write(result) @@ -224,9 +233,9 @@ local scnnotifications = { [c.SCN_CHARADDED] = { 'char_added', 'ch' }, [c.SCN_SAVEPOINTREACHED] = { 'save_point_reached' }, [c.SCN_SAVEPOINTLEFT] = { 'save_point_left' }, - [c.SCN_DOUBLECLICK] = { 'double_click', 'modifiers', 'position', 'line' }, + [c.SCN_DOUBLECLICK] = { 'double_click', 'position', 'line', 'modifiers' }, [c.SCN_UPDATEUI] = { 'update_ui' }, - [c.SCN_MARGINCLICK] = { 'margin_click', 'margin', 'modifiers', 'position' }, + [c.SCN_MARGINCLICK] = { 'margin_click', 'margin', 'position', 'modifiers' }, [c.SCN_USERLISTSELECTION] = { 'user_list_selection', 'wParam', 'text', 'position' }, @@ -255,3 +264,14 @@ function notification(n) for i = 2, #f do args[i - 1] = n[f[i]] end return emit(f[1], unpack(args)) end + +-- Set event constants. +for _, n in pairs(scnnotifications) do _M[n[1]:upper()] = n[1] end +local ta_events = { + 'appleevent_odoc', 'buffer_after_switch', 'buffer_before_switch', + 'buffer_deleted', 'buffer_new', 'command_entry_command', + 'command_entry_keypress', 'error', 'find', 'keypress', 'menu_clicked', 'quit', + 'replace', 'replace_all', 'reset_after', 'reset_before', 'view_after_switch', + 'view_before_switch', 'view_new' +} +for _, e in pairs(ta_events) do _M[e:upper()] = e end |