Sublime Forum

API Suggestions


I would also like the option of hiding some of the statuses that are managed by sublime or even other packages.

Sometimes the default information from sublime is redundant to something your own plugin needs to display, in my case, an emacs-like incremental search package. If I could enumerate the existing status keys and hide them, perhaps for the duration of an input panel’s visibility or something like that.



I would like to see an API to initialize settings in the find/replace forms.

window.find_in_files.add_directory( myParentDirectory() )

so that I could write macros/plugins to set up commonly used searches and then use normal find next/find prev/find all commands to process them with existing commands.

or maybe a way to set up search/replace snippets collection.



No the goal is not to completely define a command’s key mapping within a plugin. The goal is remove plugin boilerplate, complexity, duplication, and performance footprint. I’ve update the post with extra details about motivation. I’ve removed the suggestion about defining the keys within the command itself, because I agree the keys should still be defined in the keymaps file.



on_close event listeners should be able to abort the close action

Importance: Medium

Use case: a plugin may be managing a view with special functionality.
The view may even be set as scratch but contain information edited by the user.
The plugin should be able to detect the on_close event of such view and ask the user what to do with any un-committed changes.
A dialog can be displayed but a “Cancel” option cannot be currently cleanly implemented.

(Think of a thin client of some web API: edits may need to be uploaded to be saved)


pinned globally #86


Addition to this: would also be useful for on_save/on_pre_save to prevent saving actions.

Github issue:



Easy way to set contents of a view

Importance: Low (because of the easy workarounds)

Currently, many plugins define simple TextCommands just to set the text of a view to precisely the contents of a string.
This duplication exists because the commands defined by ST do not handle new lines nicely, always trying to be too smart with indentation.



API for transient/image views

Importance: Medium

See related post.

1 Like


I would classify this as a bug, honestly. Maybe the commands should receive a few arguments that enable or disable this auto-indentation, but I agree that it’s very annoying. You always have to disable the setting before adding content to a view.

1 Like


More general sublime.find_resources

Importance: Medium

Use cases: you want to find a settings/keymap/sublime resource file, using the same “path-resolution” strategy that ST uses internally.
For example, you may want to examine the settings for Ruby files, which may be overwritten in many places such as your User folder.
An advantage of having an API for this is that if the mechanism changes in ST, the plugins would still pick up the right file.

Secondly, find_resources should also work with fully specified paths or patterns including folders.



Getting the syntax file from extension/scope

Importance: Medium

Use case:
Different users may have installed different custom/plugin syntaxes for some file types.
Suppose your plugin wants to display some information in Markdown in a custom view.
Which syntax do you set? Ideally you want to ask ST to set the syntax to whichever syntax the user set for Markdown.



Get the entire contents of a view as a string

class View(object):
    def to_str(self):
        return self.view.substr(sublime.Region(0, self.view.size()))

Importance Low

Motivation Removes boilerplate and complexity



This would remove such boilerplate as the following which should be an unnecessary command:

class __plugin_name_view_replace(sublime_plugin.TextCommand):

    def run(self, edit, text):
        self.view.replace(edit, sublime.Region(0, self.view.size()), text)
1 Like


Testing colour schemes

re: Testing color schemes

COLOR_SCHEME_TEST "color_scheme_name"

SYNTAX "source.php"
$variable = true;
//          ^^^^ fg=#xxxxxx bg=#xxxxxx font=name font_style=none

variable = True;
//         ^^^^ fg=#xxxxxx bg=#xxxxxx font=name font_style=none

 // ...

Importance High, because it will improve the quality of colour schemes greatly. And has the side-effect of improving syntaxes by way of bug reports by colour scheme developers.
Motivation Helps with creating robust colour schemes.



Native dialogs for getExistingFileDialog(iniDir,extensions), getExistingDirectoryDialog(iniDir), etc. With help from the forum I have a plugin that does this (but it’s a bit clunky). Also GetColorDialog(initial) (currently a plugin which starts an external .exe) etc.

This was meant as an API suggestion. I would like my plugin to be able to ask the user for the name of an existing directory.or file. I didn’t mean, for instance, that I want file>open on the menu to open a particular kind of native dialog


myDirectory = path_to_current_file()   
deliverydir = window.getExistingDirectory( myDirectory )    #  API Call
if not deliveryDir is None: 
   defaultDest[myDirectory]  = deliveryDir

I wrote a plugin to map SQL files from different parts of my source tree to another tree of files that need to be delivered to a customer. The plugin has commands to:

  • Copy the current file to a subdirectory of my delivery tree.
    • If the base of the delivery tree has not been identifed, allow the user to locate/create a base directory whose name is then saved in my project settings.
    • If a file has already been copied from the same directory, add it to the same delivery sub-dir
      • otherwise allow the user to create a new subdir in the delivery tree (starting from the base)
  • Add a line to my install.sql each time a new file is coped
  • Check that all my delivered files are up to date etc.

ETA: fixed error in example code, The code is still not technically correct

1 Like


importance: minor/“fringe”

syntax.html gives an example of a PHP heredoc in which the end of the heredoc is matched using
-match: ^\1

\1 used to match a previously captured pattern.

I tried to do something similar in order to set a scope name according to a previously matched pattern

- match: "^\\s*([a-z.]+): .* // (.*)"
    2: \1

the idea was to have a custom syntax for a .myScheme file (from which a standard tmScheme file would be generated), The source would preview itself in the comments.::

markup.deleted:   #a1000d        
meta.diff.header: #ffffff/#4e738a  // --- D:\st3portable\Data\Packages\MyScheme\x.txt
meta.diff.range:  #888888 <i>      // @@ -34,6 +34,5 @@

The first // comment would have scope name meta.diff.header and be shown as white text on a different background and the second comment would have scope meta.diff.range and text shown in grey italics.

(BTW: my suggestion is that \1 etc be allowed in the captures: list, unless it would open up a horrible can of worms)

ETA: I just noticed the suggestion for a YAML based format for tmscheme which would make my plugin immediately redundant. However maybe the YAML-solution could benefit from such a change.



Introduce new optional parameter in run_command() method:

def run_command(command_name, cmd_params, lock=None)):

It would be wonderful if commands executed witch run_command could be synchronized by use of threading.Lock.



API Suggestions Discussion: locks for run_command

I would like to see a Block Decorations API like Atom has:

The API could be as simple as this:

ref = view.add_block_decoration(after_line=12, html=html_string)

Presumably this could reuse the existing HTML library that is used for tooltips (with the same type of callbacks for links), but would display persistent but passive inline information between buffer lines.

This would be useful for extended linter information (instead of one line in the status bar), inline image previews, inline latex equation previews, inline documentation, ipython-notebook-style output, just to name a few off the top of my head. There is a lot of potential here and I’m sure people will come up with more ideas, so I would rate this as major.




As a sidenote to this - I have a plugin concept that could greatly benefit from this functionality.  The plugin essentially allows users to define arbitrary code folding points ( as opposed to the default indentation-based system ) by implementing headers, which they can also use to quickly fold/zoom code, open specific sections in new views, navigate sections via quickpanel, etc.

Here are a few other demos.

Some areas where I could see benefit would be - rather than headers occupying the same line-space as code, headers could be in non-code space like:

1> here is
2> some code
////////// This Is A Header /////////
3> here is some more code

I believe this would allow for faster performance by allowing headers to be queried solely within block decorations, rather than performing a RegEx search over the entirety of code.

Some implementations of block decorations that would be useful:

  • tag : used to quickly group all block decorations of a particular tag into an array via
    tagArray = view.get_decorations( "tagName" )

  • data{} : “hidden” dictionary to store associated content ( EG: in the case of my header example, "indentation_level": 3 could be a stored value )

  • callback : allows callbacks to be run upon clicking block decorations ( Some sort of method to differentiate left, right, & double clicks might be useful. Also, allow keybinding contexts to implement the tag property along with is_block_decoration )

  • decoration.begin() & decoration.end() : return the same results as their region counterparts

  • fold markers : allow text to be folded “into” block decorations manually ( +1 for automatic fold-regions in between decorations as an option )

1 Like


I agree it would be very useful to be able to ask the user for a path using the standard dialogs.
Right now we have very few options like using window.show_input_panel which requires the user to have copied the path by other means beforehand.

A simple API with callbacks would be just fine:

sublime.show_open_dialog(title:string, initial_path:string, open_dir:bool, on_done:callback, on_cancel:callback)
sublime.show_save_dialog(title:string, initial_path:string, on_done:callback, on_cancel:callback)