Module textadept.events
Textadept's core event structure and handlers.
Overview
Textadept is very event-driven. Most of its functionality comes through event handlers. Events occur when you create a new buffer, press a key, click on a menu, etc. You can even make an event occur with Lua code. Instead of having a single event handler however, each event can have a set of handlers. These handlers are simply Lua functions that are called in the order they were added to an event. This enables dynamically loaded modules to add their own handlers 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 occurs, either generated 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 a handler returns either true or false explicitly, all subsequent handlers are not called. This is useful if you want to stop the propagation of an event like a keypress.
Textadept Events
The following is a list of all Scintilla events generated by Textadept in
event_name(arguments)
format:
- char_added (ch)
Called when an ordinary text character is added to the buffer.- ch: the ASCII representation of the character.
- save_point_reached ()
Called when a save point is entered. - save_point_left ()
Called when a save point is left. - double_click (position, line)
Called when the mouse button is double-clicked.- position: the text position the click occured at.
- line: the line number the click occured at.
- update_ui ()
Called when the text or styling of the buffer has changed or the selection range has changed. - margin_click (margin, modifiers, position)
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
, andSCI_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 corresponds to the margin click.
- user_list_selection (wParam, text)
Called when the user has selected an item in a user list.- wParam: the list_type parameter from
buffer:user_list_show()
. - text: the text of the selection.
- wParam: the list_type parameter from
- uri_dropped (text)
Called when the user has dragged a URI such as a file name or web address into Textadept.- text: URI text.
- call_tip_click (position)
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 (lParam, text)
Called when the user has selected an item in an autocompletion list.- lParam: the start position of the word being completed.
- text: the text of the selection.
The following is a list of all Textadept events generated in
event_name(arguments)
format:
- buffer_new ()
Called when a new buffer is created. - buffer_deleted ()
Called when a buffer has been deleted. - buffer_before_switch ()
Called right before another buffer is switched to. - buffer_after_switch ()
Called right after a buffer was switched to. - 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 view was switched to. - reset_before()
Called before resetting the Lua state during a call totextadept.reset()
. - reset_after()
Called after resetting the Lua state during a call totextadept.reset()
. - quit ()
Called when quitting Textadept.
Note: Any quit handlers added must be inserted at index 1 because the default quit handler incore/events.lua
returnstrue
, which ignores all subsequent handlers. - keypress (code, shift, control, alt)
Called when a key is pressed.- code: the key code (according to
<gdk/gdkkeysyms.h>
). - shift: flag indicating whether or not the Shift key is pressed.
- control: flag indicating whether or not the Control key is pressed.
- alt: flag indicating whether or not the Alt/Apple key is pressed.
Note: The Alt-Option key in Mac OSX is not available.
- code: the key code (according to
- menu_clicked (menu_id)
Called when a menu item is selected.- menu_id: the numeric ID of the menu item set in
textadept.gtkmenu()
.
- menu_id: the numeric ID of the menu item set in
- pm_contents_request (full_path, expanding)
Called when the PM requests data to display.- full_path: a numerically indexed table of treeview item parents. The first index contains the text of the PM entry. Subsequent indices contain the ID's of parents of the child (if any).
- expanding: indicates if the contents of a parent are being requested.
- pm_item_selected (selected_item)
Called when an item in the PM is double-clicked or activated.- selected_item: identical to
full_path
in thepm_contents_request
event.
- selected_item: identical to
- pm_context_menu_request (selected_item, gdkevent)
Called when the context menu for an item in the PM is requested.- selected_item: identical to
full_path
in thepm_contents_request
event. - gdkevent: the GDK event associated with the request. It must be
passed to
textadept.pm.show_context_menu()
.
- selected_item: identical to
- pm_menu_clicked (menu_id, selected_item)
Called when a PM context menu item is selected.- menu_id: the numeric ID of the context menu item set in
textadept.gtkmenu()
. - selected_item: identical to
full_path
in thepm_contents_request
event.
- menu_id: the numeric ID of the context menu item set in
- pm_view_filled ()
Called when the PM view is filled with data. - find (text, next)
Called when attempting to finding text via the Find dialog box.- text: the text to search for.
- next: flat indicating whether or not the search direction is forward.
- replace (text)
Called when the found text is selected and asked to be replaced.- text: the text to replace the selected text with.
- replace_all (find_text, repl_text)
Called when all occurances of found text are to be replaced.- find_text: the text to search for.
- repl_text: the text to replace found text with.
- command_entry_keypress (code)
Called when a key is pressed in the Command Entry.- code: the key code (according to
<gdk/gdkkeysyms.h>
).
- code: the key code (according to
Example
The following Lua code generates and handles a custom my_event
event:
function my_event_handler(message)
textadept.print(message)
end
textadept.events.add_handler('my_event', my_event_handler)
textadept.events.handle('my_event', 'my message')
Overview
Textadept is very event-driven. Most of its functionality comes through event handlers. Events occur when you create a new buffer, press a key, click on a menu, etc. You can even make an event occur with Lua code. Instead of having a single event handler however, each event can have a set of handlers. These handlers are simply Lua functions that are called in the order they were added to an event. This enables dynamically loaded modules to add their own handlers 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 occurs, either generated 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 a handler returns either true or false explicitly, all subsequent handlers are not called. This is useful if you want to stop the propagation of an event like a keypress.
Textadept Events
The following is a list of all Scintilla events generated by Textadept in
event_name(arguments)
format:
- char_added (ch)
Called when an ordinary text character is added to the buffer.- ch: the ASCII representation of the character.
- save_point_reached ()
Called when a save point is entered. - save_point_left ()
Called when a save point is left. - double_click (position, line)
Called when the mouse button is double-clicked.- position: the text position the click occured at.
- line: the line number the click occured at.
- update_ui ()
Called when the text or styling of the buffer has changed or the selection range has changed. - margin_click (margin, modifiers, position)
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
, andSCI_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 corresponds to the margin click.
- user_list_selection (wParam, text)
Called when the user has selected an item in a user list.- wParam: the list_type parameter from
buffer:user_list_show()
. - text: the text of the selection.
- wParam: the list_type parameter from
- uri_dropped (text)
Called when the user has dragged a URI such as a file name or web address into Textadept.- text: URI text.
- call_tip_click (position)
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 (lParam, text)
Called when the user has selected an item in an autocompletion list.- lParam: the start position of the word being completed.
- text: the text of the selection.
The following is a list of all Textadept events generated in
event_name(arguments)
format:
- buffer_new ()
Called when a new buffer is created. - buffer_deleted ()
Called when a buffer has been deleted. - buffer_before_switch ()
Called right before another buffer is switched to. - buffer_after_switch ()
Called right after a buffer was switched to. - 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 view was switched to. - reset_before()
Called before resetting the Lua state during a call totextadept.reset()
. - reset_after()
Called after resetting the Lua state during a call totextadept.reset()
. - quit ()
Called when quitting Textadept.
Note: Any quit handlers added must be inserted at index 1 because the default quit handler incore/events.lua
returnstrue
, which ignores all subsequent handlers. - keypress (code, shift, control, alt)
Called when a key is pressed.- code: the key code (according to
<gdk/gdkkeysyms.h>
). - shift: flag indicating whether or not the Shift key is pressed.
- control: flag indicating whether or not the Control key is pressed.
- alt: flag indicating whether or not the Alt/Apple key is pressed.
Note: The Alt-Option key in Mac OSX is not available.
- code: the key code (according to
- menu_clicked (menu_id)
Called when a menu item is selected.- menu_id: the numeric ID of the menu item set in
textadept.gtkmenu()
.
- menu_id: the numeric ID of the menu item set in
- pm_contents_request (full_path, expanding)
Called when the PM requests data to display.- full_path: a numerically indexed table of treeview item parents. The first index contains the text of the PM entry. Subsequent indices contain the ID's of parents of the child (if any).
- expanding: indicates if the contents of a parent are being requested.
- pm_item_selected (selected_item)
Called when an item in the PM is double-clicked or activated.- selected_item: identical to
full_path
in thepm_contents_request
event.
- selected_item: identical to
- pm_context_menu_request (selected_item, gdkevent)
Called when the context menu for an item in the PM is requested.- selected_item: identical to
full_path
in thepm_contents_request
event. - gdkevent: the GDK event associated with the request. It must be
passed to
textadept.pm.show_context_menu()
.
- selected_item: identical to
- pm_menu_clicked (menu_id, selected_item)
Called when a PM context menu item is selected.- menu_id: the numeric ID of the context menu item set in
textadept.gtkmenu()
. - selected_item: identical to
full_path
in thepm_contents_request
event.
- menu_id: the numeric ID of the context menu item set in
- pm_view_filled ()
Called when the PM view is filled with data. - find (text, next)
Called when attempting to finding text via the Find dialog box.- text: the text to search for.
- next: flat indicating whether or not the search direction is forward.
- replace (text)
Called when the found text is selected and asked to be replaced.- text: the text to replace the selected text with.
- replace_all (find_text, repl_text)
Called when all occurances of found text are to be replaced.- find_text: the text to search for.
- repl_text: the text to replace found text with.
- command_entry_keypress (code)
Called when a key is pressed in the Command Entry.- code: the key code (according to
<gdk/gdkkeysyms.h>
).
- code: the key code (according to
Example
The following Lua code generates and handles a custom my_event
event:
function my_event_handler(message)
textadept.print(message)
end
textadept.events.add_handler('my_event', my_event_handler)
textadept.events.handle('my_event', 'my message')
Overview
Textadept is very event-driven. Most of its functionality comes through event handlers. Events occur when you create a new buffer, press a key, click on a menu, etc. You can even make an event occur with Lua code. Instead of having a single event handler however, each event can have a set of handlers. These handlers are simply Lua functions that are called in the order they were added to an event. This enables dynamically loaded modules to add their own handlers 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 occurs, either generated 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 a handler returns either true or false explicitly, all subsequent handlers are not called. This is useful if you want to stop the propagation of an event like a keypress.
Textadept Events
The following is a list of all Scintilla events generated by Textadept in
event_name(arguments)
format:
- char_added (ch)
Called when an ordinary text character is added to the buffer.- ch: the ASCII representation of the character.
- save_point_reached ()
Called when a save point is entered. - save_point_left ()
Called when a save point is left. - double_click (position, line)
Called when the mouse button is double-clicked.- position: the text position the click occured at.
- line: the line number the click occured at.
- update_ui ()
Called when the text or styling of the buffer has changed or the selection range has changed. - margin_click (margin, modifiers, position)
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
, andSCI_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 corresponds to the margin click.
- user_list_selection (wParam, text)
Called when the user has selected an item in a user list.- wParam: the list_type parameter from
buffer:user_list_show()
. - text: the text of the selection.
- wParam: the list_type parameter from
- uri_dropped (text)
Called when the user has dragged a URI such as a file name or web address into Textadept.- text: URI text.
- call_tip_click (position)
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 (lParam, text)
Called when the user has selected an item in an autocompletion list.- lParam: the start position of the word being completed.
- text: the text of the selection.
The following is a list of all Textadept events generated in
event_name(arguments)
format:
- buffer_new ()
Called when a new buffer is created. - buffer_deleted ()
Called when a buffer has been deleted. - buffer_before_switch ()
Called right before another buffer is switched to. - buffer_after_switch ()
Called right after a buffer was switched to. - 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 view was switched to. - reset_before()
Called before resetting the Lua state during a call totextadept.reset()
. - reset_after()
Called after resetting the Lua state during a call totextadept.reset()
. - quit ()
Called when quitting Textadept.
Note: Any quit handlers added must be inserted at index 1 because the default quit handler incore/events.lua
returnstrue
, which ignores all subsequent handlers. - keypress (code, shift, control, alt)
Called when a key is pressed.- code: the key code (according to
<gdk/gdkkeysyms.h>
). - shift: flag indicating whether or not the Shift key is pressed.
- control: flag indicating whether or not the Control key is pressed.
- alt: flag indicating whether or not the Alt/Apple key is pressed.
Note: The Alt-Option key in Mac OSX is not available.
- code: the key code (according to
- menu_clicked (menu_id)
Called when a menu item is selected.- menu_id: the numeric ID of the menu item set in
textadept.gtkmenu()
.
- menu_id: the numeric ID of the menu item set in
- pm_contents_request (full_path, expanding)
Called when the PM requests data to display.- full_path: a numerically indexed table of treeview item parents. The first index contains the text of the PM entry. Subsequent indices contain the ID's of parents of the child (if any).
- expanding: indicates if the contents of a parent are being requested.
- pm_item_selected (selected_item)
Called when an item in the PM is double-clicked or activated.- selected_item: identical to
full_path
in thepm_contents_request
event.
- selected_item: identical to
- pm_context_menu_request (selected_item, gdkevent)
Called when the context menu for an item in the PM is requested.- selected_item: identical to
full_path
in thepm_contents_request
event. - gdkevent: the GDK event associated with the request. It must be
passed to
textadept.pm.show_context_menu()
.
- selected_item: identical to
- pm_menu_clicked (menu_id, selected_item)
Called when a PM context menu item is selected.- menu_id: the numeric ID of the context menu item set in
textadept.gtkmenu()
. - selected_item: identical to
full_path
in thepm_contents_request
event.
- menu_id: the numeric ID of the context menu item set in
- pm_view_filled ()
Called when the PM view is filled with data. - find (text, next)
Called when attempting to finding text via the Find dialog box.- text: the text to search for.
- next: flat indicating whether or not the search direction is forward.
- replace (text)
Called when the found text is selected and asked to be replaced.- text: the text to replace the selected text with.
- replace_all (find_text, repl_text)
Called when all occurances of found text are to be replaced.- find_text: the text to search for.
- repl_text: the text to replace found text with.
- command_entry_keypress (code)
Called when a key is pressed in the Command Entry.- code: the key code (according to
<gdk/gdkkeysyms.h>
).
- code: the key code (according to
Example
The following Lua code generates and handles a custom my_event
event:
function my_event_handler(message)
textadept.print(message)
end
textadept.events.add_handler('my_event', my_event_handler)
textadept.events.handle('my_event', 'my message')
Functions
add_handler (event, f, index) | Adds a handler function to an event. |
handle (event, ...) | Calls all handlers for the given event in sequence (effectively "generating" the event). |
notification (n) | Handles Scintilla notifications. |
Functions
- add_handler (event, f, index)
-
Adds a handler function to an event.
Parameters
- event: The string event name. It is arbitrary and need not be defined anywhere.
- f: The Lua function to add.
- index: Optional index to insert the handler into.
- handle (event, ...)
-
Calls all handlers for the given event in sequence (effectively "generating" the event). If true or false is explicitly returned by any handler, the event is not propagated any further; iteration ceases.
Parameters
- event: The string event name.
- ...: Arguments passed to the handler.
Return value:
true or false if any handler explicitly returned such; nil otherwise. - notification (n)
-
Handles Scintilla notifications.
Parameters
- n: The Scintilla notification structure as a Lua table.
Return value:
true or false if any handler explicitly returned such; nil otherwise.