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, and SCI_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.
  • 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 to textadept.reset().
  • reset_after()
    Called after resetting the Lua state during a call to textadept.reset().
  • quit ()
    Called when quitting Textadept.
    Note: Any quit handlers added must be inserted at index 1 because the default quit handler in core/events.lua returns true, 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.
  • menu_clicked (menu_id)
    Called when a menu item is selected.
  • 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 the pm_contents_request event.
  • 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 the pm_contents_request event.
    • gdkevent: the GDK event associated with the request. It must be passed to textadept.pm.show_context_menu().
  • 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 the pm_contents_request event.
  • 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>).

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, and SCI_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.
  • 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 to textadept.reset().
  • reset_after()
    Called after resetting the Lua state during a call to textadept.reset().
  • quit ()
    Called when quitting Textadept.
    Note: Any quit handlers added must be inserted at index 1 because the default quit handler in core/events.lua returns true, 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.
  • menu_clicked (menu_id)
    Called when a menu item is selected.
  • 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 the pm_contents_request event.
  • 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 the pm_contents_request event.
    • gdkevent: the GDK event associated with the request. It must be passed to textadept.pm.show_context_menu().
  • 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 the pm_contents_request event.
  • 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>).

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, and SCI_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.
  • 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 to textadept.reset().
  • reset_after()
    Called after resetting the Lua state during a call to textadept.reset().
  • quit ()
    Called when quitting Textadept.
    Note: Any quit handlers added must be inserted at index 1 because the default quit handler in core/events.lua returns true, 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.
  • menu_clicked (menu_id)
    Called when a menu item is selected.
  • 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 the pm_contents_request event.
  • 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 the pm_contents_request event.
    • gdkevent: the GDK event associated with the request. It must be passed to textadept.pm.show_context_menu().
  • 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 the pm_contents_request event.
  • 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>).

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.

Valid XHTML 1.0!