Package Control is the first and probably most essential Sublime Text plugin. It enables the easy installation, download, and update of packages or plugins into Sublime Text. The terms package and plugin are often used interchangeably. To install Package Control, follow the instructions found on the Package Control website. Sublime Text has a powerful, Python API that allows plugins to augment built-in functionality. Package Control can be installed via the command palette, providing simple access to thousands of packages built by the community.
Warning
Development of Sublime Text has moved on to version 3.
As a result,this branch for Sublime Text 2will not be updated any more.Please select the latest branchin the panel on the bottom leftand consider updating Sublime Text.
See also
- API Reference
- More information on the Python API.
- Plugins Reference
- More information about plugins.
Sublime Text 2 is programmable with Python scripts. Plugins reuse existingcommands or create new ones to build a feature. Plugins are a logical entity,rather than a physical one.
Prerequisites¶
In order to write plugins, you must be able to program in Python.
Where to Store Plugins¶
Sublime Text 2 will only look for plugins in these places:
PackagesPackages//
Consequently, any plugin nested deeper in Packages won't be loaded.
Keeping plugins just under Packages is discouraged, because Sublime Textsorts packages in a predefined way before loading them. So, you might getconfusing results if your plugins live outside a package.
Your First Plugin¶
Let's write a 'Hello, World!' plugin for Sublime Text 2:
- Select Tools | New Plugin… in the menu.
- Save to
Packages/User/hello_world.py.
You've just written your first plugin. Let's put it to use:
- Create a new buffer (
Ctrl+n). - Open the python console (
Ctrl+`). - Type:
view.run_command('example')and press enter.
You should see the text 'Hello, World!' in your new buffer.
Analyzing Your First Plugin¶
The plugin created in the previous section should look roughly like this:
Both the sublime and sublime_plugin modules are provided bySublime Text 2.
All new commands derive from the *Command classes defined in sublime_plugin(more on this later).
Sublime Text Xml Pretty
The rest of the code is concerned with the particulars of TextCommand or withthe API. We'll discuss those topics in later sections.
Before moving on, though, we'll look at how we invoked the new command. First weopened the python console, and then we issued a call to view.run_command(). Thisis rather an inconvenient way of using plugins, but it's often useful whenyou're in the development phase of a plugin. For now, keep in mind that your commandscan be accessed both through key bindings and by other means, just like other commands.
Sublime Text Format Xml
Conventions for Command Names¶
You might have noticed that our command is defined with the name ExampleCommand,but we pass the string example to the API call instead. This is necessary becauseSublime Text 2 normalizes command names, stripping the Command suffix andseparating CamelCasedPhrases with underscores, like this: snake_cased_phrases.
New commands should follow the CamelCase pattern for class names.
Types of Commands¶
You can create the following types of commands:
- Application commands (
ApplicationCommand) - Window commands (
WindowCommand) - Text commands (
TextCommand)
When writing plugins, consider your goal and choose the appropriate type ofcommands for your plugin.
Where to Store Plugins¶
Sublime Text 2 will only look for plugins in these places:
PackagesPackages//
Consequently, any plugin nested deeper in Packages won't be loaded.
Keeping plugins just under Packages is discouraged, because Sublime Textsorts packages in a predefined way before loading them. So, you might getconfusing results if your plugins live outside a package.
Your First Plugin¶
Let's write a 'Hello, World!' plugin for Sublime Text 2:
- Select Tools | New Plugin… in the menu.
- Save to
Packages/User/hello_world.py.
You've just written your first plugin. Let's put it to use:
- Create a new buffer (
Ctrl+n). - Open the python console (
Ctrl+`). - Type:
view.run_command('example')and press enter.
You should see the text 'Hello, World!' in your new buffer.
Analyzing Your First Plugin¶
The plugin created in the previous section should look roughly like this:
Both the sublime and sublime_plugin modules are provided bySublime Text 2.
All new commands derive from the *Command classes defined in sublime_plugin(more on this later).
Sublime Text Xml Pretty
The rest of the code is concerned with the particulars of TextCommand or withthe API. We'll discuss those topics in later sections.
Before moving on, though, we'll look at how we invoked the new command. First weopened the python console, and then we issued a call to view.run_command(). Thisis rather an inconvenient way of using plugins, but it's often useful whenyou're in the development phase of a plugin. For now, keep in mind that your commandscan be accessed both through key bindings and by other means, just like other commands.
Sublime Text Format Xml
Conventions for Command Names¶
You might have noticed that our command is defined with the name ExampleCommand,but we pass the string example to the API call instead. This is necessary becauseSublime Text 2 normalizes command names, stripping the Command suffix andseparating CamelCasedPhrases with underscores, like this: snake_cased_phrases.
New commands should follow the CamelCase pattern for class names.
Types of Commands¶
You can create the following types of commands:
- Application commands (
ApplicationCommand) - Window commands (
WindowCommand) - Text commands (
TextCommand)
When writing plugins, consider your goal and choose the appropriate type ofcommands for your plugin.
Shared Traits of Commands¶
All commands need to implement a .run() method in order to work. Additionally,they can receive an arbitrarily long number of keyword parameters.
Application Commands¶
Application commands derive from sublime_plugin.ApplicationCommand andcan be executed with sublime.run_command().
Window Commands¶
Window commands operate at the window level. This doesn't mean you can'tmanipulate views from window commands, but rather that you don't need viewsin order for window commands to be available. For instance, the built-incommand new_file is defined as a WindowCommand so it works, even when noview is open. Requiring a view to exist in that case wouldn't make sense.
Window command instances have a .window attribute to point to the windowinstance that created them.
The .run() method of a window command does not take any requiredarguments.
Text Commands¶
Text commands operate at the buffer level, so they require a buffer to existin order to be available.
Best Sublime Plugins
View command instances have a .view attribute pointing to the view instancethat created them.
The .run() method of a text command needs to accept an edit instance asthe first positional argument.
Text Commands and the edit Object¶
The edit object groups any modifications to the view so as to enable undo andmacros to work sensibly.
You are responsible for creating and closing edit objects. To doso, you can call view.begin_edit() and edit.end_edit().For convenience, the currently open edit object gets passed to textcommands' run method automatically.Additionally, many View methods require an edit object.
Responding to Events¶
Any command deriving from EventListener will be able to respond to events.
Another Plugin Example: Feeding the Completions List¶
Let's create a plugin that fetches data from Google's Autocomplete service and thenfeeds it to the Sublime Text 2 completions list. Please note that, as ideas forplugins go, this a very bad one.
Note
Make sure you don't keep this plugin around after trying it or it willinterfere with the autocompletion system.
See also
EventListener.on_query_completions()- Documentation on the API event used in this example.
Learning the API¶
In order to create plugins, you need to get acquainted with the Sublime TextAPI and the available commands. Documentation on both is scarce at the time ofthis writing, but you can read existing code and learn from it too. Inparticular, the Packages/Default Privately learn more. Battleship through imessage. folder contains many examples ofundocumented commands and API calls.
