Plugins¶
See also
- API Reference
- More information on the Python API.
Plugins are Python scripts implementing *Command
classes from
sublime_plugin
.
Where to Store Plugins¶
Sublime Text will look for plugins in these places:
Packages
Packages/<pkg_name>
.sublime-package
files
Plugin files nested deeper in Packages
won’t be loaded.
All plugins should live inside a folder of their own and not directly
under Packages
. This will spare you confusions when Sublime Text attempts
to sort packages for loading.
Conventions for Command Names¶
By convention, Sublime Text command class names are suffixed with Command
and written as NamesLikeThisCommand
.
However, command names are automatically transformed from NamesLikeThisCommand
to name_like_this
. Thus, ExampleCommand
would become example
,
and AnotherExampleCommand
would become another_example
.
In names for classes defining commands, use NameLikeThisCommand
. To call a
command from the API, use the standardized name_like_this
.
Types of Commands¶
sublime_plugin.WindowCommand
sublime_plugin.TextCommand
sublime_plugin.EventListener
Instances of WindowCommand
have a .window
attribute pointing to the
window instance that created them. Similarly, instances of TextCommand
have a .view
attribute.
How to Call Commands from the API¶
Depending on the type of command, use a reference to a View
or a Window
and call <object>.run_command('command_name')
. In addition to the command’s
name, .run_command
accepts a dictionary whose keys are the names of valid
parameters for said command:
window.run_command("echo", {"Tempus": "Irreparabile", "Fugit": "."})
Command Arguments¶
All user-provided arguments to commands must be valid JSON types.
Text Commands and the edit
Object¶
Text commands receive an edit
object passed to them by Sublime Text.
All actions done within an edit
are grouped as a single undo action.
Callbacks such as on_modified()
and on_selection_modified()
are called
when the edit is finished.
Contrary to earlier versions of Sublime Text, the edit
object’s life time is
now managed solely by the editor. Plugin authors must ensure to perform all
editing operations within the run()
method of text commands so that macros
and repeating commands work as expected.
To call other commands from your own commands, use the run_command()
function.
Responding to Events¶
Any subclass of EventListener
will be able to respond to events. You cannot
make a class derive both from EventListener
and from any other type of
command.
Sublime Text and the Python Standard Library¶
Sublime Text ships with a trimmed down standard library.
Automatic Plugin Reload¶
Sublime Text will reload topmost Python modules as they change (perhaps because you are editing a .py file within Packages). By contrast, Python subpackages won’t be reloaded automatically, and this can lead to confusion while you’re developing plugins. Generally speaking, it’s best to restart Sublime Text after you’ve made changes to plugin files, so all changes can take effect.
Multithreading¶
Only the set_timeout()
function is safe to call from different threads.