Improvement for Tree Explorer API

[octref]

Umbrella issue for Tree Explorer API. Continuation of #12163

#14048 is a MVP that provides just enough functionalities for implementing a DB explorer. We decided to start minimal and evolve the API accordingly to feedback.

Here is a list of functionalities / questions that we should think about for future iterations.

Functionalities

• Extension-initiated refresh (call resolveChildren again on a particular item)
• Extension-initiated update to tree items (label, etc)
• Icon (svg or png? should we allow remote icons? how this go with theming?)
• Badge on Activity Bar
• Reveal / Focus a tree item
• Customized right click / context-menu

Questions

• contributes.explorer currently only allows one explorer per extension. Should we allow multiple explorers per extension? Or should we allow more complex Viewlet contributions, such as multi-section Viewlets?
• Should there be an user-defined, workspace config for which explorers to enable? (Would also solve the problem of ordering. Currently custom Viewlets are ordered by enabling sequences, and it's not easy to rearrange them if you have many Viewlets)
• Should we add activation event for Viewlets, like a onLanguage:python Viewlet that only shows its icon if the language is Python?

---

Edit:

Functionalities

• Contributable top bar (we only have refresh by default)

  

[octref]

Fyi @bpasero @jrieken @Tyriar

[bpasero]

/cc @joaomoreno

[DanTup]

Should we allow multiple explorers per extension?

I don't know if these explorers are the correct way to implement these, but Dart Code already had two requests for different things that would be rendered as trees:

• outline view
• type hierarchy

If these are the sorts of things you expect people to use it for, then I think support for multiple would be important. However, I'm not sure if that is the case - both of these things feel like trees that belong as part of the editor for a given file (and maybe not something you'd want icons for?). What do you think? Is it valid to raise another issue to support something like this, or is this explorer functionality the preferred way for something like this?

[octref]

@DanTup

These two can be done as two extensions, one explorer for each, or as two trees in a multi-section explorer, such as the Open Editors and File Explorer in the Explorer View.
Or you can do them as one tree, as Outline View can also show type hierarchy.
So your case doesn't really give an answer to the question.

I don't know if these explorers are the correct way to implement these

Not yet. We left out extension-initiated refresh. Once we have it you can bind a refresh to changeActiveEditor and have an Outline View.

[DanTup]

@octref

So your case doesn't really give an answer to the question.

Sure, was just meant to be feedback that might be useful when you're making a decision, I didn't mean to suggest it was a requirement (though in hindsight you probably know very well what people want from this!). Two extensions would suck a little (especially as it would either require a dependency or both extensions hosting the language service) but I think the others suggestions are very valid!

Not yet. We left out extension-initiated refresh.

I did see that on the list and wonder if that might be an issue but haven't seen the docs yet, thanks for confirming. I'll keep my eye on this case! :)

[Tyriar]

@DanTup I wouldn't go and build 2 extensions now, I imagine multiple trees in a single extension would be added before it's promoted to a stable API.

[Krzysztof-Cieslak]

I've played a bit with API (https://twitter.com/k_cieslak/status/798607133248016386).

From the list given in 1st post I'd want to see:

• Extension-initiated refresh (I think it would handle also Extension-initiated update to tree items)
• Icons for node (getIcon(node) as part of provider ?)
• Right click menus

I'd also want to see some kind of filtering / searching abilities (In more complex case, allowing custom queries, not only textual label matching).

Personally I'd also want to see some option of adding multiple tree explorers - while I understand why you're worried about UX, it's just artificial problem, people will just workaround it by releasing only-tree-explorer extension and adding it as extensionDependencies... at least that's what I'd do ;)

[jrieken]

@DanTup Re #15485 (comment) We are actually not very keen on that happening. If we end up with an outline view or type hierarchy UI per (language) extension we have failed to deliver a streamlined editor with consistent and easy to understand UI.

For common programming-scenarios like show type hierarchy we should do the same we have already done for other features like IntelliSense, Reference Search, Diagnostics etc. That is VS Code builds UI, defines interaction models, and adds API to plug-in data providers to these features. That is a proven approach and we are not planning to exchange that. Just image how VS Code would look and feel if every language extension would have contributed its own reference search UI.

Two questions: Why don't you make a proposal for a TypeHierarchyProvider-api in the spirit of existing providers, like ReferenceProvider. That is feature common to writing code and other languages will also benefit from this.

Also, I wonder where the request for an OutlineView comes from? We always look at the 'document symbol'-feature as exactly that and I wonder what is missing? Do folks miss a tree or do they wanna see in which child-node the cursor currently is? I'd like to know how we can make this better.

[Tyriar]

@jrieken if the outline tree is always present I've found it can be a great way of familiarizing yourself with the contents of a file as it essentially puts the interface (of a class) on the side. Also when I use ctrl+r to look at the symbols I only ever care about the high level symbols, there is also some weird duplication of symbols that happens in some files. Take https://github.com/sourcelair/xterm.js/blob/master/src/xterm.js for example:

Lots of local functions and variables which I don't care about clutter it up, making it harder to explore a file in this manner.

Also a thought: it might make more sense to be able to view this information for a file underneath the file inside the file explorer and exposing a command to expand/collapse it that could be keybound for convenience, rather than a completely new viewlet.

[DanTup]

@jrieken

@DanTup Re #15485 (comment) We are actually not very keen on that happening

I actually totally agree with everything you said; I would much rather Code has a standard way of implementing these that was consistent across languages. There's already a request for one of these (#5605) but it hasn't been really clear if it's likely to be implemented which is why I hadn't raised the other (and wondered if it'd make sense for me to try to do with this new tree).

Why don't you make a proposal for a TypeHierarchyProvider-api in the spirit of existing providers, like ReferenceProvider. That is feature common to writing code and other languages will also benefit from this.

I've opened #15533 though it's not a feature I've actually used in any editor so it's not all that detailed. I can try to add more if required.

Also, I wonder where the request for an OutlineView comes from? We always look at the 'document symbol'-feature as exactly that and I wonder what is missing? Do folks miss a tree or do they wanna see in which child-node the cursor currently is? I'd like to know how we can make this better.

I don't have a lot of info on this, but my guesses (I'm not an experience Dart dev) are:

• The current document symbol list is flat which doesn't really match the file structure (it can have top level functions, classes, classes within classes, functions within classes, functions within functions, etc.). This might be less of an issue with some languages (generally flat, single-class-per-file, etc.) but to me it does feel a bit awkward.
• An outline view is a good way to get an idea of the contents of a file at a glance - is it a single class with a thousand methods? A file of fifty classes? I think it's useful to have an overview like this, especially when exploring someone elses code. I think it's also even better if it can be always visible.

@sladage raised the original issue in Dart Code so maybe he can add his motivation. @devoncarew may also have some ideas as he's worked on some of the other Dart IDE integrations.

(btw, if I'm derailing this issue a little and this discussion is best elsewhere, let me know)

[octref]

IMO Symbol search and Outline View serve different use cases.

• Symbol -> you know what you are looking for and want to quickly jump to there.
• Outline -> quickly scanning high-level structure of a file.

In a sense Outline is closer to Minimap instead of Viewlet I believe.

And as Outline View is a special case and not very suitable as an extension using this API (as @jrieken pointed out, it deserves deeper integration), discussions should happen in #5605.

[ramya-rao-a]

@jrieken

Also, I wonder where the request for an OutlineView comes from? We always look at the 'document symbol'-feature as exactly that and I wonder what is missing? Do folks miss a tree or do they wanna see in which child-node the cursor currently is? I'd like to know how we can make this better.

See #15222

[Kurren123]

Any update on this? Seems like a large number of extensions would benefit

[pr-yemibedu]

Hello,
The viewlet being enabled would be nice to work like existing extensions. A viewlet being active for a workspace would be nice if it had defaults for languages or files it favored. Since I don't know of users in general ordering the extensions they install, the viewlets would not benefit for the same reasons.

One viewlet per extension really encourages single responsibility. an extension viewlet should rely on another service extension if there is an author that provides general functionality that could be used by multiple views. Multiple sections in a view is helpful when you want to see both a sort by list and a group by list in a single viewlet. Thank you. Good day.

[entr0cks]

Still want something like @Tyriar mentioned. I'm seriously missing the "navigation" pane from NetBeans.
Basically an interface of the file - good overview and reference of what you have in the file.

Would be great if the "Explorer" pane could be split vertically - so the lower half would be another pane, like the following (from NetBeans):

[jrieken]

Closing as this is feedback collected on a old implementation and design. Feedback should come in separate items and relate to the design we have actually shipped.