Sublime Forum

**wbond** · June 8, 2016, 8:39pm

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

**FichteFoll** · June 7, 2016, 1:51am

Better control over the status bar

Importance: minor

Description: More control over the status bar in the API (and UI).

Motivation: A recurring use case is the permanent display of information about the current view (or project), but it hard to find a specific status bar section sometimes. Additionally, some status bar info could use a feature to display more information or present the user with a list of options he can take (i.e. display a context menu)

Details:

It should be possible to:

make status bar sections have a distinct and rearrangable section (drag with mouse). I’d like the “line x, column y” section to always be at the most left, for example, and the current git branch could move to the right next to encoding and line endings.
define a callback for status bar entries that is called when they are clicked (left mouse button). Linters could display a list of the current errors with this, for example.
define a context menu to be opened if the section is right-clicked. This could be a resource path to some .sublime-menu file. (I’ll make a suggestion for dynamic menus next.)

With the above, one could emulate all the current status-bar sections (on the right side) with just plugin code, except for syntax selection.

API:

view.set_status(...)
window.set_status(...)
sublime.set_status(key, text, on_click=None, 
                   menu="Packages/Default/Indentation.sublime-menu")
# view, window and sublime define the section's visibility
# 
# - key and text remain as they are currently
# - on_click: called when clicked
# - menu: resource path to a menu file that will be shown when right-clicked

On github: #15

**FichteFoll** · June 7, 2016, 12:47am

Dynamic menu items

Importance: minor

Description: Fill a menu with items that are generated on the fly by plugins, like the syntax or color scheme selection, or recent files/projects in the main menu.

Motivation: Many plugins would like to add items to a menu dynamically, which is the only thing you can’t do with menus right now.

Details:

In a .sublime-menu file, you provide a { "source": "key" } entry for a menu item. If a menu is to be displayed with an entry like this, ST would go through all EventListeners and call their on_query_menu callback with the value of "source" as the first parameter, similar to completions. Plugins would then be able to provide a list of menu items of the same structure as in .sublime-menu files, including the ability to define more { "source": "key" } items.

Alternatively, the { "command": "$key" } syntax, as found in Main.sublime-menu, could be used.

Example:

Main.sublime-menu

[
    {
        "id": "preferences",
        "children": [
            {
                "caption": "Theme",
                "children": [
                    { "source": "my_menu" }
                ]
            }
        ]
    }
]

some.py

class MenuExpander(sublime_plugin.EventListener):
    def on_query_menu(self, key):
        if key != "my_menu":
            return
        theme_files = sublime.find_resources("*.sublime-theme")
        theme_names = set(path.rpartition("/")[2] for path in theme_files)
        
        return [{"command": "set_theme", "args": {"name": name}}
                for name in sorted(theme_names)]

class SetThemeCommand(sublime_plugin.ApplicationCommand):
    def description(self, name):
        return name
    
    def run(self, name):
        prefs = sublime.load_settings("Preferences.sublime-settings")
        prefs.set("theme", name)
        sublime.save_settings("Preferences.sublime-settings")

**FichteFoll** · June 7, 2016, 12:59am

Find out where a setting value in view.settings() was defined

Importance: minor

Description: Find out where a value in view.settings() was defined. Could also be useful for any other settings object returned by sublime.load_settings(...).

Motivation: There are a lot of places where a setting can be defined (Preferences.sublime-settings (default, user, any other package…), project, syntax.sublime-settings (also multiple possible), view) and this is specifically important when you need to know whether you are overriding a view-specific setting and whether you should re-set its old value or erase your custom setting to not make the value stick.
It would also help with debugging.

API:

source = view.settings().get_source(key)
# returns a string that could be a resource path or `"project"` or `"view"`

Corresponding github issues: #1003, #907

**FichteFoll** · June 7, 2016, 1:32am

Distinguish view types and get handles of special views

Importance: trivial

Description: Several API hooks get called for all view types, including the console input and output, quick panels, input panels, find panels, goto anything … There is view.settings().get('is_widget'), but it’s not documented and not a nice API.

Motivation: A way to distiguish these panels would be nice for fine-grained features such as providing completions and a properly documented API would certainly help with discoverability.

Snippets In on_query_completions

Importance: Major

Another set of bugs that affect the existing API are:

Completion triggers with characters not in [a-zA-Z0-9_-] prevent buffer completions
on_query_completions fails to return custom completions when some characters are used

I currently have an auto-completion plugin that’s about 80% done, which will allow users and developers to easily define context-sensitive completions via YAML files. The macro-contexts are scope & location, and there is a micro-context that parses the current line’s text to allow nested completions.

Here is an example of a .custom-completions file that would add Sublime Text API completions only to python files contained within /Packages/. It works great, with the exception that all buffer completions are overridden as mentioned in the issues above ( if certain snippet-particular characters are used ).

#▓▓▓▓▓║     Settings     ║▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓

completionTrigger: "."

trailing_WhiteSpace_Enabled: false

scopeSelectors: [ "source.python" ]

locationContext_Mode: "Paths_StartWith"
locationContext_RegEx_Enabled: true
locationContexts: [ "(.*)(\\\\Sublime Text 3\\\\Packages\\\\)" ]

#▓▓▓▓▓║     completionSets     ║▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓

completionSets:

	view:
		sel:                 "sel()"
		line( point ):       "line( ${1:__INTEGER__Point__} )"
		line( region ):      "line( ${1:__REGION__} )"
		full_line( point ):  "full_line( ${1:__INTEGER__Point__} )"
		full_line( region ): "full_line( ${1:__REGION__} )"
		lines:               "lines( ${1:__REGION__} )"
		split_by_newlines:   "split_by_newlines( ${1:__REGION__} )"
		word( point ):       "word( ${1:__INTEGER__Point__} )"
		word( region ):      "word( ${1:__REGION__} )"

	window:
		id:                   "id()"
		new_file:             "new_file()"
		open_file:            "open_file( ${1:__STRING__File__}, ${2:»__FLAGS__} )"
		find_open_file:       "find_open_file( ${1:__STRING__File__} )"
		active_view:          "active_view()"
		active_view_in_group: "active_view_in_group( ${1:__INTEGER__GroupNumber__} )"
		views:                "views()"
		views_in_group:       "views_in_group( ${1:__INTEGER__GroupNumber__} )"
		num_groups:           "num_groups()"
		active_group:         "active_group()"
		focus_group:          "focus_group( ${1:__INTEGER__GroupNumber__} )"
		focus_view:           "focus_view( ${1:__VIEW__} )"

**canoeberry** · June 7, 2016, 9:05am

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.

**steveh4133** · June 7, 2016, 8:52pm

I would like to see an API to initialize settings in the find/replace forms.
eg.:
window.find.setRegex(true)
window.find.setFind("([0-9]{2}),([0-9]{2}),([0-9]{4})")
window.find.setReplace("\2.\1.\3")

window.find_in_files.add_directory( myParentDirectory() )
window.find_in_files.exclude_directory("./OLDFILES/./")

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.

**gerry** · June 8, 2016, 10:39am

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.

**bordaigorl** · June 8, 2016, 3:17pm

`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)

**wbond** · June 8, 2016, 8:58pm

**FichteFoll** · June 9, 2016, 2:39am

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

Github issue: https://github.com/SublimeTextIssues/Core/issues/821

**bordaigorl** · June 9, 2016, 10:25am

Easy way to set contents of a view

Importance: Low (because of the easy workarounds)

Description:
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.

**bordaigorl** · June 9, 2016, 1:31pm

API for transient/image views

Importance: Medium

See related post.

**FichteFoll** · June 9, 2016, 1:38pm

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.

**bordaigorl** · June 9, 2016, 1:42pm

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.

**bordaigorl** · June 9, 2016, 1:47pm

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.

API Suggestions

Better control over the status bar

Dynamic menu items

Find out where a setting value in view.settings() was defined

Distinguish view types and get handles of special views

Snippets In on_query_completions

on_close event listeners should be able to abort the close action

Easy way to set contents of a view

API for transient/image views

More general sublime.find_resources

Getting the syntax file from extension/scope

`on_close` event listeners should be able to abort the close action

More general `sublime.find_resources`