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_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
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)
Emitted when Mac OSX tells Textadept to open a document. Arguments:
uri
: The UTF-8-encoded URI to open.
AUTO_C_CHAR_DELETED
(string)
Emitted when deleting a character while the autocompletion list is active.
AUTO_C_RELEASE
(string)
Emitted when canceling the autocompletion list.
AUTO_C_SELECTION
(string)
Emitted 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)
Emitted right after switching to another buffer.
Emitted by view:goto_buffer()
.
BUFFER_BEFORE_SWITCH
(string)
Emitted right before switching to another buffer.
Emitted by view:goto_buffer()
.
BUFFER_DELETED
(string)
Emitted after deleting a buffer.
Emitted by buffer:delete()
.
BUFFER_NEW
(string)
Emitted after creating a new buffer.
Emitted on startup and by buffer.new()
.
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.
CHAR_ADDED
(string)
Emitted after adding an ordinary text character to the buffer. Arguments:
ch
: The text character byte.
COMMAND_ENTRY_KEYPRESS
(string)
Emitted 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)
Emitted 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)
Emitted 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)
Emitted 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)
Emitted when an error occurs. Arguments:
text
: The error text.
FIND
(string)
Emitted 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)
Emitted 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)
Emitted 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)
Emitted 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)
Emitted 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)
Emitted after releasing the mouse after clicking on text that had an indicator. Arguments:
position
: The position in the buffer unclicked.
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”/“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)
Emitted 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)
Emitted after selecting a menu item. Arguments:
menu_id
: The numeric ID of the menu item set ingui.menu()
.
QUIT
(string)
Emitted 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)
Emitted to replace selected (found) text. Arguments:
text
: The text to replace the selected text with.
REPLACE_ALL
(string)
Emitted 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)
Emitted after resetting the Lua state.
Emitted by reset()
.
RESET_BEFORE
(string)
Emitted before resetting the Lua state.
Emitted by reset()
.
SAVE_POINT_LEFT
(string)
Emitted after leaving a save point.
SAVE_POINT_REACHED
(string)
Emitted after reaching a save point.
UPDATE_UI
(string)
Emitted when the text, styling, or selection range in the buffer changes.
URI_DROPPED
(string)
Emitted 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)
Emitted 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)
Emitted right after switching to another view.
Emitted by gui.goto_view()
.
VIEW_BEFORE_SWITCH
(string)
Emitted right before switching to another view.
Emitted by gui.goto_view()
.
VIEW_NEW
(string)
Emitted 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.