Textadept
- Home |
- Download |
- Lua API |
- Source |
- Language Modules |
- Stats |
- Wiki |
- Mailing List
Contents
- events
- Overview
- Fields
- APPLEEVENT_ODOC
- AUTO_C_CHAR_DELETED
- AUTO_C_RELEASE
- AUTO_C_SELECTION
- BUFFER_AFTER_SWITCH
- BUFFER_BEFORE_SWITCH
- BUFFER_DELETED
- BUFFER_NEW
- CALL_TIP_CLICK
- CHAR_ADDED
- COMMAND_ENTRY_COMMAND
- COMMAND_ENTRY_KEYPRESS
- DOUBLE_CLICK
- DWELL_END
- DWELL_START
- ERROR
- FIND
- HOTSPOT_CLICK
- HOTSPOT_DOUBLE_CLICK
- HOTSPOT_RELEASE_CLICK
- INDICATOR_CLICK
- INDICATOR_RELEASE
- KEYPRESS
- MARGIN_CLICK
- MENU_CLICKED
- QUIT
- REPLACE
- REPLACE_ALL
- RESET_AFTER
- RESET_BEFORE
- SAVE_POINT_LEFT
- SAVE_POINT_REACHED
- UPDATE_UI
- URI_DROPPED
- USER_LIST_SELECTION
- VIEW_AFTER_SWITCH
- VIEW_BEFORE_SWITCH
- VIEW_NEW
- Functions
- Tables
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:
uri
: The UTF-8-encoded URI to open.
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:
text
: The text of the selection.position
: The position in the buffer of the beginning of the autocompleted word.
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:
position
:1
if the up arrow was clicked, 2 if the down arrow was clicked, and 0 otherwise.
CHAR_ADDED
(string)
Called after adding an ordinary text character to the buffer. Arguments:
ch
: The text character byte.
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
: The command text.
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:
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.
DOUBLE_CLICK
(string)
Called after double-clicking the mouse button. Arguments:
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 setbuffer.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+.
DWELL_END
(string)
Called after a DWELL_START
when the mouse moves, a key is pressed, etc.
Arguments:
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.
DWELL_START
(string)
Called after keeping the mouse stationary for the dwell period Arguments:
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.
ERROR
(string)
Called when an error occurs. Arguments:
text
: The error text.
FIND
(string)
Called to find text via the Find dialog box. Arguments:
text
: The text to search for.next
: Whether or not to search forward.
HOTSPOT_CLICK
(string)
Called when clicking on text that is in a style with the hotspot attribute set. Arguments:
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 setbuffer.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+.
HOTSPOT_DOUBLE_CLICK
(string)
Called when double-clicking on text that is in a style with the hotspot attribute set. Arguments:
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 setbuffer.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+.
HOTSPOT_RELEASE_CLICK
(string)
Called after releasing the mouse after clicking on text that was in a style with the hotspot attribute set. Arguments:
position
: The position in the buffer unclicked.
INDICATOR_CLICK
(string)
Called when clicking the mouse on text that has an indicator. Arguments:
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 setbuffer.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+.
INDICATOR_RELEASE
(string)
Called after releasing the mouse after clicking on text that had an indicator. Arguments:
position
: The position in the buffer unclicked.
KEYPRESS
(string)
Called 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”/“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.
MARGIN_CLICK
(string)
Called when clicking the mouse inside a margin. Arguments:
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 setbuffer.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+.
MENU_CLICKED
(string)
Called after selecting a menu item. Arguments:
menu_id
: The numeric ID of the menu item set ingui.menu()
.
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:
text
: The text to replace the selected text with.
REPLACE_ALL
(string)
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.
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:
text
: The UTF-8-encoded URI text.
USER_LIST_SELECTION
(string)
Called after selecting an item in a user list. Arguments:
list_type
: The list_type frombuffer:user_list_show()
.text
: The text of the selection.position
: The position in the buffer the list was displayed at.
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:
event
: The string event name.f
: The Lua function to connect to event.index
: Optional index to insert the handler into.
Usage:
events.connect('my_event', function(msg) gui.print(msg) end)
Return:
- handler ID.
See also:
disconnect
(event, id)
Removes handler ID id, returned by events.connect()
, from the set of
event handlers for event.
Parameters:
event
: The string event name.id
: ID of the handler returned byevents.connect()
.
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:
event
: The string event name....
: Arguments passed to the handler.
Usage:
events.emit('my_event', 'my message')
Return:
true
orfalse
if any handler explicitly returned such;nil
otherwise.
Tables
handlers
Map of event names with tables of the functions connected to them.