I’m starting work on some additional features for my addon and I’ve run into a snag… The api docs at:
http://www.sublimetext.com/docs/3/api_reference.html
https://www.sublimetext.com/docs/3/api_reference.html
I took all of the Callback functions and created a template file out of them. The issue is, the functions don’t seem to list the actual arguments ( some cases they simply show , etc… and they all don’t show self but from what I’ve seen self is needed )…
If anyone with more experience with SublimeText API with the Callback classes can take a look to see what doesn’t look right - that’d be a huge help!
The errors I’m getting are numerous - Basically 2 of the callback functions don’t exist ( using Sublime Text 3 - latest ) - ListInputHandler and TextInputHandler
AttributeError: ‘module’ object has no attribute ‘TextInputHandler’
AttributeError: ‘module’ object has no attribute ‘ListInputHandler’
is_applicable missing _settings - so it probably doesn’t need self for this callback but why?
class MyViewEventListener( sublime_plugin.ViewEventListener ):
##
## A @classmethod that receives a Settings object and should return a bool indicating if this class applies to a view with those settings
## Returns: bool
##
def is_applicable( self, _settings ):
pass
Here’s the complete file - the goal of this is to make things easier for plugin developers by having the code already in place so they can copy the class they want - rename My to what they want and delete the functions they don’t need… or comment them out… It is a lot quicker than writing it all out…
I’ll probably convert them into snippets after it’s all settled to make it even easier… I may also eventually convert the non-callback classes into code so my mapper can map the functions so it they can be used as a quick-look-guide by pasting into the file as a snippet ( likely with limited comments and as compact as possible so the data shows up and doesn’t require a lot of scrolling… )
##
## Template File - Used to increase efficiency when developing addons which require SublimeText Callbacks - Josh 'Acecool' Moser
##
## Note: This is also to serve as a live-wiki / quick-glance reference guide for the callbacks when using my Code Navigation System with CodeMap...
## It shows you exactly what you need to know in the output panel with nothing else - there is a lot of fluff because it's meant as a template file however
## I am considering turning these into snippets - and if I do I can create a wiki snippet-code for these which removes most of the comments and new-lines
## leaving only the function definitions with pass on the same line so the mapper can be used, or not...
##
## Additionally, I may do the same thing with the non-callback classes so they can be mapped by my Code Navigation System to provide a reference guide
## when working with SublimeText objects..
##
##
## Sublime Text API to Code...
##
## http://www.sublimetext.com/docs/3/api_reference.html#sublime_plugin.ApplicationCommand
##
##
## General Information
## EXAMPLE PLUGINS
## Several pre-made plugins come with Sublime Text, you can find them in the Default package:
##
## Packages/Default/delete_word.py Deletes a word to the left or right of the cursor
## Packages/Default/duplicate_line.py Duplicates the current line
## Packages/Default/exec.py Uses phantoms to display errors inline
## Packages/Default/font.py Shows how to work with settings
## Packages/Default/goto_line.py Prompts the user for input, then updates the selection
## Packages/Default/mark.py Uses add_regions() to add an icon to the gutter
## Packages/Default/show_scope_name.py Uses a popup to show the scope names at the caret
## Packages/Default/trim_trailing_whitespace.py Modifies a buffer just before its saved
## Packages/Default/arithmetic.py Accepts an input from the user when run via the Command Palette
##
## PLUGIN LIFECYCLE
## At importing time, plugins may not call any API functions, with the exception of sublime.version(), sublime.platform(), sublime.architecture() and sublime.channel().
##
## If a plugin defines a module level function plugin_loaded(), this will be called when the API is ready to use. Plugins may also define plugin_unloaded(), to get notified just before the plugin is unloaded.
##
## THREADING
## All API functions are thread-safe, however keep in mind that from the perspective of code running in an alternate thread, application state will be changing while the code is running.
##
## UNITS AND COORDINATES
## API functions that accept or return coordinates or dimensions do so using device-independent pixel (dip) values. While in some cases these will be equivalent to device pixels, this is often not the case. Per the CSS specification, minihtml treats the px unit as device-independent.
##
## TYPES
## This documentation generally refers to simply Python data types. Some type names are classes documented herein, however there are also a few custom type names that refer to construct with specific semantics:
##
## location: a tuple of (str, str, (int, int)) that contains information about a location of a symbol. The first string is the absolute file path, the second is the file path relative to the project, the third element is a two-element tuple of the row and column.
## point: an int that represents the offset from the beginning of the editor buffer. The View methods text_point() and rowcol() allow converting to and from this format.
## value: any of the Python data types bool, int, float, str, list or dict.
## dip: a float that represents a device-independent pixel.
## vector: a tuple of (dip, dip) representing x and y coordinates.
## CommandInputHandler: a subclass of either TextInputHandler or ListInputHandler.
##
##
## Imports required by these...
##
import sublime
import sublime_plugin
##
## sublime_plugin.ApplicationCommand Class
##
class MyApplicationCommand( sublime_plugin.ApplicationCommand ):
##
## Called when the command is run.
##
def run( self, **_keyed_varargs ):
pass
##
## Returns True if the command is able to be run at this time. The default implementation simply always returns True.
##
## Returns: bool
##
def is_enabled( self, *_varargs ):
pass
##
## Returns True if the command should be shown in the menu at this time. The default implementation always returns True.
##
## Returns: bool
##
def is_visible( self, *_varargs ):
pass
##
## Returns True if a checkbox should be shown next to the menu item. The .sublime-menu file must have the checkbox attribute set to true for this to be used.
##
## Returns: bool
##
def is_checked( self, *_varargs ):
pass
##
## Returns a description of the command with the given arguments. Used in the menu, if no caption is provided. Return None to get the default description.
##
## Returns: str
##
def description( self, *_varargs ):
pass
##
## If this returns something other than None, the user will be prompted for an input before the command is run in the Command Palette.
##
## Returns: CommandInputHandler or None
##
def input( self, *_varargs ):
pass
##
## sublime_plugin.WindowCommandClass
##
## WindowCommands are instantiated once per window. The Window object may be retrieved via self.window
##
class MyWindowCommand( sublime_plugin.WindowCommand ):
##
## Called when the command is run.
##
def run( self, *_varargs ):
pass
##
## Returns True if the command is able to be run at this time. The default implementation simply always returns True.
##
## Returns: bool
##
def is_enabled( self, *_varargs ):
pass
##
## Returns True if the command should be shown in the menu at this time. The default implementation always returns True.
##
## Returns: bool
##
def is_visible( self, *_varargs ):
pass
##
## Returns a description of the command with the given arguments. Used in the menu, if no caption is provided. Return None to get the default description.
##
## Returns: str
##
def description( self, *_varargs ):
pass
##
## If this returns something other than None, the user will be prompted for an input before the command is run in the Command Palette.
##
## Returns: CommandInputHandler or None
##
def input( self, *_varargs ):
pass
##
## sublime_plugin.TextCommand Class
##
## TextCommands are instantiated once per view. The View object may be retrieved via self.view
##
class MyTextCommand( sublime_plugin.TextCommand ):
##
## Called when the command is run.
##
def run( self, _edit, *_varargs ):
pass
##
## Returns True if the command is able to be run at this time. The default implementation simply always returns True.
##
## Returns: bool
##
def is_enabled( self, *_varargs ):
pass
##
## Returns True if the command should be shown in the menu at this time. The default implementation always returns True.
##
## Returns: bool
##
def is_visible( self, *_varargs ):
pass
##
## Returns a description of the command with the given arguments. Used in the menus, and for Undo / Redo descriptions. Return None to get the default description.
##
## Returns: str
##
def description( self, *_varargs ):
pass
##
## Return True to receive an event argument when the command is triggered by a mouse action. The event information allows commands to determine which portion of the view was clicked on. The default implementation returns False.
##
## Returns: bool
##
def want_event( self ):
pass
##
## If this returns something other than None, the user will be prompted for an input before the command is run in the Command Palette.
##
## Returns: CommandInputHandler or None
##
def input( self, *_varargs ):
pass
##
## sublime_plugin.EventListener Class
##
## Note that many of these events are triggered by the buffer underlying the view, and thus the method is only called once, with the first view as the parameter.
##
class MyEventListener( sublime_plugin.EventListener ):
##
## Called when a new buffer is created.
##
def on_new( self, _view ):
pass
##
## Called when a new buffer is created. Runs in a separate thread, and does not block the application.
##
def on_new_async( self, _view ):
pass
##
## Called when a view is cloned from an existing one.
##
def on_clone( self, _view ):
pass
##
## Called when a view is cloned from an existing one. Runs in a separate thread, and does not block the application.
##
def on_clone_async( self, _view ):
pass
##
## Called when the file is finished loading.
##
def on_load( self, _view ):
pass
##
## Called when the file is finished loading. Runs in a separate thread, and does not block the application.
##
def on_load_async( self, _view ):
pass
##
## Called when a view is about to be closed. The view will still be in the window at this point.
##
def on_pre_close( self, _view ):
pass
##
## Called when a view is closed (note, there may still be other views into the same buffer).
##
def on_close( self, _view ):
pass
##
## Called just before a view is saved.
##
def on_pre_save( self, _view ):
pass
##
## Called just before a view is saved. Runs in a separate thread, and does not block the application.
##
def on_pre_save_async( self, _view ):
pass
##
## Called after a view has been saved.
##
def on_post_save( self, _view ):
pass
##
## Called after a view has been saved. Runs in a separate thread, and does not block the application.
##
def on_post_save_async( self, _view ):
pass
##
## Called after changes have been made to a view.
##
def on_modified( self, _view ):
pass
##
## Called after changes have been made to a view. Runs in a separate thread, and does not block the application.
##
def on_modified_async( self, _view ):
pass
##
## Called after the selection has been modified in a view.
##
def on_selection_modified( self, _view ):
pass
##
## Called after the selection has been modified in a view. Runs in a separate thread, and does not block the application.
##
def on_selection_modified_async( self, _view ):
pass
##
## Called when a view gains input focus.
##
def on_activated( self, _view ):
pass
##
## Called when a view gains input focus. Runs in a separate thread, and does not block the application.
##
def on_activated_async( self, _view ):
pass
##
## Called when a view loses input focus.
##
def on_deactivated( self, _view ):
pass
##
## Called when a view loses input focus. Runs in a separate thread, and does not block the application.
##
def on_deactivated_async( self, _view ):
pass
##
## Called when the user's mouse hovers over a view for a short period.
##
## point is 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:
## sublime.HOVER_TEXT: When the mouse is hovered over text.
## sublime.HOVER_GUTTER: When the mouse is hovered over the gutter.
## sublime.HOVER_MARGIN: When the mouse is hovered in whitespace to the right of a line.
##
def on_hover( self, _view, _point, _hover_zone ):
pass
##
## 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.
##
## operator is one of:
## sublime.OP_EQUAL: Is the value of the context equal to the operand?
## sublime.OP_NOT_EQUAL: Is the value of the context not equal to the operand?
## sublime.OP_REGEX_MATCH: Does the value of the context match the regex given in operand?
## sublime.OP_NOT_REGEX_MATCH: Does the value of the context not match the regex given in operand?
## sublime.OP_REGEX_CONTAINS: Does the value of the context contain a substring matching the regex given in operand?
## sublime.OP_NOT_REGEX_CONTAINS: Does the value of the context not contain a substring matching the regex given in operand?
##
## match_all 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: bool or None
##
def on_query_context( self, _view, _key, _operator, _operand, _match_all ):
pass
##
## Called whenever completions are to be presented to the user. The prefix is a unicode string of the text to complete.
## locations is a list of points. Since this method is called for all completions in every view no matter the syntax, view.match_selector(point, relevant_scope) should be called to determine if the point is relevant.
##
## The return value must be one of the following formats:
##
## None: no completions are provided
##
## return None
##
##
## A list of 2-element lists/tuples. The first element is a unicode string of the completion trigger, the second is the unicode replacement text.
##
## return [ [ "me1", "method1( self )" ], [ "me2", "method2( self )" ] ]
##
##
## The trigger may contain a tab character (\t) followed by a hint to display in the right-hand side of the completion box.
##
## return [
## [ "me1\tmethod", "method1( self )" ],
## [ "me2\tmethod", "method2( self )" ]
## ]
##
##
## The replacement text may contain dollar-numeric fields such as a snippet does, e.g. $0, $1.
##
## return [
## [ "fn", "def ${1:name}( $2 ) { $0 }" ],
## [ "for", "for ( $1; $2; $3 ) { $0 }" ]
## ]
##
##
## A 2-element tuple with the first element being the list format documented above, and the second element being bit flags from the following list:
##
## sublime.INHIBIT_WORD_COMPLETIONS: prevent Sublime Text from showing completions based on the contents of the view
## sublime.INHIBIT_EXPLICIT_COMPLETIONS: prevent Sublime Text from showing completions based on .sublime-completions files
##
## return (
## [
## [ "me1", "method1( self )" ],
## [ "me2", "method2( self )" ]
## ],
## sublime.INHIBIT_WORD_COMPLETIONS | sublime.INHIBIT_EXPLICIT_COMPLETIONS
## )
##
##
## Returns: list, tuple or None
##
def on_query_completions( self, _view, _prefix, _locations ):
pass
##
## 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.
## Returns: (str, dict)
##
def on_text_command( self, _view, _command_name, _args ):
pass
##
## 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.
## Returns: (str, dict)
##
def on_window_command( self, _window, _command_name, _args ):
pass
##
## Called after a text command has been executed.
##
def on_post_text_command( self, _view, _command_name, _args ):
pass
##
## Called after a window command has been executed.
##
def on_post_window_command( self, _window, _command_name, _args ):
pass
##
## sublime_plugin.ViewEventListener Class
##
## A class that provides similar event handling to EventListener, but bound to a specific view. Provides class method-based filtering to control what views objects are created for.
##
## The view is passed as a single parameter to the constructor. The default implementation makes the view available via self.view.
##
class MyViewEventListener( sublime_plugin.ViewEventListener ):
##
## A @classmethod that receives a Settings object and should return a bool indicating if this class applies to a view with those settings
## Returns: bool
##
def is_applicable( self, _settings ):
pass
##
## A @classmethod that should return a bool indicating if this class applies only to the primary view for a file. A view is considered primary if it is the only, or first, view into a file.
## Returns: bool
##
def applies_to_primary_view_only( self ):
pass
##
## Called when the file is finished loading.
##
def on_load( self ):
pass
##
## Called when the file is finished loading. Runs in a separate thread, and does not block the application.
##
def on_load_async( self ):
pass
##
## Called when a view is about to be closed. The view will still be in the window at this point.
##
def on_pre_close( self ):
pass
##
## Called when a view is closed (note, there may still be other views into the same buffer).
##
def on_close( self ):
pass
##
## Called just before a view is saved.
##
def on_pre_save( self ):
pass
##
## Called just before a view is saved. Runs in a separate thread, and does not block the application.
##
def on_pre_save_async( self ):
pass
##
## Called after a view has been saved.
##
def on_post_save( self ):
pass
##
## Called after a view has been saved. Runs in a separate thread, and does not block the application.
##
def on_post_save_async( self ):
pass
##
## Called after changes have been made to the view.
##
def on_modified( self ):
pass
##
## Called after changes have been made to the view. Runs in a separate thread, and does not block the application.
##
def on_modified_async( self ):
pass
##
## Called after the selection has been modified in the view.
##
def on_selection_modified( self ):
pass
##
## Called after the selection has been modified in the view. Runs in a separate thread, and does not block the application.
##
def on_selection_modified_async( self ):
pass
##
## Called when a view gains input focus.
##
def on_activated( self ):
pass
##
## Called when the view gains input focus. Runs in a separate thread, and does not block the application.
##
def on_activated_async( self ):
pass
##
## Called when the view loses input focus.
##
def on_deactivated( self ):
pass
##
## Called when the view loses input focus. Runs in a separate thread, and does not block the application.
##
def on_deactivated_async( self ):
pass
##
## Called when the user's mouse hovers over the view for a short period.
##
## point is 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:
## sublime.HOVER_TEXT: When the mouse is hovered over text.
## sublime.HOVER_GUTTER: When the mouse is hovered over the gutter.
## sublime.HOVER_MARGIN: When the mouse is hovered in whitespace to the right of a line.
##
## Removed self, _view
##
def on_hover( self, _point, _hover_zone ):
pass
##
## 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.
##
## operator is one of:
## sublime.OP_EQUAL: Is the value of the context equal to the operand?
## sublime.OP_NOT_EQUAL: Is the value of the context not equal to the operand?
## sublime.OP_REGEX_MATCH: Does the value of the context match the regex given in operand?
## sublime.OP_NOT_REGEX_MATCH: Does the value of the context not match the regex given in operand?
## sublime.OP_REGEX_CONTAINS: Does the value of the context contain a substring matching the regex given in operand?
## sublime.OP_NOT_REGEX_CONTAINS: Does the value of the context not contain a substring matching the regex given in operand?
##
## match_all 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: bool or None
##
## Removed self, _view
##
def on_query_context( self, _key, _operator, _operand, _match_all ):
pass
##
## Called whenever completions are to be presented to the user. The prefix is a unicode string of the text to complete.
##
## locations is a list of points. 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.
##
## The return value must be one of the following formats:
##
## None: no completions are provided
##
## return None
##
##
## A list of 2-element lists/tuples. The first element is a unicode string of the completion trigger, the second is the unicode replacement text.
##
## return [ [ "me1", "method1( self )" ], [ "me2", "method2( self )" ] ]
##
##
## The trigger may contain a tab character (\t) followed by a hint to display in the right-hand side of the completion box.
##
## return [
## [ "me1\tmethod", "method1( self )" ],
## [ "me2\tmethod", "method2( self )" ]
## ]
##
##
## The replacement text may contain dollar-numeric fields such as a snippet does, e.g. $0, $1.
##
## return [
## [ "fn", "def ${1:name}( $2 ) { $0 }" ],
## [ "for", "for ( $1; $2; $3 ) { $0 }" ]
## ]
##
##
## A 2-element tuple with the first element being the list format documented above, and the second element being bit flags from the following list:
##
## sublime.INHIBIT_WORD_COMPLETIONS: prevent Sublime Text from showing completions based on the contents of the view
## sublime.INHIBIT_EXPLICIT_COMPLETIONS: prevent Sublime Text from showing completions based on .sublime-completions files
##
## return (
## [
## [ "me1", "method1( self )" ],
## [ "me2", "method2( self )" ]
## ],
## sublime.INHIBIT_WORD_COMPLETIONS | sublime.INHIBIT_EXPLICIT_COMPLETIONS
## )
##
##
## Returns: list, tuple or None
##
def on_query_completions( self, _view, _prefix, _locations ):
pass
##
## 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.
## Returns: (str, dict)
##
def on_text_command( self, _view, _command_name, _args ):
pass
##
## Called after a text command has been executed.
##
def on_post_text_command( self, _view, _command_name, _args ):
pass
##
## These apparently do not exist
##
##
## sublime_plugin.TextInputHandler Class
##
## TextInputHandlers can be used to accept textual input in the Command Palette. Return a subclass of this from the input() method of a command.
##
class MyTextInputHandler( sublime_plugin.TextInputHandler ):
##
## The command argument name this input handler is editing. Defaults to foo_bar for an input handler named FooBarInputHandler
##
## Returns: str
##
def name( self ):
pass
##
## Placeholder text is shown in the text entry box before the user has entered anything. Empty by default.
##
## Returns: str
##
def placeholder( self ):
pass
##
## Initial text shown in the text entry box. Empty by default.
##
## Returns: str
##
def initial_text( self ):
pass
##
## Called whenever the user changes the text in the entry box. The returned value (either plain text or HTML) will be shown in the preview area of the Command Palette.
##
## Returns: str or sublime.Html(str)
##
def preview( self, _text ):
pass
##
## Called whenever the user presses enter in the text entry box. Return False to disallow the current value.
##
## Returns: bool
##
def validate( self, _text ):
pass
##
## Called when the input handler is canceled, either by the user pressing backspace or escape.
##
def cancel( self ):
pass
##
## Called when the input is accepted, after the user has pressed enter and the text has been validated.
##
def confirm( self, _text ):
pass
##
## Returns the next input after the user has completed this one. May return None to indicate no more input is required, or sublime_plugin.Back() to indicate that the input handler should be poped off the stack instead.
##
## Returns: CommandInputHandler or None
##
def next_input( self, *_varargs ):
pass
##
## The text to show in the Command Palette when this input handler is not at the top of the input handler stack. Defaults to the text the user entered.
##
## Returns: str
##
def description( self, _text ):
pass
##
## sublime_plugin.ListInputHandler Class
##
## TextInputHandlers can be used to accept textual input in the Command Palette. Return a subclass of this from the input() method of a command.
##
class MyListInputHandler( sublime_plugin.ListInputHandler ):
##
## The command argument name this input handler is editing. Defaults to foo_bar for an input handler named FooBarInputHandler
##
## Returns: str
##
def name( self ):
pass
##
## The items to show in the list. If returning a list of (str, value) tuples, then the str will be shown to the user, while the value will be used as the command argument.
## Optionally return a tuple of (list_items, selected_item_index) to indicate an initial selection.
##
## Returns: [str] or [(str,value)]
##
def list_items( self ):
pass
##
## Placeholder text is shown in the text entry box before the user has entered anything. Empty by default.
##
## Returns: str
##
def placeholder( self ):
pass
##
## Initial text shown in the text entry box. Empty by default.
##
## Returns: str
##
def initial_text( self ):
pass
##
## Called whenever the user changes the selected item. The returned value (either plain text or HTML) will be shown in the preview area of the Command Palette.
##
## Returns: str or sublime.Html(str)
##
def preview( self, _value ):
pass
##
## Called whenever the user presses enter in the text entry box. Return False to disallow the current value.
##
## Returns: bool
##
def validate( self, _value ):
pass
##
## Called when the input handler is canceled, either by the user pressing backspace or escape.
##
def cancel( self ):
pass
##
## Called when the input is accepted, after the user has pressed enter and the item has been validated.
##
def confirm( self, _value ):
pass
##
## Returns the next input after the user has completed this one. May return None to indicate no more input is required, or sublime_plugin.Back() to indicate that the input handler should be poped off the stack instead.
##
## Returns: CommandInputHandler or None
##
def next_input( self, *_varargs ):
pass
##
## The text to show in the Command Palette when this input handler is not at the top of the input handler stack. Defaults to the text of the list item the user selected.
##
## Returns: str
##
def description( self, _value, _text ):
pass
A direct link to the file can be found here which also contains more data pending conversion: https://www.dropbox.com/s/x4m5rac1xs7cgba/__sublime_plugin.EventListener_Class__and_ViewEventListener_Template.txt.py?dl=0
Any help to get this finalized would be a great help and I’m sure it’ll help plugin developers too…