diff --git a/types/vscode/index.d.ts b/types/vscode/index.d.ts index ad687f0d97..5aa882a98e 100644 --- a/types/vscode/index.d.ts +++ b/types/vscode/index.d.ts @@ -1,4 +1,4 @@ -// Type definitions for Visual Studio Code 1.47 +// Type definitions for Visual Studio Code 1.48 // Project: https://github.com/microsoft/vscode // Definitions by: Visual Studio Code Team, Microsoft // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped @@ -10,7 +10,7 @@ *--------------------------------------------------------------------------------------------*/ /** - * Type Definition for Visual Studio Code 1.47 Extension API + * Type Definition for Visual Studio Code 1.48 Extension API * See https://code.visualstudio.com/api for more information */ @@ -1395,7 +1395,7 @@ declare module 'vscode' { * the `skipEncoding`-argument: `uri.toString(true)`. * * @param skipEncoding Do not percentage-encode the result, defaults to `false`. Note that - * the `#` and `?` characters occurring in the path will always be encoded. + * the `#` and `?` characters occurring in the path will always be encoded. * @returns A string representation of this Uri. */ toString(skipEncoding?: boolean): string; @@ -1735,8 +1735,8 @@ declare module 'vscode' { * like "TypeScript", and an array of extensions, e.g. * ```ts * { - * 'Images': ['png', 'jpg'] - * 'TypeScript': ['ts', 'tsx'] + * 'Images': ['png', 'jpg'] + * 'TypeScript': ['ts', 'tsx'] * } * ``` */ @@ -1770,8 +1770,8 @@ declare module 'vscode' { * like "TypeScript", and an array of extensions, e.g. * ```ts * { - * 'Images': ['png', 'jpg'] - * 'TypeScript': ['ts', 'tsx'] + * 'Images': ['png', 'jpg'] + * 'TypeScript': ['ts', 'tsx'] * } * ``` */ @@ -1976,23 +1976,23 @@ declare module 'vscode' { * * ```ts * let a: HoverProvider = { - * provideHover(doc, pos, token): ProviderResult { - * return new Hover('Hello World'); - * } + * provideHover(doc, pos, token): ProviderResult { + * return new Hover('Hello World'); + * } * } * * let b: HoverProvider = { - * provideHover(doc, pos, token): ProviderResult { - * return new Promise(resolve => { - * resolve(new Hover('Hello World')); - * }); - * } + * provideHover(doc, pos, token): ProviderResult { + * return new Promise(resolve => { + * resolve(new Hover('Hello World')); + * }); + * } * } * * let c: HoverProvider = { - * provideHover(doc, pos, token): ProviderResult { - * return; // undefined - * } + * provideHover(doc, pos, token): ProviderResult { + * return; // undefined + * } * } * ``` */ @@ -4818,19 +4818,19 @@ declare module 'vscode' { * @param section Configuration name, supports _dotted_ names. * @param value The new value. * @param configurationTarget The [configuration target](#ConfigurationTarget) or a boolean value. - * - If `true` updates [Global settings](#ConfigurationTarget.Global). - * - If `false` updates [Workspace settings](#ConfigurationTarget.Workspace). - * - If `undefined` or `null` updates to [Workspace folder settings](#ConfigurationTarget.WorkspaceFolder) if configuration is resource specific, - * otherwise to [Workspace settings](#ConfigurationTarget.Workspace). + * - If `true` updates [Global settings](#ConfigurationTarget.Global). + * - If `false` updates [Workspace settings](#ConfigurationTarget.Workspace). + * - If `undefined` or `null` updates to [Workspace folder settings](#ConfigurationTarget.WorkspaceFolder) if configuration is resource specific, + * otherwise to [Workspace settings](#ConfigurationTarget.Workspace). * @param overrideInLanguage Whether to update the value in the scope of requested languageId or not. - * - If `true` updates the value under the requested languageId. - * - If `undefined` updates the value under the requested languageId only if the configuration is defined for the language. + * - If `true` updates the value under the requested languageId. + * - If `undefined` updates the value under the requested languageId only if the configuration is defined for the language. * @throws error while updating - * - configuration which is not registered. - * - window configuration to workspace folder - * - configuration to workspace or workspace folder when no workspace is opened. - * - configuration to workspace folder when there is no workspace folder settings. - * - configuration to workspace folder when [WorkspaceConfiguration](#WorkspaceConfiguration) is not scoped to a resource. + * - configuration which is not registered. + * - window configuration to workspace folder + * - configuration to workspace or workspace folder when no workspace is opened. + * - configuration to workspace folder when there is no workspace folder settings. + * - configuration to workspace folder when [WorkspaceConfiguration](#WorkspaceConfiguration) is not scoped to a resource. */ update(section: string, value: any, configurationTarget?: ConfigurationTarget | boolean, overrideInLanguage?: boolean): Thenable; @@ -5395,7 +5395,7 @@ declare module 'vscode' { * ```typescript * window.onDidCloseTerminal(t => { * if (t.exitStatus && t.exitStatus.code) { - * vscode.window.showInformationMessage(`Exit code: ${t.exitStatus.code}`); + * vscode.window.showInformationMessage(`Exit code: ${t.exitStatus.code}`); * } * }); * ``` @@ -6296,6 +6296,10 @@ declare module 'vscode' { * Executes a task that is managed by VS Code. The returned * task execution can be used to terminate the task. * + * @throws When running a ShellExecution or a ProcessExecution + * task in an environment where a new process cannot be started. + * In such an environment, only CustomExecution tasks can be run. + * * @param task the task to execute */ export function executeTask(task: Task): Thenable; @@ -7357,6 +7361,9 @@ declare module 'vscode' { /** * The application root folder from which the editor is running. + * + * *Note* that the value is the empty string when running in an + * environment that has no representation of an application root folder. */ export const appRoot: string; @@ -7399,7 +7406,8 @@ declare module 'vscode' { /** * The detected default shell for the extension host, this is overridden by the - * `terminal.integrated.shell` setting for the extension host's platform. + * `terminal.integrated.shell` setting for the extension host's platform. Note that in + * environments that do not support a shell the value is the empty string. */ export const shell: string; @@ -7498,18 +7506,18 @@ declare module 'vscode' { * register a command handler with the identifier `extension.sayHello`. * ```javascript * commands.registerCommand('extension.sayHello', () => { - * window.showInformationMessage('Hello World!'); + * window.showInformationMessage('Hello World!'); * }); * ``` * Second, bind the command identifier to a title under which it will show in the palette (`package.json`). * ```json * { - * "contributes": { - * "commands": [{ - * "command": "extension.sayHello", - * "title": "Hello World" - * }] - * } + * "contributes": { + * "commands": [{ + * "command": "extension.sayHello", + * "title": "Hello World" + * }] + * } * } * ``` */ @@ -7923,7 +7931,7 @@ declare module 'vscode' { * @param options Options that control the dialog. * @returns A promise that resolves to the selected resources or `undefined`. */ - export function showOpenDialog(options: OpenDialogOptions): Thenable; + export function showOpenDialog(options?: OpenDialogOptions): Thenable; /** * Shows a file save dialog to the user which allows to select a file @@ -7932,7 +7940,7 @@ declare module 'vscode' { * @param options Options that control the dialog. * @returns A promise that resolves to the selected resource or `undefined`. */ - export function showSaveDialog(options: SaveDialogOptions): Thenable; + export function showSaveDialog(options?: SaveDialogOptions): Thenable; /** * Opens an input box to ask the user for input. @@ -8073,6 +8081,7 @@ declare module 'vscode' { * allows specifying shell args in * [command-line format](https://msdn.microsoft.com/en-au/08dfcab2-eb6e-49a4-80eb-87d4076c98c6). * @return A new Terminal. + * @throws When running in an environment where a new process cannot be started. */ export function createTerminal(name?: string, shellPath?: string, shellArgs?: string[] | string): Terminal; @@ -8081,6 +8090,7 @@ declare module 'vscode' { * * @param options A TerminalOptions object describing the characteristics of the new terminal. * @return A new Terminal. + * @throws When running in an environment where a new process cannot be started. */ export function createTerminal(options: TerminalOptions): Terminal; @@ -8411,16 +8421,16 @@ declare module 'vscode' { * For example, a tree item is given a context value as `folder`. When contributing actions to `view/item/context` * using `menus` extension point, you can specify context value for key `viewItem` in `when` expression like `viewItem == folder`. * ``` - * "contributes": { - * "menus": { - * "view/item/context": [ - * { - * "command": "extension.deleteFolder", - * "when": "viewItem == folder" - * } - * ] - * } - * } + * "contributes": { + * "menus": { + * "view/item/context": [ + * { + * "command": "extension.deleteFolder", + * "when": "viewItem == folder" + * } + * ] + * } + * } * ``` * This will show action `extension.deleteFolder` only for items with `contextValue` is `folder`. */ @@ -9202,11 +9212,11 @@ declare module 'vscode' { * * ```ts * workspace.onWillSaveTextDocument(event => { - * // async, will *throw* an error - * setTimeout(() => event.waitUntil(promise)); + * // async, will *throw* an error + * setTimeout(() => event.waitUntil(promise)); * - * // sync, OK - * event.waitUntil(promise); + * // sync, OK + * event.waitUntil(promise); * }) * ``` * @@ -9246,11 +9256,11 @@ declare module 'vscode' { * * ```ts * workspace.onWillCreateFiles(event => { - * // async, will *throw* an error - * setTimeout(() => event.waitUntil(promise)); + * // async, will *throw* an error + * setTimeout(() => event.waitUntil(promise)); * - * // sync, OK - * event.waitUntil(promise); + * // sync, OK + * event.waitUntil(promise); * }) * ``` * @@ -9301,11 +9311,11 @@ declare module 'vscode' { * * ```ts * workspace.onWillCreateFiles(event => { - * // async, will *throw* an error - * setTimeout(() => event.waitUntil(promise)); + * // async, will *throw* an error + * setTimeout(() => event.waitUntil(promise)); * - * // sync, OK - * event.waitUntil(promise); + * // sync, OK + * event.waitUntil(promise); * }) * ``` * @@ -9356,11 +9366,11 @@ declare module 'vscode' { * * ```ts * workspace.onWillCreateFiles(event => { - * // async, will *throw* an error - * setTimeout(() => event.waitUntil(promise)); + * // async, will *throw* an error + * setTimeout(() => event.waitUntil(promise)); * - * // sync, OK - * event.waitUntil(promise); + * // sync, OK + * event.waitUntil(promise); * }) * ``` * @@ -9869,11 +9879,12 @@ declare module 'vscode' { export interface ConfigurationChangeEvent { /** - * Returns `true` if the given section is affected in the provided scope. + * Checks if the given section has changed. + * If scope is provided, checks if the section has changed for resources under the given scope. * * @param section Configuration name, supports _dotted_ names. * @param scope A scope in which to check. - * @return `true` if the given section is affected in the provided scope. + * @return `true` if the given section has changed. */ affectsConfiguration(section: string, scope?: ConfigurationScope): boolean; } @@ -9893,9 +9904,9 @@ declare module 'vscode' { * * ```javascript * languages.registerHoverProvider('javascript', { - * provideHover(document, position, token) { - * return new Hover('I am a hover!'); - * } + * provideHover(document, position, token) { + * return new Hover('I am a hover!'); + * } * }); * ``` * @@ -11040,7 +11051,7 @@ declare module 'vscode' { */ export enum DebugConfigurationProviderTriggerKind { /** - * `DebugConfigurationProvider.provideDebugConfigurations` is called to provide the initial debug configurations for a newly created launch.json. + * `DebugConfigurationProvider.provideDebugConfigurations` is called to provide the initial debug configurations for a newly created launch.json. */ Initial = 1, /** @@ -11183,16 +11194,16 @@ declare module 'vscode' { * * ```javascript * export function activate(context: vscode.ExtensionContext) { - * let api = { - * sum(a, b) { - * return a + b; - * }, - * mul(a, b) { - * return a * b; - * } - * }; - * // 'export' public api-surface - * return api; + * let api = { + * sum(a, b) { + * return a + b; + * }, + * mul(a, b) { + * return a * b; + * } + * }; + * // 'export' public api-surface + * return api; * } * ``` * When depending on the API of another extension add an `extensionDependencies`-entry @@ -11299,16 +11310,16 @@ declare module 'vscode' { * For example, a comment thread is given a context value as `editable`. When contributing actions to `comments/commentThread/title` * using `menus` extension point, you can specify context value for key `commentThread` in `when` expression like `commentThread == editable`. * ``` - * "contributes": { - * "menus": { - * "comments/commentThread/title": [ - * { - * "command": "extension.deleteCommentThread", - * "when": "commentThread == editable" - * } - * ] - * } - * } + * "contributes": { + * "menus": { + * "comments/commentThread/title": [ + * { + * "command": "extension.deleteCommentThread", + * "when": "commentThread == editable" + * } + * ] + * } + * } * ``` * This will show action `extension.deleteCommentThread` only for comment threads with `contextValue` is `editable`. */ @@ -11391,16 +11402,16 @@ declare module 'vscode' { * For example, a comment is given a context value as `editable`. When contributing actions to `comments/comment/title` * using `menus` extension point, you can specify context value for key `comment` in `when` expression like `comment == editable`. * ```json - * "contributes": { - * "menus": { - * "comments/comment/title": [ - * { - * "command": "extension.deleteComment", - * "when": "comment == editable" - * } - * ] - * } - * } + * "contributes": { + * "menus": { + * "comments/comment/title": [ + * { + * "command": "extension.deleteComment", + * "when": "comment == editable" + * } + * ] + * } + * } * ``` * This will show action `extension.deleteComment` only for comments with `contextValue` is `editable`. */ @@ -11521,6 +11532,141 @@ declare module 'vscode' { } //#endregion + + /** + * Represents a session of a currently logged in user. + */ + export interface AuthenticationSession { + /** + * The identifier of the authentication session. + */ + readonly id: string; + + /** + * The access token. + */ + readonly accessToken: string; + + /** + * The account associated with the session. + */ + readonly account: AuthenticationSessionAccountInformation; + + /** + * The permissions granted by the session's access token. Available scopes + * are defined by the [AuthenticationProvider](#AuthenticationProvider). + */ + readonly scopes: ReadonlyArray; + } + + /** + * The information of an account associated with an [AuthenticationSession](#AuthenticationSession). + */ + export interface AuthenticationSessionAccountInformation { + /** + * The unique identifier of the account. + */ + readonly id: string; + + /** + * The human-readable name of the account. + */ + readonly label: string; + } + + + /** + * Options to be used when getting an [AuthenticationSession](#AuthenticationSession) from an [AuthenticationProvider](#AuthenticationProvider). + */ + export interface AuthenticationGetSessionOptions { + /** + * Whether login should be performed if there is no matching session. + * + * If true, a modal dialog will be shown asking the user to sign in. If false, a numbered badge will be shown + * on the accounts activity bar icon. An entry for the extension will be added under the menu to sign in. This + * allows quietly prompting the user to sign in. + * + * Defaults to false. + */ + createIfNone?: boolean; + + /** + * Whether the existing user session preference should be cleared. + * + * For authentication providers that support being signed into multiple accounts at once, the user will be + * prompted to select an account to use when [getSession](#authentication.getSession) is called. This preference + * is remembered until [getSession](#authentication.getSession) is called with this flag. + * + * Defaults to false. + */ + clearSessionPreference?: boolean; + } + + /** + * Basic information about an [authenticationProvider](#AuthenticationProvider) + */ + export interface AuthenticationProviderInformation { + /** + * The unique identifier of the authentication provider. + */ + readonly id: string; + + /** + * The human-readable name of the authentication provider. + */ + readonly label: string; + } + + /** + * An [event](#Event) which fires when an [AuthenticationSession](#AuthenticationSession) is added, removed, or changed. + */ + export interface AuthenticationSessionsChangeEvent { + /** + * The [authenticationProvider](#AuthenticationProvider) that has had its sessions change. + */ + readonly provider: AuthenticationProviderInformation; + } + + /** + * Namespace for authentication. + */ + export namespace authentication { + /** + * Get an authentication session matching the desired scopes. Rejects if a provider with providerId is not + * registered, or if the user does not consent to sharing authentication information with + * the extension. If there are multiple sessions with the same scopes, the user will be shown a + * quickpick to select which account they would like to use. + * + * Currently, there are only two authentication providers that are contributed from built in extensions + * to VS Code that implement GitHub and Microsoft authentication: their providerId's are 'github' and 'microsoft'. + * @param providerId The id of the provider to use + * @param scopes A list of scopes representing the permissions requested. These are dependent on the authentication provider + * @param options The [getSessionOptions](#GetSessionOptions) to use + * @returns A thenable that resolves to an authentication session + */ + export function getSession(providerId: string, scopes: string[], options: AuthenticationGetSessionOptions & { createIfNone: true }): Thenable; + + /** + * Get an authentication session matching the desired scopes. Rejects if a provider with providerId is not + * registered, or if the user does not consent to sharing authentication information with + * the extension. If there are multiple sessions with the same scopes, the user will be shown a + * quickpick to select which account they would like to use. + * + * Currently, there are only two authentication providers that are contributed from built in extensions + * to VS Code that implement GitHub and Microsoft authentication: their providerId's are 'github' and 'microsoft'. + * @param providerId The id of the provider to use + * @param scopes A list of scopes representing the permissions requested. These are dependent on the authentication provider + * @param options The [getSessionOptions](#GetSessionOptions) to use + * @returns A thenable that resolves to an authentication session if available, or undefined if there are no sessions + */ + export function getSession(providerId: string, scopes: string[], options?: AuthenticationGetSessionOptions): Thenable; + + /** + * An [event](#Event) which fires when the authentication sessions of an authentication provider have + * been added, removed, or changed. + */ + export const onDidChangeSessions: Event; + } } /**