Declarative contribution of custom Tree Explorer

src/vs/platform/explorers/browser/explorerExtensionPoint.ts

@@ -0,0 +1,71 @@
+/*---------------------------------------------------------------------------------------------
+ *  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 { localize } from 'vs/nls';
+import { join } from 'vs/base/common/paths';
+import { createCSSRule } from 'vs/base/browser/dom';
+import { IJSONSchema } from 'vs/base/common/jsonSchema';
+import { ExtensionsRegistry } from 'vs/platform/extensions/common/extensionsRegistry';
+import { Registry } from 'vs/platform/platform';
+import { ViewletRegistry, Extensions as ViewletExtensions, ViewletDescriptor } from 'vs/workbench/browser/viewlet';
+import { VIEWLET_ID_ROOT } from 'vs/workbench/parts/explorers/common/treeExplorer';
+
+namespace schema {
+
+	export interface IExplorer {
+		treeExplorerNodeProviderId: string;
+		treeLabel: string;
+		icon: string;
+	}
+
+	export const explorerContribtion: IJSONSchema = {
+		description: localize('vscode.extension.contributes.explorer', "Contributes custom tree explorer viewlet to the sidebar"),
+		type: 'object',
+		properties: {
+			treeExplorerNodeProviderId: {
+				description: localize('vscode.extension.contributes.explorer.treeExplorerNodeProviderId', 'Unique id used to identify provider registered through vscode.workspace.registerTreeExplorerNodeProvider'),
+				type: 'string'
+			},
+			treeLabel: {
+				description: localize('vscode.extension.contributes.explorer.treeLabel', 'Human readable string used to render the custom tree viewlet'),
+				type: 'string'
+			},
+			icon: {
+				description: localize('vscode.extension.contributes.explorer.icon', 'Path to the viewlet icon on the activity bar'),
+				type: 'string'
+			}
+		}
+	};
+}
+
+ExtensionsRegistry.registerExtensionPoint<schema.IExplorer>('explorer', schema.explorerContribtion).setHandler(extensions => {
+	let baseOrder = 200; // Stock viewlet order goes up to 100
+	let descriptors = [];
+
+	for (let extension of extensions) {
+		const { treeExplorerNodeProviderId, treeLabel, icon } = extension.value;
+
+		const getIconRule = (iconPath) => { return `background-image: url('${iconPath}')`; };
+		if (icon) {
+			const iconClass = `.monaco-workbench > .activitybar .monaco-action-bar .action-label.${treeExplorerNodeProviderId}`;
+			const iconPath = join(extension.description.extensionFolderPath, icon);
+			createCSSRule(iconClass, getIconRule(iconPath));
+			// Coerce the icon into a style similar to stock icons
+			createCSSRule(iconClass, '-webkit-filter: grayscale(1) invert(1)');
+		}
+
+		descriptors.push(new ViewletDescriptor(
+			'vs/workbench/parts/explorers/browser/treeExplorerViewlet',
+			'TreeExplorerViewlet',
+			VIEWLET_ID_ROOT + treeExplorerNodeProviderId,
+			treeLabel,
+			treeExplorerNodeProviderId,
+			baseOrder++,
+			true
+		));
+	}
+	Registry.as<ViewletRegistry>(ViewletExtensions.Viewlets).registerExternalViewlets(descriptors);
+});

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

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

src/vs/vscode.d.ts

@@ -1348,6 +1348,72 @@ declare module 'vscode' {
 		provideTextDocumentContent(uri: Uri, token: CancellationToken): string | Thenable<string>;
 	}
 
+	/**
+	 * A node provider for the tree explorer contributed by extension.
+	 *
+	 * 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 return `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 (#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;
+	}
+
 	/**
 	 * Represents an item that can be selected from
 	 * a list of items.
@@ -3803,6 +3869,15 @@ declare module 'vscode' {
 		 */
 		export function registerTextDocumentContentProvider(scheme: string, provider: TextDocumentContentProvider): Disposable;
 
+		/**
+		 * Register a [tree explorer node provider](#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;
+
 		/**
 		 * An event that is emitted when a [text document](#TextDocument) is opened.
 		 */

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';
@@ -65,6 +66,7 @@ export function createApiFactory(threadService: IThreadService, extensionService
 	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)));
 	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));
@@ -332,6 +334,9 @@ export function createApiFactory(threadService: IThreadService, extensionService
 			onWillSaveTextDocument: (listener, thisArgs?, disposables?) => {
 				return extHostDocumentSaveParticipant.onWillSaveTextDocumentEvent(listener, thisArgs, disposables);
 			},
+			registerTreeExplorerNodeProvider(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

@@ -34,6 +34,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 { InternalTreeExplorerNode } from 'vs/workbench/parts/explorers/common/treeExplorerViewModel';
+
 export interface InstanceSetter<T> {
 	set<R extends T>(instance: T): R;
 }
@@ -115,6 +117,11 @@ 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(); }
+	$showMessage(severity: Severity, message: string): void { throw ni(); }
+}
+
 export abstract class MainThreadErrorsShape {
 	onUnexpectedExtHostError(err: any): void { throw ni(); }
 }
@@ -257,6 +264,12 @@ export abstract class ExtHostEditorsShape {
 	$acceptTextEditorRemove(id: string): void { throw ni(); }
 }
 
+export abstract class ExtHostTreeExplorersShape {
+	$provideRootNode(providerId: string): TPromise<InternalTreeExplorerNode> { throw ni(); };
+	$resolveChildren(providerId: string, node: InternalTreeExplorerNode): TPromise<InternalTreeExplorerNode[]> { throw ni(); }
+	$executeCommand(providerId: string, node: InternalTreeExplorerNode): TPromise<void> { throw ni(); }
+}
+
 export abstract class ExtHostExtensionServiceShape {
 	$localShowMessage(severity: Severity, msg: string): void { throw ni(); }
 	$activateExtension(extensionDescription: IExtensionDescription): TPromise<void> { throw ni(); }
@@ -331,6 +344,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),
@@ -351,6 +365,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 { Severity } from 'vs/platform/message/common/message';
+
+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];
+		});
+	}
+
+	$provideRootNode(providerId: string): TPromise<InternalTreeExplorerNode> {
+		const provider = this.getProvider(providerId);
+
+		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 => {
+			this.showErrorMessage(`TreeExplorerNodeProvider '${providerId}' failed to provide root node.`);
+		});
+	}
+
+	$resolveChildren(providerId: string, mainThreadNode: InternalTreeExplorerNode): TPromise<InternalTreeExplorerNode[]> {
+		const provider = this.getProvider(providerId);
+
+		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 => {
+			this.showErrorMessage(`TreeExplorerNodeProvider '${providerId}' failed to resolve children.`);
+		});
+	}
+
+	$executeCommand(providerId: string, mainThreadNode: InternalTreeExplorerNode): TPromise<void> {
+		if (mainThreadNode.clickCommand) {
+			const externalNode = this._externalNodeMaps[providerId][mainThreadNode.id];
+			return asWinJsPromise(() => this.commands.executeCommand(mainThreadNode.clickCommand, externalNode)).then(() => {
+				return null;
+			}, err => {
+				this.showErrorMessage(`Failed to execute command '${mainThreadNode.clickCommand}' provided by TreeExplorerNodeProvider '${providerId}'.`);
+			});
+		}
+
+		return TPromise.as(null);
+	}
+
+	getProvider(providerId: string): TreeExplorerNodeProvider<any> {
+		const provider = this._treeExplorerNodeProviders[providerId];
+		if (!provider) {
+			this.showErrorMessage(`No TreeExplorerNodeProvider with id '${providerId}' registered.`);
+		}
+
+		return provider;
+	}
+
+	private showErrorMessage(message: string): void {
+		this._proxy.$showMessage(Severity.Error, message);
+	}
+}