Explore providing an API for providing progress information

[kieferrm]

Some extensions have a need to make the user aware of long running operations that usually happen in the background. Here are a few examples.

• the Java extension indicates the background installation of the Java language server
• the Azure Functions extensions indicates the generation of code
• the spell checking extension indicates checking in progress
• the Python extension indicates running unit tests

Since VS Code does not provide an API extensions invent their own way of progress reporting usually using status bar contributions. Some use words, some use ascii art, some use glyphs. Some show the progress on the right side, some in the left side. This does not

We'll explore what kind of progress reporting capabilities are most helpful to extensions and how we could expose those in our API.

[jrieken]

While there are many ways and locations to show progress we will focus an 'ambient progress' information presented in the status bar. Still, the solution developed here should be generic enough to allow for progress in other places, like progress inside an editor.

Option 1 - ProgressIndicator API

This is UX'ish API which allows extensions to create ProgressIndicators in the status bar. This is similar to the StatusBarItem-api. It give lots of freedom to extensions which can (but must not) cause headaches for the editor, for instance do we rely on extensions hide/disposing those indicators etc.

export interface ProgressIndicator {
	title: string;
	percentage: number;
	onDidCancel: Event<this>;
	show(): void;
	hide(): void;
	dispose(): void;
}

export namespace window {

	export function createStatusBarProgressIndicator(): ProgressIndicator;
}

Pros:

• flexible

Cons:

• flexible, extension might forget to hide/reset indicator etc
• similar to the StatusBarItem API

Option 2 - declarative

The second options abstracts the UX element of a ProgressIndicator and simply allows extensions to provide a task/callback for which we will show progress. The interface is more simple and allows for less.

export interface Progress {
	message: string;
	precentage: number;
}

export namespace window {
	export function withStatusBarProgress<R>(task: (progress: Progress, token: CancellationToken) => Thenable<R>): Thenable<R>;
}

Pros:

• limited
• allows to restrict the lifecycle of Progress to the execution time of task

Cons:

• limited, it's harder to fit an operation into this which isn't yet wrapped into a promise.

[indiejames]

If I understand Option 2 correctly, this would mean one progress indicator managed by VS Code. This would be an issue if two extensions were executing simultaneous tasks and both wanted to indicate progress.

Also, I think many (perhaps the majority) of uses cases would involve showing an indeterminate progress indicator, e.g., a spinner, to simply indicate that a long running task is occurring. Whatever API you come up with should allow for this.

[jrieken]

Option 2, and that's we one we are implementing, means that the API allows you to suggest to the editor to show progress in different places. One is the status bar, we now call that window progress, others are progress inside the viewlets, editors, or application wide progress (showing on the app icon). That doesn't mean only one progress can be shown at a time but we have UX limitation that don't allow us to show arbitrary progress indicators everywhere. For instance the little clock icons we render on top of the activity switcher can only show one activity at a time. Similar with progress inside editors. Still, all progress elements will stack. So, a latter task overlays the former but also reveals it again when finishing earlier.

[anseki]

My extension Color Picker shows own progress indicator in the status bar while NPM modules installation running.
Since the user might not see the status bar, I made it blink.

• For important message, is an option of new API that make it stand out considered?
• Also, can an extension do something when the task is forcibly aborted? For example, is the onDidCancel event fired when the user closes VS Code also?

When installation for something is aborted, files might be broken, and re-installation may fail.
An extension has to clean up the install directories.

(Sorry, my poor English)

[jrieken]

We will finalise this in March.

@anseki Unsure if important progress is a concept we will support, tho we will have different styles and location to show progress such that you can indicate to a user that something ambient is running or that something needs to be awaited.

[anseki]

Ok, I understood that. Thank you.
I think that a new event that is fired when VS Code is closed is needed for important task such as installation.

[jrieken]

Api is now a single function with an options parameter

/**
 * A location in the editor at which progress information can be shown. It depends on the
 * location how progress is visually represented.
 */
export enum ProgressLocation {

	/**
	 * Show progress for the source control viewlet, as overlay for the icon and as progress bar
	 * inside the viewlet (when visible).
	 */
	SourceControl = 1,
	/**
	 * Show progress in the status bar of the editor.
	 */
	Window = 10
}

/**
 * Value-object describing where and how progress should show.
 */
export interface ProgressOptions {
	/**
	 * The location at which progress should show.
	 */
	location: ProgressLocation;

	/**
	 * A human-readable string which will be used to describe the
	 * operation.
	 */
	title?: string;
}

export function withProgress<R>(options: ProgressOptions, task: (progress: Progress<{ message?: string; percentage?: number }>) => Thenable<R>): Thenable<R>;

[aeschli]

Verified by implementing an extension that uses the new API.

[indiejames]

@aeschli Can you post your extension to github? I'm not quite following the API as posted above.

[aeschli]

Use yo code to generate a sample extension

• in package.json set

    "engines": {
        "vscode": "^1.12.0"
    },

• replace extension.ts with:

'use strict';

export function activate(context: vscode.ExtensionContext) {

    let disposable = vscode.commands.registerCommand('extension.sayHello', () => {

        vscode.window.withProgress({ location: vscode.ProgressLocation.Window, title: 'hello'}, p => {
            return new Promise((resolve, reject) => {
                p.report({message: 'Start working...' });
                let count= 0;
                let handle = setInterval(() => {
                    count++;
                    p.report({message: 'Worked ' + count + ' steps' });
                    if (count >= 10) {
                        clearInterval(handle);
                        resolve();
                    }
                }, 1000);
            });
        });
    });

    context.subscriptions.push(disposable);
}

[vazexqi]

@jrieken - Is support for cancellation going to be (re)added? I see that in your original proposal and PR that you had support for taking a CancellationToken.

Was there a reason for taking it out?

My use case is that I have some commands in the command palette that spawn shell processes that could be long running. I would like the user to be able to click on the status bar item to cancel them (yes, clicking to cancel is not intuitive so maybe a different UX).

I believe the cancellation use case is common. For instance, even in the Git viewlet, sometimes I select "Push", only to realized that I have not authenticated to my local VPN. So the push just hangs there. But, I have no way to cancel that command.

Let me know if this is something that we can consider and I will open a new issue for it.

[siegebell]

@vazexqi I think you should go ahead and open an issue for adding a cancel event to withProgress.

[Xanewok]

@aeschli any plans on exposing also custom tooltip (like here) using public withProgress API?

[aeschli]

No plans, but please file a new issue.