Allow TreeItems to have optional checkboxes

[TylerLeonhardt]

I'm all for trying to avoid webviews as much as possible, especially when tree views are hard to make work in a webview. This proposal allows for treeviews to have checkboxes:

(but better styling of course 😄)

Scenarios

• To-do list extensions
• Applying filters where an 'Edit' button drops you into the experience above where checkboxes show up
• Crafting .gitignore's or other 'ignores' where you go down the filesystem and uncheck the files you want to ignore

Proposal

• TreeItem has new optional property called checkboxState similar to collapsibleState which takes in a TreeItemCheckBoxState:

        export class TreeItem {
            // ...

            /**
             * [TreeItemCheckboxState](#TreeItemCheckboxState) of the tree item.
             */
            checkboxState?: TreeItemCheckboxState;

            // ...
        }

       /**
	 * Checkbox state of the tree item
	 */
        export enum TreeItemCheckboxState{
		/**
		 * Determines an item can be neither checked nor unchecked. Implies it has no checkbox.
		 */
		None = 0,
		/**
		 * Determines an item is checked
		 */
		Checked = 1,
		/**
		 * Determines an item is unchecked
		 */
		Unchecked = 2
	}

• TreeDataProvider will have a new optional event onDidChangeTreeCheckbox which will fire when the checkbox of a TreeItem is checked or unchecked:

        /**
	 * A data provider that provides tree data
	 */
	export interface TreeDataProvider<T> {
                // ...

                /**
		 * An optional event to signal that an element or root has either been checked or unchecked.
		 */
		onDidChangeTreeCheckbox?: Event<ChangeTreeCheckboxEvent<T>>;

                // ...
        }

        export interface ChangeTreeCheckboxEvent {
                /**
		 * The item that was checked or unchecked.
		 */
		readonly item: <T>;

		/**
		 * Removed workspace folders.
		 */
		readonly newState: TreeItemCheckboxState;
        }

[TylerLeonhardt]

btw, this is essentially an alternative to #115365

[joaomoreno]

Interesting that some internal tree usages already do something similar:

[albertelo]

@daviddossett @misolori Hi folks, this feature request has come up for some of our extension authors. Since the last update was more than a year ago, I was wondering if you had this in your pipeline for the near future?

[alexr00]

You should see this appear on our August iteration plan :). We'll start looking into it then.

[benibenj]

API Proposal: #158250

[alexr00]

Re-opening to track API proposal.

[alexr00]

1. checkbox is not rendered if initial state is Unchecked.

@Eskibear I'm not able to reproduce this. Are you able to reproduce this by adding a checkbox to tree items in the [tree view sample](https://github.com/microsoft/vscode-extension-samples/blob/f7b27a91779e770b8f8f0e6791bcefc5d9c64035/tree-view-sample/src/testView.ts#L50-L51}.

2. by check/uncheck, context value is not updated unless I signal the element has changed

As you say, this can be accomplished with onDidChangeTreeData. For now, this is by design. We will revisit as part of the finalization process.

do we need indeterminate state for the checkbox?

We have discussed this, and it would be nice to have. However, the major use cases we have seen so far for the checkbox can live without it. We will revisit during finalization, but I think the outcome will be that we should have only 2 states for now and make sure the API is designed in such a way that if we want to add a third state later we can.

[alexr00]

Starting tomorrow, child and parent checkbox state will be managed by VS Code by default. This can be overridden:

vscode/src/vscode-dts/vscode.proposed.treeItemCheckbox.d.ts

Lines 47 to 57 in 44fc3db

	/**
	* Options for creating a {@link TreeView}
	*/
	export interface TreeViewOptions<T> {
	/**
	* By default, when the children of a tree item have already been fetched, child checkboxes are automatically managed based on the checked state of the parent tree item.
	* If the tree item is collapsed by default (meaning that the children haven't yet been fetched) then child checkboxes will not be updated.
	* To override this behavior and manage child and parent checkbox state in the extension, set this to `true`.
	*/
	manuallyManageCheckboxSelection?: boolean;
	}

We also have a new accessibilityInformation:

vscode/src/vscode-dts/vscode.proposed.treeItemCheckbox.d.ts

Lines 8 to 14 in 44fc3db

	export class TreeItem2 extends TreeItem {
	/**
	* {@link TreeItemCheckboxState TreeItemCheckboxState} of the tree item.
	* {@link TreeDataProvider.onDidChangeTreeData onDidChangeTreeData} should be fired when {@link TreeItem2.checkboxState checkboxState} changes.
	*/
	checkboxState?: TreeItemCheckboxState | { readonly state: TreeItemCheckboxState; readonly tooltip?: string; readonly accessibilityInformation?: AccessibilityInformation };
	}

[Eskibear]

@alexr00 I still can produce it.

Latest Insiders, Commit: f6be5461f8bc69013a605f5baea834651c6589fb

I made some changes, and expect all items ending with "a" to have a checked box, and otherwise an unchecked box. See item "ab", "b" and "bb".

Code change based on the sample.
https://github.com/microsoft/vscode-extension-samples/compare/main...Eskibear:vscode-extension-samples:checkbox?expand=1#diff-c9867a60c64266b038de2193e5a755121ab3e04c2597c19a1cee9ba77ed3a0d4R82

[alexr00]

Thanks for the example @Eskibear! I was using the readonly state: TreeItemCheckboxState; readonly tooltip?: string;} type for checkboxState, which is why I failed to repro.