Declarative contribution of custom Tree Explorer

src/vs/platform/extensionManagement/common/extensionManagement.ts

@@ -75,6 +75,12 @@ export interface ITheme {
 	label: string;
 }
 
+export interface ITreeExplorer {
+	treeExplorerNodeProviderId: string;
+	treeLabel: string;
+	icon: string;
+}
+
 export interface IExtensionContributions {
 	commands?: ICommand[];
 	configuration?: IConfiguration;
@@ -86,6 +92,7 @@ export interface IExtensionContributions {
 	menus?: { [context: string]: IMenu[] };
 	snippets?: ISnippet[];
 	themes?: ITheme[];
+	explorer?: ITreeExplorer;
 }
 
 export interface IExtensionManifest {

src/vs/vscode.proposed.d.ts

@@ -11,4 +11,78 @@ declare module 'vscode' {
 
 		export function sampleFunction(): Thenable<any>;
 	}
+
+	export namespace workspace {
+
+		/**
+		 * Register a [TreeExplorerNodeProvider](#TreeExplorerNodeProvider).
+		 *
+		 * @param providerId A unique id that identifies the provider.
+		 * @param provider A [TreeExplorerNodeProvider](#TreeExplorerNodeProvider).
+		 * @return A [disposable](#Disposable) that unregisters this provider when being disposed.
+		 */
+		export function registerTreeExplorerNodeProvider(providerId: string, provider: TreeExplorerNodeProvider<any>): Disposable;
+	}
+
+	/**
+	 * A node provider for a tree explorer contribution.
+	 *
+	 * Providers are registered through (#workspace.registerTreeExplorerNodeProvider) with a
+	 * `providerId` that corresponds to the `treeExplorerNodeProviderId` in the extension's
+	 * `contributes.explorer` section.
+	 *
+	 * The contributed tree explorer will ask the corresponding provider to provide the root
+	 * node and resolve children for each node. In addition, the provider could **optionally**
+	 * provide the following information for each node:
+	 * - label: A human-readable label used for rendering the node.
+	 * - hasChildren: Whether the node has children and is expandable.
+	 * - clickCommand: A command to execute when the node is clicked.
+	 */
+	export interface TreeExplorerNodeProvider<T> {
+
+		/**
+		 * Provide the root node. This function will be called when the tree explorer is activated
+		 * for the first time. The root node is hidden and its direct children will be displayed on the first level of
+		 * the tree explorer.
+		 *
+		 * @return The root node.
+		 */
+		provideRootNode(): T | Thenable<T>;
+
+		/**
+		 * Resolve the children of `node`.
+		 *
+		 * @param node The node from which the provider resolves children.
+		 * @return Children of `node`.
+		 */
+		resolveChildren(node: T): T[] | Thenable<T[]>;
+
+		/**
+		 * Provide a human-readable string that will be used for rendering the node. Default to use
+		 * `node.toString()` if not provided.
+		 *
+		 * @param node The node from which the provider computes label.
+		 * @return A human-readable label.
+		 */
+		getLabel?(node: T): string;
+
+		/**
+		 * Determine if `node` has children and is expandable. Default to `true` if not provided.
+		 *
+		 * @param node The node to determine if it has children and is expandable.
+		 * @return A boolean that determines if `node` has children and is expandable.
+		 */
+		getHasChildren?(node: T): boolean;
+
+		/**
+		 * Get the command to execute when `node` is clicked.
+		 *
+		 * Commands can be registered through [registerCommand](#commands.registerCommand). `node` will be provided
+		 * as the first argument to the command's callback function.
+		 *
+		 * @param node The node that the command is associated with.
+		 * @return The command to execute when `node` is clicked.
+		 */
+		getClickCommand?(node: T): string;
+	}
 }

src/vs/workbench/api/node/extHost.api.impl.ts

@@ -17,6 +17,7 @@ import { ExtHostDocuments } from 'vs/workbench/api/node/extHostDocuments';
 import { ExtHostDocumentSaveParticipant } from 'vs/workbench/api/node/extHostDocumentSaveParticipant';
 import { ExtHostConfiguration } from 'vs/workbench/api/node/extHostConfiguration';
 import { ExtHostDiagnostics } from 'vs/workbench/api/node/extHostDiagnostics';
+import { ExtHostTreeExplorers } from 'vs/workbench/api/node/extHostTreeExplorers';
 import { ExtHostWorkspace } from 'vs/workbench/api/node/extHostWorkspace';
 import { ExtHostQuickOpen } from 'vs/workbench/api/node/extHostQuickOpen';
 import { ExtHostHeapService } from 'vs/workbench/api/node/extHostHeapService';
@@ -72,6 +73,7 @@ export function createApiFactory(initDataConfiguration: IInitConfiguration, init
 	const extHostDocumentSaveParticipant = col.define(ExtHostContext.ExtHostDocumentSaveParticipant).set<ExtHostDocumentSaveParticipant>(new ExtHostDocumentSaveParticipant(extHostDocuments, threadService.get(MainContext.MainThreadWorkspace)));
 	const extHostEditors = col.define(ExtHostContext.ExtHostEditors).set<ExtHostEditors>(new ExtHostEditors(threadService, extHostDocuments));
 	const extHostCommands = col.define(ExtHostContext.ExtHostCommands).set<ExtHostCommands>(new ExtHostCommands(threadService, extHostEditors, extHostHeapService));
+	const extHostExplorers = col.define(ExtHostContext.ExtHostExplorers).set<ExtHostTreeExplorers>(new ExtHostTreeExplorers(threadService, extHostCommands));
 	const extHostConfiguration = col.define(ExtHostContext.ExtHostConfiguration).set<ExtHostConfiguration>(new ExtHostConfiguration(threadService.get(MainContext.MainThreadConfiguration), initDataConfiguration));
 	const extHostDiagnostics = col.define(ExtHostContext.ExtHostDiagnostics).set<ExtHostDiagnostics>(new ExtHostDiagnostics(threadService));
 	const languageFeatures = col.define(ExtHostContext.ExtHostLanguageFeatures).set<ExtHostLanguageFeatures>(new ExtHostLanguageFeatures(threadService, extHostDocuments, extHostCommands, extHostHeapService, extHostDiagnostics));
@@ -340,6 +342,9 @@ export function createApiFactory(initDataConfiguration: IInitConfiguration, init
 			onWillSaveTextDocument: (listener, thisArgs?, disposables?) => {
 				return extHostDocumentSaveParticipant.onWillSaveTextDocumentEvent(listener, thisArgs, disposables);
 			},
+			registerTreeExplorerNodeProvider: proposedApiFunction(extension, (providerId: string, provider: vscode.TreeExplorerNodeProvider<any>) => {
+				return extHostExplorers.registerTreeExplorerNodeProvider(providerId, provider);
+			}),
 			onDidChangeConfiguration: (listener: () => any, thisArgs?: any, disposables?: extHostTypes.Disposable[]) => {
 				return extHostConfiguration.onDidChangeConfiguration(listener, thisArgs, disposables);
 			},

src/vs/workbench/api/node/extHost.contribution.ts

@@ -20,6 +20,7 @@ import { MainThreadDiagnostics } from './mainThreadDiagnostics';
 import { MainThreadDocuments } from './mainThreadDocuments';
 import { MainThreadEditors } from './mainThreadEditors';
 import { MainThreadErrors } from './mainThreadErrors';
+import { MainThreadTreeExplorers } from './mainThreadTreeExplorers';
 import { MainThreadLanguageFeatures } from './mainThreadLanguageFeatures';
 import { MainThreadLanguages } from './mainThreadLanguages';
 import { MainThreadMessageService } from './mainThreadMessageService';
@@ -70,6 +71,7 @@ export class ExtHostContribution implements IWorkbenchContribution {
 		col.define(MainContext.MainThreadDocuments).set(create(MainThreadDocuments));
 		col.define(MainContext.MainThreadEditors).set(create(MainThreadEditors));
 		col.define(MainContext.MainThreadErrors).set(create(MainThreadErrors));
+		col.define(MainContext.MainThreadExplorers).set(create(MainThreadTreeExplorers));
 		col.define(MainContext.MainThreadLanguageFeatures).set(create(MainThreadLanguageFeatures));
 		col.define(MainContext.MainThreadLanguages).set(create(MainThreadLanguages));
 		col.define(MainContext.MainThreadMessageService).set(create(MainThreadMessageService));

src/vs/workbench/api/node/extHost.protocol.ts

@@ -35,6 +35,8 @@ import { SaveReason } from 'vs/workbench/services/textfile/common/textfiles';
 import { IWorkspaceSymbol } from 'vs/workbench/parts/search/common/search';
 import { IApplyEditsOptions, TextEditorRevealType, ITextEditorConfigurationUpdate, IResolvedTextEditorConfiguration, ISelectionChangeEvent } from './mainThreadEditorsTracker';
 
+import { InternalTreeExplorerNodeContent } from 'vs/workbench/parts/explorers/common/treeExplorerViewModel';
+
 export interface IEnvironment {
 	appSettingsHome: string;
 	disableExtensions: boolean;
@@ -139,6 +141,10 @@ export abstract class MainThreadEditorsShape {
 	$tryApplyEdits(id: string, modelVersionId: number, edits: editorCommon.ISingleEditOperation[], opts: IApplyEditsOptions): TPromise<boolean> { throw ni(); }
 }
 
+export abstract class MainThreadTreeExplorersShape {
+	$registerTreeExplorerNodeProvider(providerId: string): void { throw ni(); }
+}
+
 export abstract class MainThreadErrorsShape {
 	onUnexpectedExtHostError(err: any): void { throw ni(); }
 }
@@ -280,6 +286,12 @@ export abstract class ExtHostEditorsShape {
 	$acceptTextEditorRemove(id: string): void { throw ni(); }
 }
 
+export abstract class ExtHostTreeExplorersShape {
+	$provideRootNode(providerId: string): TPromise<InternalTreeExplorerNodeContent> { throw ni(); };
+	$resolveChildren(providerId: string, node: InternalTreeExplorerNodeContent): TPromise<InternalTreeExplorerNodeContent[]> { throw ni(); }
+	$getInternalCommand(providerId: string, node: InternalTreeExplorerNodeContent): TPromise<modes.Command> { throw ni(); }
+}
+
 export abstract class ExtHostExtensionServiceShape {
 	$localShowMessage(severity: Severity, msg: string): void { throw ni(); }
 	$activateExtension(extensionDescription: IExtensionDescription): TPromise<void> { throw ni(); }
@@ -354,6 +366,7 @@ export const MainContext = {
 	MainThreadDocuments: createMainId<MainThreadDocumentsShape>('MainThreadDocuments', MainThreadDocumentsShape),
 	MainThreadEditors: createMainId<MainThreadEditorsShape>('MainThreadEditors', MainThreadEditorsShape),
 	MainThreadErrors: createMainId<MainThreadErrorsShape>('MainThreadErrors', MainThreadErrorsShape),
+	MainThreadExplorers: createMainId<MainThreadTreeExplorersShape>('MainThreadExplorers', MainThreadTreeExplorersShape),
 	MainThreadLanguageFeatures: createMainId<MainThreadLanguageFeaturesShape>('MainThreadLanguageFeatures', MainThreadLanguageFeaturesShape),
 	MainThreadLanguages: createMainId<MainThreadLanguagesShape>('MainThreadLanguages', MainThreadLanguagesShape),
 	MainThreadMessageService: createMainId<MainThreadMessageServiceShape>('MainThreadMessageService', MainThreadMessageServiceShape),
@@ -374,6 +387,7 @@ export const ExtHostContext = {
 	ExtHostDocuments: createExtId<ExtHostDocumentsShape>('ExtHostDocuments', ExtHostDocumentsShape),
 	ExtHostDocumentSaveParticipant: createExtId<ExtHostDocumentSaveParticipantShape>('ExtHostDocumentSaveParticipant', ExtHostDocumentSaveParticipantShape),
 	ExtHostEditors: createExtId<ExtHostEditorsShape>('ExtHostEditors', ExtHostEditorsShape),
+	ExtHostExplorers: createExtId<ExtHostTreeExplorersShape>('ExtHostExplorers', ExtHostTreeExplorersShape),
 	ExtHostFileSystemEventService: createExtId<ExtHostFileSystemEventServiceShape>('ExtHostFileSystemEventService', ExtHostFileSystemEventServiceShape),
 	ExtHostHeapService: createExtId<ExtHostHeapServiceShape>('ExtHostHeapMonitor', ExtHostHeapServiceShape),
 	ExtHostLanguageFeatures: createExtId<ExtHostLanguageFeaturesShape>('ExtHostLanguageFeatures', ExtHostLanguageFeaturesShape),

src/vs/workbench/api/node/extHostTreeExplorers.ts

@@ -0,0 +1,101 @@
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *  Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+'use strict';
+
+import { TreeExplorerNodeProvider } from 'vscode';
+import { TPromise } from 'vs/base/common/winjs.base';
+import { Disposable } from 'vs/workbench/api/node/extHostTypes';
+import { IThreadService } from 'vs/workbench/services/thread/common/threadService';
+import { MainContext, ExtHostTreeExplorersShape, MainThreadTreeExplorersShape } from './extHost.protocol';
+import { InternalTreeExplorerNode } from 'vs/workbench/parts/explorers/common/treeExplorerViewModel';
+import { ExtHostCommands } from 'vs/workbench/api/node/extHostCommands';
+import { asWinJsPromise } from 'vs/base/common/async';
+import * as modes from 'vs/editor/common/modes';
+
+export class ExtHostTreeExplorers extends ExtHostTreeExplorersShape {
+	private _proxy: MainThreadTreeExplorersShape;
+
+	private _treeExplorerNodeProviders: { [providerId: string]: TreeExplorerNodeProvider<any> };
+	private _externalNodeMaps: { [providerId: string]: { [id: number]: any } };
+
+	constructor(
+		threadService: IThreadService,
+		private commands: ExtHostCommands
+	) {
+		super();
+
+		this._proxy = threadService.get(MainContext.MainThreadExplorers);
+
+		this._treeExplorerNodeProviders = Object.create(null);
+		this._externalNodeMaps = Object.create(null);
+	}
+
+	registerTreeExplorerNodeProvider(providerId: string, provider: TreeExplorerNodeProvider<any>): Disposable {
+		this._proxy.$registerTreeExplorerNodeProvider(providerId);
+		this._treeExplorerNodeProviders[providerId] = provider;
+
+		return new Disposable(() => {
+			delete this._treeExplorerNodeProviders[providerId];
+			delete this._treeExplorerNodeProviders[providerId];
+		});
+	}
+
+	$provideRootNode(providerId: string): TPromise<InternalTreeExplorerNode> {
+		const provider = this._treeExplorerNodeProviders[providerId];
+		if (!provider) {
+			return TPromise.wrapError(`No TreeExplorerNodeProvider with id '${providerId}' registered.`);
+		}
+
+		return asWinJsPromise(() => provider.provideRootNode()).then(externalRootNode => {
+			const treeNodeMap = Object.create(null);
+			this._externalNodeMaps[providerId] = treeNodeMap;
+
+			const internalRootNode = new InternalTreeExplorerNode(externalRootNode, provider);
+			this._externalNodeMaps[providerId][internalRootNode.id] = externalRootNode;
+			return internalRootNode;
+		}, err => {
+			return TPromise.wrapError(`TreeExplorerNodeProvider '${providerId}' failed to provide root node.`);
+		});
+	}
+
+	$resolveChildren(providerId: string, mainThreadNode: InternalTreeExplorerNode): TPromise<InternalTreeExplorerNode[]> {
+		const provider = this._treeExplorerNodeProviders[providerId];
+		if (!provider) {
+			return TPromise.wrapError(`No TreeExplorerNodeProvider with id '${providerId}' registered.`);
+		}
+
+		const externalNodeMap = this._externalNodeMaps[providerId];
+		const externalNode = externalNodeMap[mainThreadNode.id];
+
+		return asWinJsPromise(() => provider.resolveChildren(externalNode)).then(children => {
+			return children.map(externalChild => {
+				const internalChild = new InternalTreeExplorerNode(externalChild, provider);
+				externalNodeMap[internalChild.id] = externalChild;
+				return internalChild;
+			});
+		}, err => {
+			return TPromise.wrapError(`TreeExplorerNodeProvider '${providerId}' failed to resolve children.`);
+		});
+	}
+
+	// Convert the command on the ExtHost side so we can pass the original externalNode to the registered handler
+	$getInternalCommand(providerId: string, mainThreadNode: InternalTreeExplorerNode): TPromise<modes.Command> {
+		const commandConverter = this.commands.converter;
+
+		if (mainThreadNode.clickCommand) {
+			const externalNode = this._externalNodeMaps[providerId][mainThreadNode.id];
+
+			const internalCommand = commandConverter.toInternal({
+				title: '',
+				command: mainThreadNode.clickCommand,
+				arguments: [externalNode]
+			});
+
+			return TPromise.wrap(internalCommand);
+		}
+
+		return TPromise.as(null);
+	}
+}

src/vs/workbench/api/node/mainThreadTreeExplorers.ts

@@ -0,0 +1,46 @@
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *  Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+'use strict';
+
+import { TPromise } from 'vs/base/common/winjs.base';
+import { IThreadService } from 'vs/workbench/services/thread/common/threadService';
+import { ExtHostContext, MainThreadTreeExplorersShape, ExtHostTreeExplorersShape } from './extHost.protocol';
+import { ITreeExplorerViewletService } from 'vs/workbench/parts/explorers/browser/treeExplorerViewletService';
+import { InternalTreeExplorerNodeContent } from 'vs/workbench/parts/explorers/common/treeExplorerViewModel';
+import { IMessageService, Severity } from 'vs/platform/message/common/message';
+import { ICommandService } from 'vs/platform/commands/common/commands';
+
+export class MainThreadTreeExplorers extends MainThreadTreeExplorersShape {
+	private _proxy: ExtHostTreeExplorersShape;
+
+	constructor(
+		@IThreadService private threadService: IThreadService,
+		@ITreeExplorerViewletService private treeExplorerService: ITreeExplorerViewletService,
+		@IMessageService private messageService: IMessageService,
+		@ICommandService private commandService: ICommandService
+	) {
+		super();
+
+		this._proxy = threadService.get(ExtHostContext.ExtHostExplorers);
+	}
+
+	$registerTreeExplorerNodeProvider(providerId: string): void {
+		const onError = err => { this.messageService.show(Severity.Error, err); };
+
+		this.treeExplorerService.registerTreeExplorerNodeProvider(providerId, {
+			provideRootNode: (): TPromise<InternalTreeExplorerNodeContent> => {
+				return this._proxy.$provideRootNode(providerId).then(rootNode => rootNode, onError);
+			},
+			resolveChildren: (node: InternalTreeExplorerNodeContent): TPromise<InternalTreeExplorerNodeContent[]> => {
+				return this._proxy.$resolveChildren(providerId, node).then(children => children, onError);
+			},
+			executeCommand: (node: InternalTreeExplorerNodeContent): TPromise<any> => {
+				return this._proxy.$getInternalCommand(providerId, node).then(command => {
+					return this.commandService.executeCommand(command.id, ...command.arguments);
+				});
+			}
+		});
+	}
+}