Python API¶
Warning
Development of Sublime Text has moved on to version 3.
As a result,
this branch for Sublime Text 2
will not be updated any more.
Please select the latest
branch
in the panel on the bottom left
and consider updating Sublime Text.
See also
- Official Documentation for Sublime Text 2
- API documentation.
- Official Documentation for Sublime Text 3
- API documentation.
Missing in the official docs¶
This section tries to address missing topics in the official documentation.
sublime
module¶
-
class
sublime.
Window
¶ This class represents windows in Sublime Text and provides an interface of methods to interact with them. For all available methods, see the official documentation.
-
set_layout
(layout)¶ Changes the group layout of the current window.
Expects a dictionary like this:
{"cols": [float], "rows": [float], "cells": [[int]]}
where
[type]
represents a list of type.- cols
- A list of the column seperators (float), should start with
0
(left) and end with1
(right). - rows
- A list of the row seperators (float), should start with
0
(top) and end with1
(bottom). - cells
A list of cell lists which describe a cell’s boundaries each. Cells can be imagines as rectangles with the rows and cols specified along in this dictionary. Think like this:
[x1, y1, x2, y2]
where all values are integers respectively and map to the cols and rows indices. Thus, a cell with
[0, 0, 1, 2]
translates to a cell from the top left to the first column and the second row separator (in a 2x2 grid this would be bottom center).
Note
rows and cols are not tested for boundaries. Thus, even though it makes zero sense to have a values lower than
0
or higher than1
it is possible to specify them and Sublime Text will in fact treat them accordingly. Furthermore, it is possible to have the first value not be0
and the last not be1
, the remaining space will simply be black in this case. Don’t try this at home!Examples:
# A 2-column layout with a separator in the middle window.set_layout({ "cols": [0, 0.5, 1], "rows": [0, 1], "cells": [[0, 0, 1, 1], [1, 0, 2, 1]] })
# A 2x2 grid layout with all separators in the middle window.set_layout({ "cols": [0, 0.5, 1], "rows": [0, 0.5, 1], "cells": [[0, 0, 1, 1], [1, 0, 2, 1], [0, 1, 1, 2], [1, 1, 2, 2]] })
# A 2-column layout with the seperator in the middle and the right # column being split in half window.set_layout({ "cols": [0, 0.5, 1], "rows": [0, 0.5, 1], "cells": [[0, 0, 1, 2], [1, 0, 2, 1], [1, 1, 2, 2]] })
-
-
class
sublime.
View
¶ Similar to
Window
, this class represents views in Sublime Text and provides an interface of methods to interact with them. For all available methods, see the official documentation.-
match_selector
(point, selector)¶ Matches the scope at
point
against the specifiedselector
.Equivalent to:
view.score_selector(point, selector) != 0
or:
sublime.score_selector(view.scope_name(point), selector) != 0
-
sublime_plugin
module¶
-
class
sublime_plugin.
EventListener
¶ A wrapper class for events. Subclass and define the methods you want to receive events on and you are done, no registering necessary.
-
on_query_completions
(view, prefix, locations)¶ Called whenever the completion list is requested.
This accounts for all views and all windows, so in order to provide syntax-specific completions you should test the current scope of
locations
withmatch_selector()
.- view
- A
View
instance for which the completions should be made. - prefix
- The text entered so far. This is only until the next word separator.
- locations
Array of points in
view
where the completion should be inserted. This can be interpreted as the current selection.If you want to handle completions that depend on word separator characters you need to test each location individually. See Completions with multiple cursors on how Sublime Text handles completions with multiple cursors.
- Return value
Expects two (three) formats for return values:
[[trigger, contents], ...]
A list of completions similar to Trigger-based Completions but without mapping keys. trigger may use the
\\t
description syntax.Note: In Sublime Text 3, completions may also consist of plain strings instead of the trigger-contents-list.
([[trigger, contents], ...], flags)
Basically the same as above but wrapped in a 2-sized tuple. The second element, the flags, may be a bitwise OR combination of these flags:
sublime.INHIBIT_WORD_COMPLETIONS
Prevents Sublime Text from adding its word completions to the completion list after all plugins have been processed.
sublime.INHIBIT_EXPLICIT_COMPLETIONS
XXX What does this do?
Flags are shared among all completions, once set by one plugin you can not revert them.
Anything else (e.g.
None
)No effect.
- Example:
- See Another Plugin Example: Feeding the Completions List for an example on how to use this event.
-
Exploring the API¶
A quick way to see the API in action:
- Add
Packages/Default
(Preferences | Browse Packages…) to your project. Ctrl + Shift + F
- Enter
*.py
in the In Files: field - Check
Use Buffer
option - Search API name
F4
- Study relevant source code