API Suggestions

[wbond]

In an attempt to get some up-to-date info, and ideally a centralized list with feedback from other users, I’m interested in hearing what package developers would like to see in terms of API enhancements.

Ground rules:

• One API enhancement, or a single set of cohesive functions/endpoints per post. This allows people to Like specific ideas.
• Concrete ideas for the API, such as what you would expect the endpoint to accept/return, or what the implementation would do
• No high-level/abstract ideas such as “flexible GUI system”, “HTML/CSS styling”, “better gutter tools”, “a sidebar API”. This is so everyone can better understand what exactly you feel is missing, or needs to be tweaked. In some cases, it will make you think about how you’d like something to work. For instance, a “sidebar API” means different things to different people.
• Use the Like functionality on any suggestion you think you would actually use for a package you would like to build, or have already built
• For your own usage, please rate the importance of this addition/change on the following scale: Trivial, Minor, Major
• Discuss ideas further by creating a linked topic

I sincerely appreciate the time and effort that I’m sure many of you will put into this. I will be splitting off interface suggestions to a separate topic. I will also move discussion of ideas to linked topics.

So, what changes would you like to see made to the API?

[wbond]

14 posts were merged into an existing topic: Interface Suggestions

[rppn]

sublime.open_readonly_package_resource('package', 'path/to/file.ext')

opens a read-only view in a new tab of path/to/file.ext of package package

---

Taking that back: This works as explained below by jps and fichtefoll.

[noreffer]

API to create custom user menu or toolbar with icons ( I describe it here: Add functionality to create custom user toolbar )

[rppn]

sublime.window.is_minimap_visible()
sublime.window.is_status_bar_visible()
sublime.window.is_tabs_visible()

suggested by @aziz in this post in the Build 3098 feedback thread

---

• Major for me personally, as I’m working with the DistractionFreeWindow plugin almost all the time.
• Implementation would be easy, could remove lots of (then) unnecessary plugin work-arounds.

[noreffer]

Extension API for tooltip / popup - to get more advanced tooltip like in other editors ( example: https://github.com/ternjs/tern_for_sublime/issues/85 )

Sublime Text have very weak system of prompting / autocomplete / hints.
For example:
Hints in Brackets (with Ternific extension)

Hints in Atom (without any extension)

The hint in Brackets / Atom display some usefull information like an type, parameters, returns, descriptions, url to documentation
I think that is one of the things, that most missing in ST, especially for beginner developers

[jcberquist]

I would love to see on_query_completions allow for an on_highlighted/on_change callback function to be provided that would be called when the current selection in the completions menu changes. This would allow for more information to be provided regarding the current selection in an HTML popup alongside the completion menu.

To implement this I would envision allowing for returning a tuple from on_query_completions like so: (completions, flags, on_change), where the on_change callback would be called with the index of the completion in the corresponding completions list whenever an item in the overall completion list is highlighted that is from that set.

This might be really tricky to implement since there are potentially going to be many different sources/plugins providing completions via on_query_completions and the correct callback with the correct original index (since all the completions are aggregated into one list) would have to be called as the selection changes.

As far as rating this goes, I would say Minor since I would definitely use this, but the lack of it doesn’t prevent completion lists from being useful.

…As I was writing this I recalled this thread: Dev Build 3071. Based on that I guess the popup API is not supposed to be used as I just described, so alternately it would be nice to see the suggestion made there implemented:

Dev Build 3071

With regards to COOPERATE_WITH_AUTO_COMPLETE, the intention is that the popup is displaying information relevant to text in the buffer, not to the selected item in the auto complete window. e.g.,

foo(arg1, arg2|)

Auto complete would be showing completions for the current word, but the popup in this case could be displaying information about the parameters that foo accepts.

I’d like to provide a way for the AC popup to show extended information about the currently selected item, but it would work via a different mechanism than view.show_popup().

[wbond]

2 posts were split to a new topic: API Suggestion Discussion: open_readonly_package_resource

[jgbishop]

Having some control over windows that we create would be useful:

sublime.maximize_window(window_id)
sublime.restore_window(window_id)

I think these wouldn’t likely return anything, but if they absolutely had to, I guess they could return a boolean indicating success or not. This is of minor importance, but it would make the user experience for my Side-by-Side Settings plugin a little nicer.

[fico]

Add A “MenuText” Property To Snippets

Importance: Minor

 
Currently, snippets are displayed in the command palette either by their filename or, if provided, by their description property.

An issue with this is that the user has to choose between a description that is useful during auto-completion or one that is more suited to the command palette.

 
For example:  I have a set of Sublime Text API snippets.  I would like to be able to use description to provide information about the snippet - but a need that takes priority is the ability to easily filter groups of snippets via the command palette.  As such, my descriptions essentially mirrors the snippet’s contents with the addition of a contextual prefix.

This allows me to easily find a snippet via the command palette by typing Snippet: [Context], but it makes the auto-completion display cluttered & redundant:

 
If I were to use description for it’s intended purpose, I would lose the ability to contextually filter through snippets via the command palette:

[fico]

Window Relative Popups

Importance: Trivial

 
view.show_popup is currently displayed relative to the view. It would be useful to position popups in relation to the window for non-view related notifications.  ( EG: centered in the window )

 
For example, I have a Messenger module that displays notifications - one usage case of which is to inform users whether a toggle command has been enabled or disabled for a particular feature.

I currently position it with view.visible_region().a, but feel that notifications of this nature are more aesthetically suited to be window-centered ( much like the “Save Changes” dialog ), especially when multi-pane layouts are active.

[michalisb]

I dont know how useful that would be for others, but maybe the option to open a file into a buffer instead of a view - but still manipulate it in similar ways i.e apply a syntax, select regions, clasify, etc.

Or maybe it is opened in a view but the view not attached to any window?

[Clams]

##List of file indexed in the project

Importance: Major

Description: Basically give us access to the list of file that is displayed when pressing ctrl+P.

Motivation: Today I can only retrieve the project folder information and have to manually recreate the list of file of the project: this is very slow, and to be propose a responsive interface in my plugin I need to cache this information (with all the issue in maintaining an up-to-date list). This was already requested some month ago here by another user.

[Clams]

##Indexed symbol list in the project

Importance: Major

Description: Give access to the list of indexed symbols in the project which is displayed when pressing ctrl+shift+r. Result would be a tuple, similar to the result of window().lookup_symbol_in_index()

Motivation: Today there is two API (view.symbols() and indexed_symbols) which return more or less the same list of symbol in the current view, but there is noway to have access to all the symbol in the project.

[Clams]

##Scope information for indexed symbol

Importance: Major

Description: Add to the symbol list (from view.indexed_symbols() or the new one i’m requesting for the whole project) the associated syntax scope. The result would just an additional entry in the tupple which is returned today

Motivation: when displaying/iterating a list of symbol in a plugin it is quite often needed to get the information of the type of symbol since you won’t do the same kind of operation on a class or a function. It is possible to do this manually but it requires additional operation that seems unnecessary (since the scope is basically the reason why the symbol was indexed) and that can be too heavy to do, especially if we talk about the whole symbol list of a project.

[kingkeith]

log_commands - show the path to where the command is defined

I would love it if sublime.log_commands(True) would also show where the commands being executed are defined - i.e. WindowCommand: "Packages/Default/auto_indent_tag.py" for auto_indent_tag or "built-in Sublime Text WindowCommand" for commands that are built in to ST3 and not defined in a package.
This would also benefit end-users I believe, not just package developers.

Importance: Minor

[kingkeith]

A way to tell programmatically when a TextCommand / WindowCommand / ApplicationCommand is visible or enabled.

Maybe something like view.get_command_availability(command_name), returning { 'visible': True, 'enabled': False }, after executing the appropriate command’s is_enabled and is_visible methods. Currently, these methods only seem to be used when the command is part of a menu or the Command Palette, and AFAIK, can’t be accessed by a plugin directly.

Importance: Trivial

[gwenzek]

Allow to change the color of a file in the sidebar

Importance: major
Description: each file in the side bar could have is font color changed. The Api could be something like:

sublime.sidebar.get_entry_color(filename)
sublime.sidebar.set_entry_color(filename, color)

Or a more pythonic interface with a dict-like syntax.

Motivation: it will allow to improve source control integration.

[Clams]

##Access to Find in files result

Importance: minor

Description: the equivalent to “Find in files” (with the exact same arguments) that would return the result in a dictionnary instead of displaying the result in a buffer

Motivation: The “Find in files” of ST is extremely fast compare to doing an equivalent search in python, this would boost significantly the performances of some plugin. My personnal use case is trying to display a hierarchy of object and this requires looking in many files with some regexp.

[greg_hoch]

Modifier keys for different actions in the Quick Panel

Importance: minor
Description: Currently, sublime.Window.show_quick_panel takes an argument on_done, which will be called once with the index of the selected item. I suggest that show_quick_panel accepts multiple callback functions for different modifier keys. The current on_done would be the default but would also accept different callbacks that are called when the user is holding down control, option, or command. With these additional callbacks, the user could perform a range of different actions with the same items in the quickpanel. Alfred App does that.