Contents

events

Textadept’s core event structure and handlers.

Overview

Events occur 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. This enables dynamically loaded modules to connect to events.

Events themselves are nothing special. They do not have to be declared in order to be used. They are simply strings containing an arbitrary event name. When an event of this name is emitted, either by Textadept or you, all event handlers assigned to it are run. Events can be given any number of arguments. These arguments will be passed to the event’s handler functions. If an event handler returns a true or false boolean value explicitly, no subsequent handlers are called. This is useful if you want to stop the propagation of an event like a keypress if it has already been handled.


Fields


APPLEEVENT_ODOC (string)

Called when Mac OSX tells Textadept to open a document. Arguments:


AUTO_C_CHAR_DELETED (string)

Called when deleting a character while the autocompletion list is active.


AUTO_C_RELEASE (string)

Called when canceling the autocompletion list.


AUTO_C_SELECTION (string)

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:


BUFFER_AFTER_SWITCH (string)

Called right after switching to another buffer. Emitted by view:goto_buffer().


BUFFER_BEFORE_SWITCH (string)

Called right before switching to another buffer. Emitted by view:goto_buffer().


BUFFER_DELETED (string)

Called after deleting a buffer. Emitted by buffer:delete().


BUFFER_NEW (string)

Called after creating a new buffer. Emitted on startup and by new_buffer().


CALL_TIP_CLICK (string)

Called when clicking on a calltip. Arguments:


CHAR_ADDED (string)

Called after adding an ordinary text character to the buffer. Arguments:


COMMAND_ENTRY_COMMAND (string)

Called to run the command entered into the Command Entry. If any handler returns true, the Command Entry does not hide automatically. Arguments:


COMMAND_ENTRY_KEYPRESS (string)

Called when pressing a key in the Command Entry. If any handler returns true, the key is not inserted into the entry. Arguments:


DOUBLE_CLICK (string)

Called after double-clicking the mouse button. Arguments:


DWELL_END (string)

Called after a DWELL_START when the mouse moves, a key is pressed, etc. Arguments:


DWELL_START (string)

Called after keeping the mouse stationary for the dwell period Arguments:


ERROR (string)

Called when an error occurs. Arguments:


FIND (string)

Called to find text via the Find dialog box. Arguments:


HOTSPOT_CLICK (string)

Called when clicking on text that is in a style with the hotspot attribute set. Arguments:


HOTSPOT_DOUBLE_CLICK (string)

Called when double-clicking on text that is in a style with the hotspot attribute set. Arguments:


HOTSPOT_RELEASE_CLICK (string)

Called after releasing the mouse after clicking on text that was in a style with the hotspot attribute set. Arguments:


INDICATOR_CLICK (string)

Called when clicking the mouse on text that has an indicator. Arguments:


INDICATOR_RELEASE (string)

Called after releasing the mouse after clicking on text that had an indicator. Arguments:


KEYPRESS (string)

Called when pressing a key. If any handler returns true, the key is not inserted into the buffer. Arguments:


MARGIN_CLICK (string)

Called when clicking the mouse inside a margin. Arguments:


MENU_CLICKED (string)

Called after selecting a menu item. Arguments:


QUIT (string)

Called when quitting Textadept. When connecting to this event, connect with an index of 1 or the handler will be ignored. Emitted by quit().


REPLACE (string)

Called to replace selected (found) text. Arguments:


REPLACE_ALL (string)

Called to replace all occurrences of found text. Arguments:


RESET_AFTER (string)

Called after resetting the Lua state. Emitted by reset().


RESET_BEFORE (string)

Called before resetting the Lua state. Emitted by reset().


SAVE_POINT_LEFT (string)

Called after leaving a save point.


SAVE_POINT_REACHED (string)

Called after reaching a save point.


UPDATE_UI (string)

Called when the text, styling, or selection range in the buffer changes.


URI_DROPPED (string)

Called after dragging and dropping a URI such as a file name onto the view. Arguments:


USER_LIST_SELECTION (string)

Called after selecting an item in a user list. Arguments:


VIEW_AFTER_SWITCH (string)

Called right after switching to another view. Emitted by gui.goto_view().


VIEW_BEFORE_SWITCH (string)

Called right before switching to another view. Emitted by gui.goto_view().


VIEW_NEW (string)

Called after creating a new view. Emitted on startup and by view:split().


Functions


connect(event, f, index)

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.

Parameters:

Usage:

Return:

See also:


disconnect(event, id)

Removes handler ID id, returned by events.connect(), from the set of event handlers for event.

Parameters:

See also:


emit(event, …)

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.

Parameters:

Usage:

Return:


Tables


handlers

Map of event names with tables of the functions connected to them.