Sublime Forum

API Suggestions


Last one for now…The ability to affect a single on_query_completions using flags. I would like to create a plugin that will display autocompletions without the in-file suggestions, but since these flags affect all instances of on_query_completions, this is not easily doable.




Find in Region by selectors

One thing I would really like to see would be the ability to do a view.find_in_region_by_selectors(region, [selector1, selector2]), which would essentially be an upgrade to the existing view.find_by_selector method, to include:

a. a region within which to restrict the results
b. an array of selectors

The result would of course be sorted by position, and could include the entire scope of the region, or just the selector that matched, like this:

[(region, scope/selector), (region, scope/selector)...]


Firstly, I know that having an array for multiple selectors may seem pointless, because a selector can include a comma to perform an “or”. i.e. string, comment.
But the problem with this, is that, if the text matching the selectors are adjacent, the region returned will include all of them, and most of the time, it is much more useful to have them separate.


take a python file containing:

"hello world"#comment
"foobar" # another comment

using the following code:

[view.substr(region) for region in view.find_by_selector('string, comment')]

will return the following:

[’“hello world”#comment\n"foobar"’, ‘# another comment’]

Now, imagine that one wants to know the location of all the comments in the file and all the strings in the file, while preserving the order. With the current API, the “most efficient” workaround is to do this (view.substr is just for demonstration of what gets returned):

[view.substr(region) for region in sorted(view.find_by_selector('string') + view.find_by_selector('comment'))]

[’“hello world”’, ‘#comment\n’, ‘“foobar”’, ‘# another comment’]

which involves sorting a potentially incredibly massive list.

Now this is where the proposed region restriction comes in handy. Most of the time when I am developing plugins, I am only interested in a small subset of the file/view at a time, and I feel that being able to get results only for a particular region will make the plugin code easier to read/understand and write, while at the same time being more efficient. (Even if the same process would have to happen in the C code, it would be a lot quicker than processing it in Python I think.)

Importance: Minor

One possibility would be to alter the find_by_selector method, to include the new functionality, in such a way as not to affect existing plugins that rely on the current behavior:

  • make the region parameter optional (and come after the selector), and default to the entire view if None
  • if the selector parameter is a string, use the current functionality and return type (list of regions)
  • if the selector parameter is an array, return the list of tuples, where each tuple would contain the region and the scope of that region or the selector that matched.

I guess if multiple selectors matched, and the API would return the matching selector(s) as opposed to the scope at the region, then the return value of the matched selectors could be a list, to avoid repeating the region in the return value. i.e.:

[(region1, [selector1, selector2]), (region2, [selector1])...]

instead of:

[(region1, selector1), (region1, selector2), (region2, selector1)...]

find_by_selector and nested scopes

Sets of APIs to Improve one aspect of the performance of ST:

  1. application does not trigger “on load” when the app is opened. This means, that any package that needs that event should trigger it in a synthetic way. So imagine many packages doing this…
  2. application does not have “on application close”, so if you need to save to disk some data related to the views you have opened you need workarounds, like on_deactivated. So we hitting hard drive on every focus lost… because there’s no reliable way to save data about the views; and this workaround is not even reliable. [data that does not fit in ST view settings object, etc], imagine you need to save something to sqlite


All file events, give events for:

Any change on disk about a file/folder is created/changes/reloads/gets deleted, even if not opened. The current ugly hack is to recurse the folder till eternity.


Adding folder name completion and syntax highlighting to an existing plugin?

Dispatch events for when a view is scrolled, so we can for example scroll other unfocused views in relation to the current focused view. The current ugly hack is to loop forever and see if the scroll changed



This gonna be hard to explain and Im sorry, We need “light” versions of on_selection_modified and on_modified .

Because these two apis are too verbose and everyone use it wrong, Then later people complain ST lags, when they triggering heavy tasks on every key press or cursor move. Some people even believe they use it right because they move to threads, and actually this is worse, there’s no need to dispatch 30 gonna-be-useless threads because you hold a key to type or to move the cursor for a few seconds.

The current workaround for this is insane, you loop in a thread with while(True) and sleep, then try to check if the view/selection changed and also if it is worth to wait a bit more

I suggest something in the lines of ;

  1. on_after_selection_modified - event fires when the cursor stops moving for some given milliseconds
  2. on_after_modified - event fires when the user stops modifying the view for some given milliseconds

Interface Suggestions

This is a pretty curated list, and Im sure you will found some worth post, specially all of these related to bugs, ST API works most of the time but has some bugs that are really frustrating and defeats the purpose of having an api in the first place, because you need workarounds that does not couple correctly or does decouple with other functionality and everything becomes a workaround of a workaround to make things work.

This is the most important stuff. Current API should work, flawless, if does not because of some edge case, then explain it



Some APIs conflict with ST itself, for example, you have an API to scroll the view to a certain position, but you don’t have any way to stop ST Core from scrolling a view. So you start fighting and racing with ST to see which one will scroll a view. Defeats the purpose of the API because you cannot use it, sublime will simply overwrite it as it wish.

For an API to work correctly, every default behaviour of the editor should be configurable. There are many, many examples of this. For example imagine you want to run a task to all the file selected on sidebar, and you need to do this repetitively, well if you change of view, your selection on sidebar vanishes, hence an API to get the current selection of files gonna be useless for a lot of cases. Want another example? on_close is not dispatched if you switch projects

1 Like


This is more a dream than anything else, it would be nice to have “linked regions”, regions that are foreign to the current document, this will allow to change for example more than one file from the same view.

Something like this, I did on package FindResultsApplyChanges

Basically you can edit the view of the find results directly and then press CTRL+S to save the changes you did to the different files

The possibilities of this are out of my imagination


split this topic #51

A post was merged into an existing topic: Interface Suggestions



Possibly an API to expose the fussy match logic that Sublime has implemented such that we could apply the matching algorithm to a list of strings or list of objects.

sublime.fuzzy_match(list, match_string, key)

  • list: list to apply the matching against
  • match_string: used to match against
  • key: A key to be used if supplying a list of objects or tuples.

Not sure if anyone would find this helpful or not, but there have been some cases where I want to apply the fuzzy matching against a list of items without using one of the built in panels.



Add to this settings too:

"minimap": true,
"status_bar": true,
"tabs": true
1 Like

Custom Key Bindings -- syntax and conventions for sorting lines

Placeholder for fold

Importance: Minor
Description: Add an optional placeholder argument to the fold function, i.e. change the signature to fold(regions, <placeholder>) and fold([regions], <placeholder>). If the function is executed the placeholder text is inside the yellow rectangle instead of the 3 dots.
In addition add a function is_folded(point), which returns whether a point is currently folded.
Motivation: This could be used to fold redundant and unnecessary code away to improve readability while keeping the key information. E.g. fold all function keywords in JavaScript to f or python lambda: to λ. In LaTeX it could be used to fold labels to l and greek characters and some operators to their unicode character, e.g. \alpha to α.


Looking for an orgmode like link presentation

Directly accept colors in add_regions

Importance: Major
Description: Change the add_regions method to accept rgb encoded colors. The function add_regions(key, [regions], <scope>, <icon>, <flags>) currently only accepts a scope and retrieves the color from the colorscheme. It would be nice, if it was possible to pass rbg encoded colors as an argument. This could either be done by changing the signature to accept an additional keyword argument <color> or by adding a flag sublime.SCOPE_IS_COLOR to treat the scope as a color.
Motivation: When creating a highlighted region one often just wants to define the color itself instead of a scope with a similar color.
At the moment some packages (e.g. SublimeLinter and ColorHighlighter) even change the colorscheme of the user to inject their colors. This has some disadvantages for the user and does not scale as a general solution.


Interface Suggestions

Query contexts

A way to query a view for certain contexts. Much like a keybinding does, but within a plugin, to make the code easier to follow without reinventing the wheel. i.e. it would execute any on_query_context EventListeners behind the scenes.

view.query_context(key, operator, operand, match_all)

(maybe also include a region or point?)

operator is one of:

  • sublime.OP_EQUAL. Is the value of the context equal to the operand?
  • sublime.OP_NOT_EQUAL. Is the value of the context not equal to the operand?
  • sublime.OP_REGEX_MATCH. Does the value of the context match the regex given in operand?
  • sublime.OP_NOT_REGEX_MATCH. Does the value of the context not match the regex given in operand?
  • sublime.OP_REGEX_CONTAINS. Does the value of the context contain a substring matching the regex given in operand?
  • sublime.OP_NOT_REGEX_CONTAINS. Does the value of the context not contain a substring matching the regex given in operand?

match_all should be used if the context relates to the selections: does every selection have to match (match_all = True), or is at least one matching enough (match_all = False)?

Importance: Major

One potential advantage of this would be the ability to use PCRE flavor RegEx expressions instead of Python ones from within a plugin, which support a few extra features (like recursion).


Interface Suggestions
[test]: simulate key press
Programmatic way to query context

Importance: Somewhat

Description: A hook for when text is about to be self-inserted, and a hook for when a key is pressed for which there is no key binding.

Motivation: There are no hooks for telling when text has been inserted. Therefore a number of things are not possible, including “inserting the same character N times” ala Emacs.

Having a hook called when there’s no binding for a key would allow us to implement ^Q which would insert the character that is normally bound to another command.

1 Like

Interface Suggestions

Importance: Medium

Description: Make it possible to close a view on a modified file without requiring confirmation iff that same file is displayed in at least one other view.

Today if you split the window and and view the same file, and you want to close the window without saving, you are bothered with the confirmation even though there’s another view still open on the file.



Test coverage reports for sublime syntax files

Mentioned by @FichteFoll here:

1 Like

Interface Suggestions

Add an EventListener callback that is run whenever a project changes or is opened.

Scale: Minor

class MyProjectChangeListener extends sublime_plugin.EventListener:
  def on_project_changed(self, window, new_project_data):
  """ Called when the current project data changes. """


Prompt Open Recent Project