Plugin API Reference

Sublime API:

Plugin Base Classes:

Module sublime

MethodsReturn ValueDescription
setTimeout(callback, delay)noneCalls the given callback after the given delay (in milliseconds). Callbacks with an equal delay will be run in the order they were added. It is safe to call setTimeout from multiple threads.
statusMessage(string)noneSets the message that appears in the status bar.
errorMessage(string)noneDisplays an error dialog to the user.
messageBox(string)noneDisplays a message box to the user.
questionBox(string)boolDisplays a yes / no message box to the user, return True iff they selected yes.
options()OptionsReturns a reference to the application options.
windows()[Window]Returns a list of all the open windows.
activeWindow()WindowReturns the most recently used window.
runCommand(string, <args>)noneRuns the named ApplicationCommand with the (optional) given arguments.
canRunCommand(string, <args>)noneReturns True iff the command is enabled with the (optional) given arguments
makeCommand(string, <args>)StringBuilds a command string from a command name and arguments. This string is suitable to use as an argument to showCompletions().
packagesPath()StringReturns the base path to the packages.
installedPackagesPath()StringReturns the path where all the user's *.sublime-package files are.
getClipboard()StringReturns the contents of the clipboard.
setClipboard(string)noneSets the contents of the clipboard.
getMacro()[String]Returns the current macro. The macro is represented as a list of commands to run.
setMacro([string])noneSets the current macro.

Class sublime.View

Represents a view into a text buffer. Note that multiple views may refer to the same buffer, but they have their own unique selection and geometry.

MethodsReturn ValueDescription
id()intReturns a number that uniquely identifies this view.
bufferId()intReturns a number that uniquely identifies the buffer underlying this view.
fileName()StringThe full name file the file associated with the buffer, or None if it doesn't exist on disk.
name()StringThe name assigned to the buffer, if any
setName(name)noneAssigns a name to the buffer
isLoading()boolReturns true if the buffer is still loading from disk, and not ready for use.
isDirty()boolReturns true if there are any unsaved modifications to the buffer.
isReadOnly()boolReturns true if the buffer may not be modified.
setReadOnly(value)noneSets the read only property on the buffer.
isScratch()boolReturns true if the buffer is a scratch buffer. Scratch buffers never report as being dirty.
setScratch(value)noneSets the scratch property on the buffer.
options()OptionsReturns a reference to the file type options for the view.
window()WindowReturns a reference to the window containing the view.
runCommand(string, <args>)noneRuns the named TextCommand with the (optional) given arguments.
canRunCommand(string, <args>)noneReturns True iff the command is enabled with the (optional) given arguments
size()intReturns the number of character in the file.
substr(region)StringReturns the contents of the region as a string.
substr(point)StringReturns the character to the right of the point.
insert(point, string)intInserts the given string in the buffer at the specified point. Returns the number of characters inserted: this may be different if tabs are being translated into spaces in the current buffer.
erase(region)noneErases the contents of the region from the buffer.
replace(region, string)noneReplaces the contents of the region with the given string.
sel()RegionSetReturns a reference to the selection.
line(point)RegionReturns the line that contains the point.
line(region)RegionReturns a modified copy of region such that it starts at the beginning of a line, and ends at the end of a line. Note that it may span several lines.
fullLine(point)RegionAs line(), but the region includes the trailing newline character, if any.
fullLine(region)RegionAs line(), but the region includes the trailing newline character, if any.
lines(region)[Region]Returns a list of lines (in sorted order) intersecting the region.
splitByNewlines(region)[Region]Splits the region up such that each region returned exists on exactly one line.
word(point)RegionReturns the word that contains the point.
word(region)RegionReturns a modified copy of region such that it starts at the beginning of a word, and ends at the end of a word. Note that it may span several words.
find(pattern, fromPosition, <flags>)RegionReturns the first Region matching the regex pattern, starting from the given point, or None if it can't be found. The optional flags parameter may be sublime.LITERAL, sublime.IGNORECASE, or the two ORed together.
findAll(pattern, <flags>, <format>, <extractions>)[Region]Returns all (non-overlapping) regions matching the regex pattern. The optional flags parameter may be sublime.LITERAL, sublime.IGNORECASE, or the two ORed together. If a format string is given, then all matches will be formatted with the formatted string and placed into the extractions list.
rowcol(point)(int, int)Calculates the 0 based line and column numbers of the point.
textPoint(row, col)intCalculates the character offset of the given, 0 based, row and column. Note that 'col' is interpreted as the number of characters to advance past the beginning of the row.
extractScope(point)RegionReturns the extents of the syntax name assigned to the character at the given point.
syntaxName(point)StringReturns the syntax name assigned to the character at the given point.
matchSelector(point, selector)boolReturns True iff the selector matches the syntax name assigned to the character at the given point.
show(point, <showSurrounds>)noneScroll the view to show the given point.
show(region, <showSurrounds>)noneScroll the view to show the given region.
show(regionSet, <showSurrounds>)noneScroll the view to show the given regionSet.
visibleRegion()RegionReturns the currently visible area of the view.
extractCompletions(prefix, <point>)[String]Returns the completions for the given prefix, based on the contents of the buffer. Completions will be ordered by frequency, and distance from the given point, if supplied.
showCompletions(point, prefix, [completions])noneShows the autocomplete menu, at the given point, with the given completions. If an entry is selected, the given prefix will be replaced with the selected completion. Each completion may be either a string, or a tuple consisting of a description and a command to run.
addRegions(key, [regions], scope, <flags>)noneAdd a set of regions to the view. If a set of regions already exists with the given key, they'll be overwritten. The scope is used to source a color to draw the regions in, it should be the name of a scope, such as "comment" or "string". If the scope is empty, the regions won't be drawn.

The optional flags parameter is a bitwise combination of:

  • sublime.DRAW_EMPTY. Draw empty regions with a vertical bar. By default, they aren't drawn at all.
  • sublime.HIDE_ON_MINIMAP. Don't show the regions on the minimap.
  • sublime.DRAW_EMPTY_AS_OVERWRITE. Draw empty regions with a horizontal bar instead of a vertical one.
  • sublime.DRAW_OUTLINED. Draw regions as an outline, rather than filled in.
  • sublime.PERSISTENT. Save the regions in the session.
getRegions(key)[regions]Return the regions associated with the given key, if any
eraseRegions(key)noneRemoved the named regions
setStatus(key, value)noneAdds the status key to the view. The value will be displayed in the status bar, in a comma separated list of all status values, ordered by key. Setting the value to the empty string will clear the status.
getStatus(key)StringReturns the previously assigned value associated with the key, if any.
eraseStatus(key)noneClears the named status.

Class sublime.RegionSet

Maintains a set of Regions, ensuring that none overlap, and that they are kept in sorted order.

MethodsReturn ValueDescription
clear()noneRemoves all regions.
add(region)noneAdds the given region. It will be merged with any intersecting regions already contained within the set.
addAll(regionSet)noneAdds all regions in the given set.
subtract(region)noneSubtracts the region from all regions in the set.
contains(region)boolReturns true iff the given region is a subset.

Class sublime.Region

Represents an area of the buffer. Empty regions, where a == b are valid.

ConstructorsDescription
Region(a, b)Creates a Region with initial values a and b.
PropertiesTypeDescription
aintThe first end of the region.
bintThe second end of the region. May be less that a, in which case the region is a reversed one.
MethodsReturn ValueDescription
begin()intReturns the minimum of a and b.
end()intReturns the maximum of a and b.
size()intReturns the number of characters spanned by the region. Always >= 0.
empty()boolReturns true iff begin() == end().
cover(region)RegionReturns a Region spanning both this and the given regions.
intersection(region)RegionReturns the set intersection of the two regions.
intersects(region)boolReturns True iff this == region or both include one or more positions in common.
contains(region)boolReturns True iff the given region is a subset.
contains(point)boolReturns True iff begin() <= point <= end().

Class sublime.Window

MethodsReturn ValueDescription
id()intReturns a number that uniquely identifies this window.
newFile()ViewCreates a new file. The returned view will be empty, and its isLoaded method will return true.
openFile(filename, <row>, <col>)ViewOpens the named file, and returns the corresponding view. Row and col are optional and may be omitted. If the file is already opened, it will be brought to the front. Note that as file loading is asynchronous, operations on the returned view won't be possible until its isLoading method returns false.
activeView()ViewReturns the currently edited view.
activeViewInGroup(groupIdx)ViewReturns the active view in the given group.
views()[View]Returns a list of all the views in the current window.
viewsInGroup(groupIdx)[View]Returns a list of all the views in given group.
focusView(view)noneFocuses the given view.
numGroups()intReturns the number of view groups in the window.
activeGroup()intReturns the index of the currently selected group.
getViewPosition(view)groupIdx, viewIdxReturns the group, and the index within the group, of the given view.
setViewPosition(view, groupIdx, viewIdx)noneMoves the view to to the given group and index within the group.
runCommand(string, <args>)noneRuns the named WindowCommand with the (optional) given arguments.
canRunCommand(string, <args>)noneReturns True iff the command is enabled with the (optional) given arguments
isFullScreen()boolReturns true of the Window is currently in full screen mode.
showQuickPanel(key, command, args, <displayArgs>, <flags>)noneShows the quick panel, populated with displayArgs. When an entry is selected, the command is run, with the arg corresponding to the selected display arg as a parameter. key should be used if updating the list asynchronously, or left blank otherwise.

displayArgs is optional, and will default to the list given for args.

The optional flags parameter is a bitwise combination of:

  • sublime.QUICK_PANEL_FILES. Indicates that the args correspond to file names, which changes how they're drawn.
  • sublime.QUICK_PANEL_MULTI_SELECT. Enables Ctrl+Enter to select all displayed items in the quick panel, up to a maximum of 16.
  • sublime.QUICK_PANEL_NO_MULTI_SELECT_SAFETY_CHECK. Used in conjunction with the above, removes the 16 item limit.
  • sublime.QUICK_PANEL_UPDATE_ONLY. When asynchronously updating the panel, ignore the update call if the panel has been closed.
  • sublime.QUICK_PANEL_MONOSPACE_FONT. Use a monospace font to draw the quick panel.
showSelectPanel(displayArgs, onSelect, onCancel, flags, <key>, <selectedIndex>)noneShows the quick panel, populated with displayArgs.

onSelect will be run for each item selected, with the index of the item passed in as a parameter.

onCancel will be run if the panel is closed without any items being selected.

The flags parameter should be 0, or a bitwise combination of:

  • sublime.SELECT_PANEL_FILES. Indicates that the args correspond to file names, which changes how they're drawn.
  • sublime.SELECT_PANEL_MULTI_SELECT. Enables Ctrl+Enter to select all displayed items in the quick panel, up to a maximum of 16.
  • sublime.SELECT_PANEL_NO_MULTI_SELECT_SAFETY_CHECK. Used in conjunction with the above, removes the 16 item limit.
  • sublime.SELECT_PANEL_UPDATE_ONLY. When asynchronously updating the panel, ignore the update call if the panel has been closed.
  • sublime.SELECT_PANEL_MONOSPACE_FONT. Use a monospace font to draw the quick panel.

key should be used if updating the list asynchronously, or left blank otherwise.

selectedIndex should be the index of the item to be initially selected, or omitted otherwise.

showInputPanel(caption, initialText, onDone, onChange, onCancel)ViewShows the input panel, to collect a line of input from the user. onDone and onChange, if not None, should both be functions that expect a single string argument. onCancel should be a function that expects no arguments. The view used for the input widget is returned.
renderer()StringReturns the name of the active Renderer, either "DirectX", or "OpenGL".
hwnd()HWNDReturns the win32 window handle for the window.

Class sublime.Options

MethodsReturn ValueDescription
getString(name)StringReturns the string value of the named option.
get(name)valueReturns the named option as the appropriate type.
get(name, default)valueReturns the named option as the appropriate type, or default if it's not defined.
set(name, value)noneSets the named option. Only primitive types are accepted.
erase(name)noneRemoves the named option. Does not remove it from any parent Options.
has(name)boolReturns true iff the named option exists in this set of Options or one of its parents.

Module sublimeplugin

MethodsReturn ValueDescription
(no methods)

Class sublimeplugin.Plugin

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.

MethodsReturn ValueDescription
onNew(view)noneCalled when a new buffer is created.
onClone(view)noneCalled when a view is cloned from an existing one.
onLoad(view)noneCalled when the file is finished loading.
onClose(view)noneCalled when a view is closed (note, there may still be other views into the same buffer).
onPreSave(view)noneCalled just before a view is saved.
onPostSave(view)noneCalled after a view has been saved.
onModified(view)noneCalled after changes have been made to a view.
onSelectionModified(view)noneCalled after the selection has been modified in a view.
onActivated(view)noneCalled when a view gains input focus.
onProjectLoad(window)noneCalled after a project has been loaded.
onProjectClose(window)noneCalled after a project has been closed.
onQueryContext(view, key, value)bool or noneCalled 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.

Class sublimeplugin.ApplicationCommand(Plugin)

MethodsReturn ValueDescription
run(args)noneCalled when the command is run.
isEnabled(args)boolReturns true if the command is able to be run at this time. The default implementation simply always returns True.

Class sublimeplugin.WindowCommand(Plugin)

MethodsReturn ValueDescription
run(window, args)noneCalled when the command is run.
isEnabled(window, args)boolReturns true if the command is able to be run at this time. The default implementation simply always returns True.

Class sublimeplugin.TextCommand(Plugin)

MethodsReturn ValueDescription
run(view, args)noneCalled when the command is run.
isEnabled(view, args)boolReturns true if the command is able to be run at this time. The default implementation simply always returns True.