# 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

- - -

<a id="APPLEEVENT_ODOC"></a>
### `APPLEEVENT_ODOC` (string)

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

  * _`uri`_: The UTF-8-encoded URI to open.

- - -

<a id="AUTO_C_CHAR_DELETED"></a>
### `AUTO_C_CHAR_DELETED` (string)

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

- - -

<a id="AUTO_C_RELEASE"></a>
### `AUTO_C_RELEASE` (string)

Emitted when canceling the autocompletion list.

- - -

<a id="AUTO_C_SELECTION"></a>
### `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.

- - -

<a id="BUFFER_AFTER_SWITCH"></a>
### `BUFFER_AFTER_SWITCH` (string)

Emitted right after switching to another buffer.
  Emitted by [`view:goto_buffer()`][].

- - -

<a id="BUFFER_BEFORE_SWITCH"></a>
### `BUFFER_BEFORE_SWITCH` (string)

Emitted right before switching to another buffer.
  Emitted by [`view:goto_buffer()`][].

- - -

<a id="BUFFER_DELETED"></a>
### `BUFFER_DELETED` (string)

Emitted after deleting a buffer.
  Emitted by [`buffer:delete()`][].

- - -

<a id="BUFFER_NEW"></a>
### `BUFFER_NEW` (string)

Emitted after creating a new buffer.
  Emitted on startup and by [`buffer.new()`][].

- - -

<a id="CALL_TIP_CLICK"></a>
### `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.

- - -

<a id="CHAR_ADDED"></a>
### `CHAR_ADDED` (string)

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

  * _`ch`_: The text character byte.

- - -

<a id="COMMAND_ENTRY_KEYPRESS"></a>
### `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.

- - -

<a id="DOUBLE_CLICK"></a>
### `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 set `buffer.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+.

- - -

<a id="DWELL_END"></a>
### `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.

- - -

<a id="DWELL_START"></a>
### `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.

- - -

<a id="ERROR"></a>
### `ERROR` (string)

Emitted when an error occurs.
  Arguments:

  * _`text`_: The error text.

- - -

<a id="FIND"></a>
### `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.

- - -

<a id="HOTSPOT_CLICK"></a>
### `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 set `buffer.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+.

- - -

<a id="HOTSPOT_DOUBLE_CLICK"></a>
### `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 set `buffer.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+.

- - -

<a id="HOTSPOT_RELEASE_CLICK"></a>
### `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.

- - -

<a id="INDICATOR_CLICK"></a>
### `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 set `buffer.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+.

- - -

<a id="INDICATOR_RELEASE"></a>
### `INDICATOR_RELEASE` (string)

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

  * _`position`_: The position in the buffer unclicked.

- - -

<a id="KEYPRESS"></a>
### `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.

- - -

<a id="MARGIN_CLICK"></a>
### `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 set `buffer.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+.

- - -

<a id="MENU_CLICKED"></a>
### `MENU_CLICKED` (string)

Emitted after selecting a menu item.
  Arguments:

  * _`menu_id`_: The numeric ID of the menu item set in [`gui.menu()`][].

- - -

<a id="QUIT"></a>
### `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()`][].

- - -

<a id="REPLACE"></a>
### `REPLACE` (string)

Emitted to replace selected (found) text.
  Arguments:

  * _`text`_: The text to replace the selected text with.

- - -

<a id="REPLACE_ALL"></a>
### `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.

- - -

<a id="RESET_AFTER"></a>
### `RESET_AFTER` (string)

Emitted after resetting the Lua state.
  Emitted by [`reset()`][].

- - -

<a id="RESET_BEFORE"></a>
### `RESET_BEFORE` (string)

Emitted before resetting the Lua state.
  Emitted by [`reset()`][].

- - -

<a id="SAVE_POINT_LEFT"></a>
### `SAVE_POINT_LEFT` (string)

Emitted after leaving a save point.

- - -

<a id="SAVE_POINT_REACHED"></a>
### `SAVE_POINT_REACHED` (string)

Emitted after reaching a save point.

- - -

<a id="UPDATE_UI"></a>
### `UPDATE_UI` (string)

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

- - -

<a id="URI_DROPPED"></a>
### `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.

- - -

<a id="USER_LIST_SELECTION"></a>
### `USER_LIST_SELECTION` (string)

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

  * _`list_type`_: The *list_type* from [`buffer:user_list_show()`][].
  * _`text`_: The text of the selection.
  * _`position`_: The position in the buffer the list was displayed at.

- - -

<a id="VIEW_AFTER_SWITCH"></a>
### `VIEW_AFTER_SWITCH` (string)

Emitted right after switching to another view.
  Emitted by [`gui.goto_view()`][].

[`buffer:auto_c_cancel()`]: buffer.html#auto_c_cancel
[`view:goto_buffer()`]: view.html#goto_buffer
[`buffer.new()`]: buffer.html#new
[`buffer:delete()`]: buffer.html#delete
[dwell period]: buffer.html#mouse_dwell_time
[`gui.menu()`]: gui.html#menu
[`quit()`]: _G.html#quit
[`reset()`]: _G.html#reset
[`buffer:user_list_show()`]: buffer.html#user_list_show
[`view:split()`]: view.html#split
[`gui.goto_view()`]: gui.html#goto_view

- - -

<a id="VIEW_BEFORE_SWITCH"></a>
### `VIEW_BEFORE_SWITCH` (string)

Emitted right before switching to another view.
  Emitted by [`gui.goto_view()`][].

- - -

<a id="VIEW_NEW"></a>
### `VIEW_NEW` (string)

Emitted after creating a new view.
  Emitted on startup and by [`view:split()`][].

- - -


## Functions

- - -

<a id="connect"></a>
### `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`](#disconnect)

- - -

<a id="disconnect"></a>
### `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 by `events.connect()`.

See also:

* [`connect`](#connect)

- - -

<a id="emit"></a>
### `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` or `false` if any handler explicitly returned such; `nil`
  otherwise.

- - -


