18. Event list

As Sublime Text is continually being updated, it is noted that this list is current as of build 4200.

18.1. EventListener

EventListener objects are instantiated exactly once, and so any state saved within EventListener sub-classes you create will be for the whole application, all Windows, and all Views within those Windows.

When events have something to do with a particular View, they will receive a view argument.

EventListener.on_init(views: List[View])

Called once with a list of views that were loaded before the EventListener was instantiated

Since build 4050

EventListener.on_exit()

Called once after the API has shut down, immediately before the plugin_host process exits

Since build 4050

EventListener.on_new(view: View)

Called when a new file is created.

EventListener.on_new_async(view: View)

Called when a new buffer is created. Runs in a separate thread, and does not block the application.

EventListener.on_associate_buffer(buffer: View)

Called when a buffer is associated with a file. buffer will be a Buffer object.

Since build 4084

EventListener.on_associate_buffer_async(buffer: View)

Called when a buffer is associated with file. Runs in a separate thread, and does not block the application. buffer will be a Buffer object.

Since build 4084

EventListener.on_clone(view: View)

Called when a view is cloned from an existing one.

EventListener.on_clone_async(view: View)

Called when a view is cloned from an existing one. Runs in a separate thread, and does not block the application.

EventListener.on_load(view: View)

Called when the file is finished loading.

EventListener.on_load_async(view: View)

Called when the file is finished loading. Runs in a separate thread, and does not block the application.

EventListener.on_reload(view: View)

Called when the View is reloaded.

Since build 4050

EventListener.on_reload_async(view: View)

Called when the View is reloaded. Runs in a separate thread, and does not block the application.

Since build 4050

EventListener.on_revert(view: View)

Called when the View is reverted.

Since build 4050

EventListener.on_revert_async(view: View)

Called when the View is reverted. Runs in a separate thread, and does not block the application.

Since build 4050

EventListener.on_pre_move(view: View)

Called right before a view is moved between two windows or within a window. Passed the View object.

Since build 4050

EventListener.on_post_move(view: View)

Called right after a view is moved between two windows or within a window. Passed the View object.

Since build 4050

EventListener.on_post_move_async(view: View)

Called right after a view is moved between two windows or within a window. Passed the View object. Runs in a separate thread, and does not block the application.

Since build 4050

EventListener.on_pre_close(view: View)

Called when a view is about to be closed. The view will still be in the window at this point.

EventListener.on_close(view: View)

Called when a view is closed (note, there may still be other views into the same buffer).

EventListener.on_pre_save(view: View)

Called just before a view is saved.

EventListener.on_pre_save_async(view: View)

Called just before a view is saved. Runs in a separate thread, and does not block the application.

EventListener.on_post_save(view: View)

Called after a view has been saved.

EventListener.on_post_save_async(view: View)

Called after a view has been saved. Runs in a separate thread, and does not block the application.

EventListener.on_modified(view: View)

Called after changes have been made to a view.

EventListener.on_modified_async(view: View)

Called after changes have been made to a view. Runs in a separate thread, and does not block the application.

EventListener.on_selection_modified(view: View)

Called after the selection has been modified in a view.

EventListener.on_selection_modified_async(view: View)

Called after the selection has been modified in a view. Runs in a separate thread, and does not block the application.

EventListener.on_activated(view: View)

Called when a view gains input focus.

EventListener.on_activated_async(view: View)

Called when a view gains input focus. Runs in a separate thread, and does not block the application.

EventListener.on_deactivated(view: View)

Called when a view loses input focus.

EventListener.on_deactivated_async(view: View)

Called when a view loses input focus. Runs in a separate thread, and does not block the application.

EventListener.on_hover(view: View, point: Point, hover_zone: HoverZone)

Called when the user’s mouse hovers over the view for a short period.

Parameters:

view – The view

point – The closest point in the view to the mouse location. The mouse may not actually be located adjacent based on the value of hover_zone.

hover_zone – Which element in Sublime Text the mouse has hovered over.

EventListener.on_query_context(view: View, key: str, operator: QueryOperator, operand: str, match_all: bool) → bool | None

Called when determining to trigger a key binding with the given context key. If the plugin knows how to respond to the context, it should return either True of False. If the context is unknown, it should return None.

Parameters:

key – The context key to query. This generally refers to specific state held by a plugin.

operator – The operator to check against the operand; whether to check equality, inequality, etc.

operand – The value against which to check using the operator.

match_all – This should be used if the context relates to the selections: does every selection have to match(match_all == True), or is at least one matching enough (match_all == False)?

Returns:

True or False if the plugin handles this context key and it either does or doesn’t match. If the context is unknown return None.

EventListener.on_query_completions(view: View, prefix: str, locations: List[Point]) → None | List[CompletionValue] | Tuple[List[CompletionValue], AutoCompleteFlags] | CompletionList

Called whenever completions are to be presented to the user.

Parameters:

prefix – The text already typed by the user.

locations – The list of points being completed. Since this method is called for all completions no matter the syntax, self.view.match_selector(point, relevant_scope) should be called to determine if the point is relevant.

Returns:

A list of completions in one of the valid formats or None if no completions are provided.

EventListener.on_text_command(view: View, command_name: str, args: CommandArgs)

Called when a text command is issued. The listener may return a (command, arguments) tuple to rewrite the command, or None to run the command unmodified.

EventListener.on_window_command(window: Window, command_name: str, args: CommandArgs)

Called when a window command is issued. The listener may return a (command, arguments) tuple to rewrite the command, or None to run the command unmodified.

EventListener.on_post_text_command(view: View, command_name: str, args: CommandArgs)

Called after a text command has been executed.

EventListener.on_post_window_command(window: Window, command_name: str, args: CommandArgs)

Called after a window command has been executed.

EventListener.on_new_window(window: Window)

Called when a window is created, passed the Window object.

Since build 4050

EventListener.on_new_window_async(window: Window)

Called when a window is created, passed the Window object. Runs in a separate thread, and does not block the application.

Since build 4050

EventListener.on_pre_close_window(window: Window)

Called right before a window is closed, passed the Window object.

Since build 4050

EventListener.on_new_project(window: Window)

Called right after a new project is created, passed the Window object.

Since build 4050

EventListener.on_new_project_async(window: Window)

Called right after a new project is created, passed the Window object. Runs in a separate thread, and does not block the application.

Since build 4050

EventListener.on_load_project(window: Window)

Called right after a project is loaded, passed the Window object.

Since build 4050

EventListener.on_load_project_async(window: Window)

Called right after a project is loaded, passed the Window object. Runs in a separate thread, and does not block the application.

Since build 4050

EventListener.on_pre_save_project(window: Window)

Called right before a project is saved, passed the Window object.

Since build 4050

EventListener.on_post_save_project(window: Window)

Called right after a project is saved, passed the Window object.

Since build 4050

EventListener.on_post_save_project_async(window: Window)

Called right after a project is saved, passed the Window object. Runs in a separate thread, and does not block the application.

Since build 4050

EventListener.on_pre_close_project(window: Window)

Called right before a project is closed, passed the Window object.

18.2. ViewEventListener

ViewEventListener objects are instantiated once per View in such a way that the object knows what View it is attached to because it the self argument each event gets has a self.view property, much like sTextCommands. So any state saved within ViewEventListener sub-classes you create will be for just the one View.

ViewEventListener.on_load()

Called when the file is finished loading.

Since build 3155

ViewEventListener.on_load_async()

Same as on_load but runs in a separate thread, not blocking the application.

Since build 3155

ViewEventListener.on_reload()

Called when the file is reloaded.

Since build 4050

ViewEventListener.on_reload_async()

Same as on_reload but runs in a separate thread, not blocking the application.

Since build 4050

ViewEventListener.on_revert()

Called when the file is reverted.

Since build 4050

ViewEventListener.on_revert_async()

Same as on_revert but runs in a separate thread, not blocking the application.

Since build 4050

ViewEventListener.on_pre_move()

Called right before a view is moved between two windows or within a window.

Since build 4050

ViewEventListener.on_post_move()

Called right after a view is moved between two windows or within a window.

Since build 4050

ViewEventListener.on_post_move_async()

Same as on_post_move but runs in a separate thread, not blocking the application.

Since build 4050

ViewEventListener.on_pre_close()

Called when a view is about to be closed. The view will still be in the window at this point.

Since build 3155

ViewEventListener.on_close()

Called when a view is closed (note, there may still be other views into the same buffer).

Since build 3155

ViewEventListener.on_pre_save()

Called just before a view is saved.

Since build 3155

ViewEventListener.on_pre_save_async()

Same as on_pre_save but runs in a separate thread, not blocking the application.

Since build 3155

ViewEventListener.on_post_save()

Called after a view has been saved.

Since build 3155

ViewEventListener.on_post_save_async()

Same as on_post_save but runs in a separate thread, not blocking the application.

Since build 3155

ViewEventListener.on_modified()

Called after changes have been made to the view.

ViewEventListener.on_modified_async()

Same as on_modified but runs in a separate thread, not blocking the application.

ViewEventListener.on_selection_modified()

Called after the selection has been modified in the view.

ViewEventListener.on_selection_modified_async()

Called after the selection has been modified in the view. Runs in a separate thread, and does not block the application.

ViewEventListener.on_activated()

Called when a view gains input focus.

ViewEventListener.on_activated_async()

Called when the view gains input focus. Runs in a separate thread, and does not block the application.

ViewEventListener.on_deactivated()

Called when the view loses input focus.

ViewEventListener.on_deactivated_async()

Called when the view loses input focus. Runs in a separate thread, and does not block the application.

ViewEventListener.on_hover(point: Point, hover_zone: HoverZone)

Called when the user’s mouse hovers over the view for a short period.

Parameters:

point – The closest point in the view to the mouse location. The mouse may not actually be located adjacent based on the value of hover_zone.

hover_zone – Which element in Sublime Text the mouse has hovered over.

ViewEventListener.on_query_context(key: str, operator: QueryOperator, operand: str, match_all: bool) → bool | None

Called when determining to trigger a key binding with the given context key. If the plugin knows how to respond to the context, it should return either True of False. If the context is unknown, it should return None.

Parameters:

key – The context key to query. This generally refers to specific state held by a plugin.

operator – The operator to check against the operand; whether to check equality, inequality, etc.

operand – The value against which to check using the operator.

match_all – This should be used if the context relates to the selections: does every selection have to match (match_all == True), or is at least one matching enough (match_all == False)?

Returns:

True or False if the plugin handles this context key and it either does or doesn’t match. If the context is unknown return None.

ViewEventListener.on_query_completions(prefix: str, locations: List[Point]) → None | List[CompletionValue] | Tuple[List[CompletionValue], AutoCompleteFlags] | CompletionList

Called whenever completions are to be presented to the user.

Parameters:

prefix – The text already typed by the user.

locations – The list of points being completed. Since this method is called for all completions no matter the syntax, self.view.match_selector(point, relevant_scope) should be called to determine if the point is relevant.

Returns:

A list of completions in one of the valid formats or None if no completions are provided.

ViewEventListener.on_text_command(command_name: str, args: CommandArgs) → Tuple[str, CommandArgs]

Called when a text command is issued. The listener may return a `` (command, arguments)`` tuple to rewrite the command, or None to run the command unmodified.

Since build 3155

ViewEventListener.on_post_text_command(command_name: str, args: CommandArgs)

Called after a text command has been executed.

@classmethod
def is_applicable(cls, settings: sublime.Settings) -> bool:
    """
    :returns: Whether this listener should apply to a view with the given `Settings`.
    """
    return True

@classmethod
def applies_to_primary_view_only(cls) -> bool:
    """
    :returns: Whether this listener should apply only to the primary view
              for a file or all of its clones as well.
    """
    return True

def __init__(self, view: sublime.View):
    self.view: sublime.View = view

18.3. TextChangeListener

TextChangeListener objects are instantiated once per Buffer, regardless of how many Views are attached to it. So any state saved within TextChangeListener sub-classes you create will be for just the one Buffer.

The events are about text changes made to the Buffer the object is attached to.

TextEventListener.on_text_changed(changes: List[TextChange])

Called once after changes has been made to a buffer, with detailed information about what has changed.

TextEventListener.on_text_changed_async(changes: List[TextChange])

Same as on_text_changed but runs in a separate thread, not blocking the application.

TextEventListener.on_revert()

Called when the buffer is reverted.

A revert does not trigger text changes. If the contents of the buffer are required here use View.substr.

TextEventListener.on_revert_async()

Same as on_revert but runs in a separate thread, not blocking the application.

TextEventListener.on_reload()

Called when the buffer is reloaded.

A reload does not trigger text changes. If the contents of the buffer are required here use View.substr.

TextEventListener.on_reload_async()

Same as on_reload but runs in a separate thread, not blocking the application.

@classmethod
def is_applicable(cls, buffer: sublime.Buffer):
    """
    :returns: Whether this listener should apply to the provided buffer.
    """
    return True

def __init__(self):
    """ """
    self.__key = None
    self.buffer: sublime.Buffer = None

def detach(self):
    """
    Remove this listener from the buffer.

    Async callbacks may still be called after this, as they are queued
    separately.

    :raises ValueError: if the listener is not attached.
    """
    if self.__key is None:
        raise ValueError('TextChangeListener is not attached')

    sublime_api.buffer_clear_text_listener(self.buffer.buffer_id, self.__key)
    if self.buffer.buffer_id in text_change_listeners:
        new_listeners = []
        for listener in text_change_listeners[self.buffer.buffer_id]:
            if listener is not self:
                new_listeners.append(listener)
        text_change_listeners[self.buffer.buffer_id] = new_listeners
    self.__key = None

def attach(self, buffer: sublime.Buffer):
    """
    Attach this listener to a buffer.

    :raises ValueError: if the listener is already attached.
    """
    if not isinstance(buffer, sublime.Buffer):
        raise TypeError('Must be a buffer')

    if self.__key is not None:
        raise ValueError('TextChangeListener is already attached')

    self.buffer = buffer
    if buffer.buffer_id not in text_change_listeners:
        text_change_listeners[buffer.buffer_id] = []
    text_change_listeners[buffer.buffer_id].append(self)
    self.__key = sublime_api.buffer_add_text_listener(buffer.buffer_id, self)

def is_attached(self) -> bool:
    """
    :returns:
        whether the listener is receiving events from a buffer. May not be
        called from ``__init__``.
    """
    return self.__key is not None