sublimehq
"selected" event when navigating completion list
Problem description
Completions returned from LSP server might provide additional information that need to be explicitly fetched per-completion. This is primarily used for resolving completion documentation lazily when the user navigates to certain completion (otherwise it could be too expensive to provide all that info upfront).
Preferred solution
Provide notification/event when completion is selected/navigated to. That would allow the LSP plugin to lazily fetch additional information for provided completion, on selecting completion.
Alternatives
I haven't verified with code, but it should be achievable currently by providing a link in a completion description that, when clicked, would fetch that extra information. The downside is that it requires an extra step from the user after selecting completion.
Additional Information
The extra notification/event would likely be utilized by showing an extra popup next to the completion list (with use of sublime.COOPERATE_WITH_AUTO_COMPLETE flag for the popup) to automatically provide extra information (documentation) on selecting the item.
I was confident we had an issue for this, but it might also have been on LSP's issue tracker.
There was a bit of discussion about this on Discord, mostly in regards to using it to hide a popup that has been shown.
One of the rather complex aspects of implanting and using this would be identifying the completion that has been selected and notifying the correct plugin source. There can be multiple completions with the same trigger, but different kind metadata, different contents, etc. However, the bigger issue in terms of complexity is that there can be multiple on_query_completion() calls in-flight on the plugin side due to async responses via CompletionList().
Some ideas around solving this would be passing a on_selected() callback with the completions, and it would received the full CompletionItem() object. However, this wouldn't help if you wanted to hide a popup, since ideally only the plugin that created a completion would get notified when it was selected. This begs the existence of on_deselected() to handle such a situation.
Trying to identify a completion by "index" within the data sent from the plugin to Sublime Text seems like it would be hard to consistently identify for plugins, especially in regards to async completions.
It might be worth noting that a popup being displayed next to a completion popup may contain different kinds of information not neccesarily sourced by the selected completion item (only).
In case of function argument completions it may contain:
- a short description about the function's signature with
- the edited formal parameter being highlighted and
- information about the selected completion item in the completion popup.
Therefore just hiding a popup when selection changes might not be what a user expects then.
Assuming sublime would provide an on_selected function. We could display the extra info in an output panel, we would have there plenty of Space.
Rather than on_selected() and on_deselected, I think it would be better to have just on_selected but with arguments that specify the source. That's because coordinating logic within two separate methods could be tricky or at least require extra overhead.
For example when selected item comes from the plugin that provided it then it could receive arguments source: 'self', index: number and when selecting an item that doesn't come from that plugin it would receive `source: 'other' and no index. Or eventually special-case the -1 index to mean that item from source was selected.
The index would be an index into the list returned by the plugin so the plugin would have to hold on to the list it returned if it wanted to lookup the item.