.. include:: /include/substitutions.txt .. include:: /include/external_links.txt .. include:: /include/custom_roles.txt .. _event list: ********** Event list ********** As Sublime |nbsp| Text is continually being updated, it is noted that this list is current as of build 4200. 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. .. method:: EventListener.on_init(views: List[View]) Called once with a list of views that were loaded before the EventListener was instantiated Since build 4050 .. method:: EventListener.on_exit() Called once after the API has shut down, immediately before the plugin_host process exits Since build 4050 .. method:: EventListener.on_new(view: View) Called when a new file is created. .. method:: EventListener.on_new_async(view: View) Called when a new buffer is created. Runs in a separate thread, and does not block the application. .. method:: EventListener.on_associate_buffer(buffer: View) Called when a buffer is associated with a file. buffer will be a Buffer object. Since build 4084 .. method:: 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 .. method:: EventListener.on_clone(view: View) Called when a view is cloned from an existing one. .. method:: 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. .. method:: EventListener.on_load(view: View) Called when the file is finished loading. .. method:: EventListener.on_load_async(view: View) Called when the file is finished loading. Runs in a separate thread, and does not block the application. .. method:: EventListener.on_reload(view: View) Called when the View is reloaded. Since build 4050 .. method:: 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 .. method:: EventListener.on_revert(view: View) Called when the View is reverted. Since build 4050 .. method:: 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 .. method:: 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 .. method:: 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 .. method:: 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 .. method:: 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. .. method:: EventListener.on_close(view: View) Called when a view is closed (note, there may still be other views into the same buffer). .. method:: EventListener.on_pre_save(view: View) Called just before a view is saved. .. method:: 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. .. method:: EventListener.on_post_save(view: View) Called after a view has been saved. .. method:: 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. .. method:: EventListener.on_modified(view: View) Called after changes have been made to a view. .. method:: 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. .. method:: EventListener.on_selection_modified(view: View) Called after the selection has been modified in a view. .. method:: 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. .. method:: EventListener.on_activated(view: View) Called when a view gains input focus. .. method:: EventListener.on_activated_async(view: View) Called when a view gains input focus. Runs in a separate thread, and does not block the application. .. method:: EventListener.on_deactivated(view: View) Called when a view loses input focus. .. method:: EventListener.on_deactivated_async(view: View) Called when a view loses input focus. Runs in a separate thread, and does not block the application. .. method:: EventListener.on_hover(view: View, point: Point, hover_zone: HoverZone) Called when the user's mouse hovers over the view for a short period. :param view: The view :param 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``. :param hover_zone: Which element in Sublime |nbsp| Text the mouse has hovered over. .. method:: EventListener.on_query_context(\ view: View, key: str, operator: QueryOperator, operand: str, match_all: bool) -> Optional[bool] 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. :param key: The context key to query. This generally refers to specific state held by a plugin. :param operator: The operator to check against the operand; whether to check equality, inequality, etc. :param operand: The value against which to check using the ``operator``. :param 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``. .. method:: EventListener.on_query_completions(view: View, prefix: str, locations: List[Point]) -> Union[\ None, List[CompletionValue], Tuple[List[CompletionValue], AutoCompleteFlags], CompletionList] Called whenever completions are to be presented to the user. :param prefix: The text already typed by the user. :param 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. .. method:: EventListener.on_text_command(view: View, command_name: str, args: CommandArgs) -> (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. .. method:: EventListener.on_window_command(window: Window, command_name: str, args: CommandArgs) -> (str, 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. .. method:: EventListener.on_post_text_command(view: View, command_name: str, args: CommandArgs) Called after a text command has been executed. .. method:: EventListener.on_post_window_command(window: Window, command_name: str, args: CommandArgs) Called after a window command has been executed. .. method:: EventListener.on_new_window(window: Window) Called when a window is created, passed the Window object. Since build 4050 .. method:: 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 .. method:: EventListener.on_pre_close_window(window: Window) Called right before a window is closed, passed the Window object. Since build 4050 .. method:: EventListener.on_new_project(window: Window) Called right after a new project is created, passed the Window object. Since build 4050 .. method:: 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 .. method:: EventListener.on_load_project(window: Window) Called right after a project is loaded, passed the Window object. Since build 4050 .. method:: 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 .. method:: EventListener.on_pre_save_project(window: Window) Called right before a project is saved, passed the Window object. Since build 4050 .. method:: EventListener.on_post_save_project(window: Window) Called right after a project is saved, passed the Window object. Since build 4050 .. method:: 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 .. method:: EventListener.on_pre_close_project(window: Window) Called right before a project is closed, passed the Window object. 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 ``sTextCommand``\ s. So any state saved within ViewEventListener sub-classes you create will be for just the one View. .. method:: ViewEventListener.on_load() Called when the file is finished loading. Since build 3155 .. method:: ViewEventListener.on_load_async() Same as `on_load` but runs in a separate thread, not blocking the application. Since build 3155 .. method:: ViewEventListener.on_reload() Called when the file is reloaded. Since build 4050 .. method:: ViewEventListener.on_reload_async() Same as `on_reload` but runs in a separate thread, not blocking the application. Since build 4050 .. method:: ViewEventListener.on_revert() Called when the file is reverted. Since build 4050 .. method:: ViewEventListener.on_revert_async() Same as `on_revert` but runs in a separate thread, not blocking the application. Since build 4050 .. method:: ViewEventListener.on_pre_move() Called right before a view is moved between two windows or within a window. Since build 4050 .. method:: ViewEventListener.on_post_move() Called right after a view is moved between two windows or within a window. Since build 4050 .. method:: ViewEventListener.on_post_move_async() Same as `on_post_move` but runs in a separate thread, not blocking the application. Since build 4050 .. method:: 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 .. method:: ViewEventListener.on_close() Called when a view is closed (note, there may still be other views into the same buffer). Since build 3155 .. method:: ViewEventListener.on_pre_save() Called just before a view is saved. Since build 3155 .. method:: ViewEventListener.on_pre_save_async() Same as `on_pre_save` but runs in a separate thread, not blocking the application. Since build 3155 .. method:: ViewEventListener.on_post_save() Called after a view has been saved. Since build 3155 .. method:: ViewEventListener.on_post_save_async() Same as `on_post_save` but runs in a separate thread, not blocking the application. Since build 3155 .. method:: ViewEventListener.on_modified() Called after changes have been made to the view. .. method:: ViewEventListener.on_modified_async() Same as `on_modified` but runs in a separate thread, not blocking the application. .. method:: ViewEventListener.on_selection_modified() Called after the selection has been modified in the view. .. method:: 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. .. method:: ViewEventListener.on_activated() Called when a view gains input focus. .. method:: ViewEventListener.on_activated_async() Called when the view gains input focus. Runs in a separate thread, and does not block the application. .. method:: ViewEventListener.on_deactivated() Called when the view loses input focus. .. method:: ViewEventListener.on_deactivated_async() Called when the view loses input focus. Runs in a separate thread, and does not block the application. .. method:: ViewEventListener.on_hover(point: Point, hover_zone: HoverZone) Called when the user's mouse hovers over the view for a short period. :param 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``. :param hover_zone: Which element in Sublime |nbsp| Text the mouse has hovered over. .. method:: ViewEventListener.on_query_context(key: str, operator: QueryOperator, operand: str, match_all: bool) -> Optional[bool] 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. :param key: The context key to query. This generally refers to specific state held by a plugin. :param operator: The operator to check against the operand; whether to check equality, inequality, etc. :param operand: The value against which to check using the ``operator``. :param 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``. .. method:: ViewEventListener.on_query_completions(prefix: str, locations: List[Point]) -> Union[\ None, List[CompletionValue], Tuple[List[CompletionValue], AutoCompleteFlags], CompletionList] Called whenever completions are to be presented to the user. :param prefix: The text already typed by the user. :param 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. .. method:: 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 .. method:: ViewEventListener.on_post_text_command(command_name: str, args: CommandArgs) Called after a text command has been executed. .. code-block:: python @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 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. .. method:: TextEventListener.on_text_changed(changes: List[TextChange]) Called once after changes has been made to a buffer, with detailed information about what has changed. .. method:: TextEventListener.on_text_changed_async(changes: List[TextChange]) Same as `on_text_changed` but runs in a separate thread, not blocking the application. .. method:: 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`. .. method:: TextEventListener.on_revert_async() Same as `on_revert` but runs in a separate thread, not blocking the application. .. method:: 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`. .. method:: TextEventListener.on_reload_async() Same as `on_reload` but runs in a separate thread, not blocking the application. .. code-block:: python @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