API to expand/collapse custom TreeItems

[eamodio]

I am looking for an API to expand or collapse a specified TreeItem (both deep and shallow).

For example, I would like to provide a Collapse All command for some of my trees to provide a deep collapse (all descendants from the specified item should collapse). Same with expand.

Here are a few more examples: #30288 (comment), gitkraken/vscode-gitlens#383, gitkraken/vscode-gitlens#275

Something similar to reveal that would allow for specifying deep (affects all descendants) or not.

expand(element: T, options?: { deep: boolean } = { deep: false }): Thenable<void>
collapse(element: T, options?: { deep: boolean } = { deep: false }): Thenable<void>

[sandy081]

@eamodio Need of this API is to implement a global expand or collapse all actions? Or is there other requirements?

Edit: Ignore the comment, I see the requests in the other mentioned issue

[eamodio]

@sandy081 is there anyway to get this bumped up from the backlog? I know a few other extension devs anxiously awaiting this 😄

[sandy081]

Planning for October :)

[sandy081]

@eamodio Here is the plan to support this.

Took your suggestion to support expand using reveal api.
reveal(element: T, options?: { select?: boolean, focus?: boolean, expand?: boolean }): Thenable<void>;

collapseAll will be an opt in action while registering the view in package.json. When opted in, collapse all action will be shown in the view header.

[eamodio]

Will expand be 1 level or all levels?

[sandy081]

1 level and not recursive.

[eamodio]

Any chance for reveal(element: T, options?: { select?: boolean, focus?: boolean, expand?: boolean | number }): Thenable<void>;

Where it is fully recursive when true or recursive to the specified number?

gitkraken/vscode-gitlens#275 requires a recursive expansion

[jrieken]

Where it is fully recursive when true or recursive to the specified number?

Recursive expand has the potential for performance suicide that's why we are pushing back on it. The boolean | number proposal isn't bad we are scared of large numbers here. How many levels to you have to expand? Is it feasible for you to "manually" expand them?

[eamodio]

Ah, yeah, that make a lot of sense. I think in most cases, having the option to expand the item or the item and its children is probably enough.

[sandy081]

@eamodio So you would still want the reveal API to take number of levels to expand?

I think expanding just an element will suffice most of the cases and if want to expand one more level you can iterate over children and call reveal?

[eamodio]

Only up to the items children.

Where am I getting the list of children to iterate over to then reveal? Do I have to call item.getChildren() and then make sure that each item maintains an active list of it's children (often I don't maintain a list as the list is already being maintained by vscode and it makes it more complicated to handles refreshes as there are no events when items are removed from the tree)

[sandy081]

Ok. I will allow the API to take number of levels boolean | number. If

• true - expands the element only
• false or 0 - does not expand
• number greater than 0 - expands that many number of levels. 1 implies expanding just the element.

[sandy081]

/**
 * Reveals the given element in the tree view.
 * If the tree view is not visible then the tree view is shown and element is revealed.
 *
 * By default revealed element is selected and not focused.
 * In order to not to select, set the option `select` to `false`.
 * In order to focus, set the option `focus` to `true`.
 * In order to expand the revealed element, set the option `expand` to `true` or `1`. To expand recursively set `expand` to the number of levels to expand.
 * **NOTE:** You can recursively expand to maximum only 3 levels.
 *
 * **NOTE:** [TreeDataProvider](#TreeDataProvider) is required to implement [getParent](#TreeDataProvider.getParent) method to access this API.
 */
reveal(element: T, options?: { select?: boolean, focus?: boolean, expand?: boolean | 1 | 2 | 3 }): Thenable<void>;