diff options
Diffstat (limited to 'core/events.lua')
| -rw-r--r-- | core/events.lua | 252 |
1 files changed, 124 insertions, 128 deletions
diff --git a/core/events.lua b/core/events.lua index 9139a30a..46ee8f6c 100644 --- a/core/events.lua +++ b/core/events.lua @@ -27,241 +27,233 @@ local M = {} -- Called when Mac OSX tells Textadept to open a document. -- Arguments: -- --- * `uri`: The URI to open encoded in UTF-8. +-- * _`uri`_: The UTF-8-encoded URI to open. -- @field AUTO_C_CHAR_DELETED (string) --- Called when the user deleted a character while the autocompletion list was --- active. +-- Called when deleting a character while the autocompletion list is active. -- @field AUTO_C_RELEASE (string) --- Called when the user has cancelled the autocompletion list. +-- Called when canceling the autocompletion list. -- @field AUTO_C_SELECTION (string) --- Called when the user has selected an item in an autocompletion list and --- before the selection is inserted. +-- Called when selecting an item in the autocompletion list and before +-- inserting the selection. -- Automatic insertion can be cancelled by calling -- [`buffer:auto_c_cancel()`][] before returning from the event handler. -- Arguments: -- --- * `text`: The text of the selection. --- * `position`: The start position of the word being completed. +-- * _`text`_: The text of the selection. +-- * _`position`_: The position in the buffer of the beginning of the +-- autocompleted word. -- @field BUFFER_AFTER_SWITCH (string) --- Called right after a buffer is switched to. --- This is emitted by [`view:goto_buffer()`][]. +-- Called right after switching to another buffer. +-- Emitted by [`view:goto_buffer()`][]. -- @field BUFFER_BEFORE_SWITCH (string) --- Called right before another buffer is switched to. --- This is emitted by [`view:goto_buffer()`][]. +-- Called right before switching to another buffer. +-- Emitted by [`view:goto_buffer()`][]. -- @field BUFFER_DELETED (string) --- Called after a buffer was deleted. --- This is emitted by [`buffer:delete()`][]. +-- Called after deleting a buffer. +-- Emitted by [`buffer:delete()`][]. -- @field BUFFER_NEW (string) --- Called when a new buffer is created. --- This is emitted on startup and by [`new_buffer()`][]. +-- Called after creating a new buffer. +-- Emitted on startup and by [`new_buffer()`][]. -- @field CALL_TIP_CLICK (string) --- Called when the user clicks on a calltip. +-- Called when clicking on a calltip. -- Arguments: -- --- * `position`: Set to 1 if the click is in an up arrow, 2 if in a down --- arrow, and 0 if elsewhere. +-- * _`position`_: `1` if the up arrow was clicked, 2 if the down arrow was +-- clicked, and 0 otherwise. -- @field CHAR_ADDED (string) --- Called when an ordinary text character is added to the buffer. +-- Called after adding an ordinary text character to the buffer. -- Arguments: -- --- * `ch`: The text character byte. +-- * _`ch`_: The text character byte. -- @field COMMAND_ENTRY_COMMAND (string) --- Called when a command is entered into the Command Entry. +-- Called to run the command entered into the Command Entry. -- If any handler returns `true`, the Command Entry does not hide -- automatically. -- Arguments: -- --- * `command`: The command text. +-- * _`command`_: The command text. -- @field COMMAND_ENTRY_KEYPRESS (string) --- Called when a key is pressed in the Command Entry. +-- Called when pressing a key in the Command Entry. -- If any handler returns `true`, the key is not inserted into the entry. -- Arguments: -- --- * `code`: The key code. --- * `shift`: The "Shift" modifier key is held down. --- * `ctrl`: The "Control"/"Command" modifier key is held down. --- * `alt`: The "Alt"/"Option" modifier key is held down. --- * `meta`: The "Control" modifier key on Mac OSX is held down. +-- * _`code`_: The numeric key code. +-- * _`shift`_: The "Shift" modifier key is held down. +-- * _`ctrl`_: The "Control"/"Command" modifier key is held down. +-- * _`alt`_: The "Alt"/"Option" modifier key is held down. +-- * _`meta`_: The "Control" modifier key on Mac OSX is held down. -- @field DOUBLE_CLICK (string) --- Called when the mouse button is double-clicked. +-- Called after double-clicking the mouse button. -- Arguments: -- --- * `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`, +-- * _`position`_: The position in the buffer double-clicked. +-- * _`line`_: The line number double-clicked. +-- * _`modifiers`_: A bit-mask of modifier keys held down. Modifiers are +-- `_SCINTILLA.constants.SCMOD_ALT`, `_SCINTILLA.constants.SCMOD_CTRL`, -- `_SCINTILLA.constants.SCMOD_SHIFT`, and -- `_SCINTILLA.constants.SCMOD_META`. -- Note: If you set `buffer.rectangular_selection_modifier` to -- `_SCINTILLA.constants.SCMOD_CTRL`, the "Control" modifier is reported as -- *both* "Control" and "Alt" due to a Scintilla limitation with GTK+. -- @field DWELL_END (string) --- Called after a `DWELL_START` and the mouse is moved or other activity such --- as key press indicates the dwell is over. +-- Called after a `DWELL_START` when the mouse moves, a key is pressed, etc. -- Arguments: -- --- * `position`: The nearest position in the document to the position where --- the mouse pointer was lingering. --- * `x`: Where the pointer lingered. --- * `y`: Where the pointer lingered. +-- * _`position`_: The position in the buffer 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) --- Called when the user keeps the mouse in one position for the dwell period --- (see `_SCINTILLA.constants.SCI_SETMOUSEDWELLTIME`). +-- Called after keeping the mouse stationary for the [dwell period][] -- Arguments: -- --- * `position`: The nearest position in the document to the position where --- the mouse pointer was lingering. --- * `x`: Where the pointer lingered. --- * `y`: Where the pointer lingered. +-- * _`position`_: The position in the buffer 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) -- Called when an error occurs. -- Arguments: -- --- * `text`: The error text. +-- * _`text`_: The error text. -- @field FIND (string) --- Called when finding text via the Find dialog box. +-- Called to find text via the Find dialog box. -- Arguments: -- --- * `text`: The text to search for. --- * `next`: Search forward. +-- * _`text`_: The text to search for. +-- * _`next`_: Whether or not to search forward. -- @field HOTSPOT_CLICK (string) --- Called when the user clicks on text that is in a style with the hotspot --- attribute set. +-- Called when clicking on text that is in a style with the hotspot attribute +-- set. -- Arguments: -- --- * `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`, +-- * _`position`_: The position in the buffer clicked. +-- * _`modifiers`_: A bit-mask of modifier keys held down. Modifiers are +-- `_SCINTILLA.constants.SCMOD_ALT`, `_SCINTILLA.constants.SCMOD_CTRL`, -- `_SCINTILLA.constants.SCMOD_SHIFT`, and -- `_SCINTILLA.constants.SCMOD_META`. -- Note: If you set `buffer.rectangular_selection_modifier` to -- `_SCINTILLA.constants.SCMOD_CTRL`, the "Control" modifier is reported as -- *both* "Control" and "Alt" due to a Scintilla limitation with GTK+. -- @field HOTSPOT_DOUBLE_CLICK (string) --- Called when the user double clicks on text that is in a style with the --- hotspot attribute set. +-- Called when double-clicking on text that is in a style with the hotspot +-- attribute set. -- Arguments: -- --- * `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`, +-- * _`position`_: The position in the buffer double-clicked. +-- * _`modifiers`_: A bit-mask of modifier keys held down. Modifiers are +-- `_SCINTILLA.constants.SCMOD_ALT`, `_SCINTILLA.constants.SCMOD_CTRL`, -- `_SCINTILLA.constants.SCMOD_SHIFT`, and -- `_SCINTILLA.constants.SCMOD_META`. -- Note: If you set `buffer.rectangular_selection_modifier` to -- `_SCINTILLA.constants.SCMOD_CTRL`, the "Control" modifier is reported as -- *both* "Control" and "Alt" due to a Scintilla limitation with GTK+. -- @field HOTSPOT_RELEASE_CLICK (string) --- Called when the user releases the mouse on text that is in a style with the --- hotspot attribute set. +-- Called after releasing the mouse after clicking on text that was in a style +-- with the hotspot attribute set. -- Arguments: -- --- * `position`: The text position of the release. +-- * _`position`_: The position in the buffer unclicked. -- @field INDICATOR_CLICK (string) --- Called when the user clicks the mouse on text that has an indicator. +-- Called when clicking the mouse on text that has an indicator. -- Arguments: -- --- * `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`, +-- * _`position`_: The position in the buffer clicked. +-- * _`modifiers`_: A bit-mask of modifier keys held down. Modifiers are +-- `_SCINTILLA.constants.SCMOD_ALT`, `_SCINTILLA.constants.SCMOD_CTRL`, -- `_SCINTILLA.constants.SCMOD_SHIFT`, and -- `_SCINTILLA.constants.SCMOD_META`. -- Note: If you set `buffer.rectangular_selection_modifier` to -- `_SCINTILLA.constants.SCMOD_CTRL`, the "Control" modifier is reported as -- *both* "Control" and "Alt" due to a Scintilla limitation with GTK+. -- @field INDICATOR_RELEASE (string) --- Called when the user releases the mouse on text that has an indicator. +-- Called after releasing the mouse after clicking on text that had an +-- indicator. -- Arguments: -- --- * `position`: The text position of the release. +-- * _`position`_: The position in the buffer unclicked. -- @field KEYPRESS (string) --- Called when a key is pressed. +-- Called when pressing a key. -- If any handler returns `true`, the key is not inserted into the buffer. -- Arguments: -- --- * `code`: The key code. --- * `shift`: The "Shift" modifier key is held down. --- * `ctrl`: The "Control"/"Command" modifier key is held down. --- * `alt`: The "Alt"/"Option" modifier key is held down. --- * `meta`: The "Control" modifier key on Mac OSX is held down. +-- * _`code`_: The numeric key code. +-- * _`shift`_: The "Shift" modifier key is held down. +-- * _`ctrl`_: The "Control"/"Command" modifier key is held down. +-- * _`alt`_: The "Alt"/"Option" modifier key is held down. +-- * _`meta`_: The "Control" modifier key on Mac OSX is held down. -- @field MARGIN_CLICK (string) --- Called when the mouse is clicked inside a margin. +-- Called when clicking the mouse inside a margin. -- Arguments: -- --- * `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. --- * `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. +-- * _`margin`_: The margin number clicked. +-- * _`position`_: The position of the start of the line in the buffer whose +-- margin line was clicked. +-- * _`modifiers`_: A bit-mask of modifier keys held down. Modifiers are +-- `_SCINTILLA.constants.SCMOD_ALT`, `_SCINTILLA.constants.SCMOD_CTRL`, +-- `_SCINTILLA.constants.SCMOD_SHIFT`, and +-- `_SCINTILLA.constants.SCMOD_META`. -- Note: If you set `buffer.rectangular_selection_modifier` to -- `_SCINTILLA.constants.SCMOD_CTRL`, the "Control" modifier is reported as -- *both* "Control" and "Alt" due to a Scintilla limitation with GTK+. -- @field MENU_CLICKED (string) --- Called when a menu item is selected. +-- Called after selecting a menu item. -- Arguments: -- --- * `menu_id`: The numeric ID of the menu item set in [`gui.menu()`][]. +-- * _`menu_id`_: The numeric ID of the menu item set in [`gui.menu()`][]. -- @field QUIT (string) -- Called when quitting Textadept. -- When connecting to this event, connect with an index of 1 or the handler -- will be ignored. --- This is emitted by [`quit()`][]. +-- Emitted by [`quit()`][]. -- @field REPLACE (string) -- Called to replace selected (found) text. -- Arguments: -- --- * `text`: The text to replace selected text with. +-- * _`text`_: The text to replace the selected text with. -- @field REPLACE_ALL (string) --- Called to replace all occurances of found text. +-- Called to replace all occurrences of found text. -- Arguments: -- --- * `find_text`: The text to search for. --- * `repl_text`: The text to replace found text with. +-- * _`find_text`_: The text to search for. +-- * _`repl_text`_: The text to replace found text with. -- @field RESET_AFTER (string) -- Called after resetting the Lua state. --- This is emitted by [`reset()`][]. +-- Emitted by [`reset()`][]. -- @field RESET_BEFORE (string) -- Called before resetting the Lua state. --- This is emitted by [`reset()`][]. +-- Emitted by [`reset()`][]. -- @field SAVE_POINT_LEFT (string) --- Called when a save point is left. +-- Called after leaving a save point. -- @field SAVE_POINT_REACHED (string) --- Called when a save point is entered. +-- Called after reaching a save point. -- @field UPDATE_UI (string) --- Called when either the text or styling of the buffer has changed or the --- selection range has changed. +-- Called when the text, styling, or selection range in the buffer changes. -- @field URI_DROPPED (string) --- Called when the user has dragged a URI such as a file name onto the view. +-- Called after dragging and dropping a URI such as a file name onto the view. -- Arguments: -- --- * `text`: The URI text encoded in UTF-8. +-- * _`text`_: The UTF-8-encoded URI text. -- @field USER_LIST_SELECTION (string) --- Called when the user has selected an item in a user list. +-- Called after selecting an item in a user list. -- Arguments: -- --- * `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. +-- * _`list_type`_: The *list_type* from [`buffer:user_list_show()`][]. +-- * _`text`_: The text of the selection. +-- * _`position`_: The position in the buffer the list was displayed at. -- @field VIEW_NEW (string) --- Called when a new view is created. --- This is emitted on startup and by [`view:split()`][]. +-- Called after creating a new view. +-- Emitted on startup and by [`view:split()`][]. -- @field VIEW_BEFORE_SWITCH (string) --- Called right before another view is switched to. --- This is emitted by [`gui.goto_view()`][]. +-- Called right before switching to another view. +-- Emitted by [`gui.goto_view()`][]. -- @field VIEW_AFTER_SWITCH (string) --- Called right after another view is switched to. --- This is emitted by [`gui.goto_view()`][]. +-- Called right after switching to another view. +-- Emitted by [`gui.goto_view()`][]. -- -- [`buffer:auto_c_cancel()`]: buffer.html#auto_c_cancel -- [`view:goto_buffer()`]: view.html#goto_buffer -- [`new_buffer()`]: _G.html#new_buffer -- [`buffer:delete()`]: buffer.html#delete +-- [dwell period]: buffer.html#mouse_dwell_time -- [`gui.menu()`]: gui.html#menu -- [`quit()`]: _G.html#quit -- [`reset()`]: _G.html#reset @@ -271,18 +263,19 @@ local M = {} module('events')]] --- --- A table of event names and a table of functions connected to them. +-- Map of event names with tables of the functions connected to them. -- @class table -- @name handlers M.handlers = {} --- --- Adds a handler function to an event. --- @param event The string event name. It is arbitrary and does not need to be --- defined previously. +-- Adds function *f* to the set of event handlers for *event* at position +-- *index*, returning a handler ID for *f*. *event* is an arbitrary event name +-- that does not need to have been previously defined. +-- @param event The string event name. -- @param f The Lua function to add. -- @param index Optional index to insert the handler into. --- @return Index of handler. +-- @return handler ID. -- @usage events.connect('my_event', function(msg) gui.print(msg) end) -- @see disconnect -- @name connect @@ -295,25 +288,28 @@ function M.connect(event, f, index) end --- --- Disconnects a handler function from an event. +-- Removes handler ID *id*, returned by `events.connect()`, from the set of +-- event handlers for *event*. -- @param event The string event name. --- @param index Index of the handler returned by `events.connect()`. +-- @param id ID of the handler returned by `events.connect()`. -- @see connect -- @name disconnect -function M.disconnect(event, index) +function M.disconnect(event, id) if not M.handlers[event] then return end - table.remove(M.handlers[event], index) + table.remove(M.handlers[event], id) end local error_emitted = false --- --- Calls all handlers for the given event in sequence. --- If `true` or `false` is explicitly returned by any handler, the event is not --- propagated any further; iteration ceases. This is useful if you want to stop --- the propagation of an event like a keypress. --- @param event The string event name. It is arbitrary and does not need to be --- defined previously. +-- Sequentially calls all handler functions for *event* with the given +-- arguments. +-- *event* is an arbitrary event name that does not need to have been previously +-- defined. If any handler explicitly returns `true` or `false`, the event is +-- not propagated any further, iteration ceases, and `emit()` returns that +-- value. This is useful for stopping the propagation of an event like a +-- keypress after it has been handled. +-- @param event The string event name. -- @param ... Arguments passed to the handler. -- @return `true` or `false` if any handler explicitly returned such; `nil` -- otherwise. |