diff --git a/types/vscode/index.d.ts b/types/vscode/index.d.ts index 5420be3cc7..4f49c3ef87 100644 --- a/types/vscode/index.d.ts +++ b/types/vscode/index.d.ts @@ -1,4 +1,4 @@ -// Type definitions for Visual Studio Code 1.20 +// Type definitions for Visual Studio Code 1.21 // 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.20 Extension API + * Type Definition for Visual Studio Code 1.21 Extension API * See https://code.visualstudio.com/api for more information */ @@ -779,6 +779,24 @@ declare module 'vscode' { constructor(id: string); } + /** + * A reference to a named icon. Currently only [File](#ThemeIcon.File) and [Folder](#ThemeIcon.Folder) are supported. + * Using a theme icon is preferred over a custom icon as it gives theme authors the possibility to change the icons. + */ + export class ThemeIcon { + /** + * Reference to a icon representing a file. The icon is taken from the current file icon theme or a placeholder icon. + */ + static readonly File: ThemeIcon; + + /** + * Reference to a icon representing a folder. The icon is taken from the current file icon theme or a placeholder icon. + */ + static readonly Folder: ThemeIcon; + + private constructor(id: string); + } + /** * Represents theme specific rendering styles for a [text editor decoration](#TextEditorDecorationType). */ @@ -1043,7 +1061,7 @@ declare module 'vscode' { /** * The document associated with this text editor. The document will be the same for the entire lifetime of this text editor. */ - document: TextDocument; + readonly document: TextDocument; /** * The primary selection on this text editor. Shorthand for `TextEditor.selections[0]`. @@ -1639,8 +1657,11 @@ declare module 'vscode' { title: string; /** - * Indicates that this item replaces the default - * 'Close' action. + * A hint for modal dialogs that the item should be triggered + * when the user cancels the dialog (e.g. by pressing the ESC + * key). + * + * Note: this option is ignored for non-modal messages. */ isCloseAffordance?: boolean; } @@ -3823,7 +3844,7 @@ declare module 'vscode' { * An output channel is a container for readonly textual information. * * To get an instance of an `OutputChannel` use - * [ createOutputChannel](#window.createOutputChannel). + * [createOutputChannel](#window.createOutputChannel). */ export interface OutputChannel { @@ -3916,7 +3937,7 @@ declare module 'vscode' { /** * The text to show for the entry. You can embed icons in the text by leveraging the syntax: * - * `My text $(icon-name) contains icons like $(icon'name) this one.` + * `My text $(icon-name) contains icons like $(icon-name) this one.` * * Where the icon-name is taken from the [octicon](https://octicons.github.com) icon set, e.g. * `light-bulb`, `thumbsup`, `zap` etc. @@ -5088,18 +5109,25 @@ declare module 'vscode' { id?: string; /** - * The icon path for the tree item. When `falsy`, it is derived from [resourceUri](#TreeItem.resourceUri). + * The icon path or [ThemeIcon](#ThemeIcon) for the tree item. + * When `falsy`, [Folder Theme Icon](#ThemeIcon.Folder) is assigned, if item is collapsible otherwise [File Theme Icon](#ThemeIcon.File). + * When a [ThemeIcon](#ThemeIcon) is specified, icon is derived from the current file icon theme for the specified theme icon using [resourceUri](#TreeItem.resourceUri) (if provided). */ - iconPath?: string | Uri | { light: string | Uri; dark: string | Uri }; + iconPath?: string | Uri | { light: string | Uri; dark: string | Uri } | ThemeIcon; /** * The [uri](#Uri) of the resource representing this item. * * Will be used to derive the [label](#TreeItem.label), when it is not provided. - * Will be used to derive the icon from current file icon theme, when [iconPath](#TreeItem.iconPath) is not provided. + * Will be used to derive the icon from current icon theme, when [iconPath](#TreeItem.iconPath) has [ThemeIcon](#ThemeIcon) value. */ resourceUri?: Uri; + /** + * The tooltip text when you hover over this item. + */ + tooltip?: string | undefined; + /** * The [command](#Command) which should be run when the tree item is selected. */ @@ -5440,6 +5468,49 @@ declare module 'vscode' { */ export function asRelativePath(pathOrUri: string | Uri, includeWorkspaceFolder?: boolean): string; + /** + * This method replaces `deleteCount` [workspace folders](#workspace.workspaceFolders) starting at index `start` + * by an optional set of `workspaceFoldersToAdd` on the `vscode.workspace.workspaceFolders` array. This "splice" + * behavior can be used to add, remove and change workspace folders in a single operation. + * + * If the first workspace folder is added, removed or changed, the currently executing extensions (including the + * one that called this method) will be terminated and restarted so that the (deprecated) `rootPath` property is + * updated to point to the first workspace folder. + * + * Use the [`onDidChangeWorkspaceFolders()`](#onDidChangeWorkspaceFolders) event to get notified when the + * workspace folders have been updated. + * + * **Example:** adding a new workspace folder at the end of workspace folders + * ```typescript + * workspace.updateWorkspaceFolders(workspace.workspaceFolders ? workspace.workspaceFolders.length : 0, null, { uri: ...}); + * ``` + * + * **Example:** removing the first workspace folder + * ```typescript + * workspace.updateWorkspaceFolders(0, 1); + * ``` + * + * **Example:** replacing an existing workspace folder with a new one + * ```typescript + * workspace.updateWorkspaceFolders(0, 1, { uri: ...}); + * ``` + * + * It is valid to remove an existing workspace folder and add it again with a different name + * to rename that folder. + * + * **Note:** it is not valid to call [updateWorkspaceFolders()](#updateWorkspaceFolders) multiple times + * without waiting for the [`onDidChangeWorkspaceFolders()`](#onDidChangeWorkspaceFolders) to fire. + * + * @param start the zero-based location in the list of currently opened [workspace folders](#WorkspaceFolder) + * from which to start deleting workspace folders. + * @param deleteCount the optional number of workspace folders to remove. + * @param workspaceFoldersToAdd the optional variable set of workspace folders to add in place of the deleted ones. + * Each workspace is identified with a mandatory URI and an optional name. + * @return true if the operation was successfully started and false otherwise if arguments were used that would result + * in invalid workspace folder state (e.g. 2 folders with the same URI). + */ + export function updateWorkspaceFolders(start: number, deleteCount: number | undefined | null, ...workspaceFoldersToAdd: { uri: Uri, name?: string }[]): boolean; + /** * Creates a file system watcher. * @@ -6332,21 +6403,79 @@ declare module 'vscode' { } /** - * Namespace for dealing with debug sessions. + * An event describing the changes to the set of [breakpoints](#debug.Breakpoint). */ - export namespace debug { + export interface BreakpointsChangeEvent { + /** + * Added breakpoints. + */ + readonly added: Breakpoint[]; /** - * Start debugging by using either a named launch or named compound configuration, - * or by directly passing a [DebugConfiguration](#DebugConfiguration). - * The named configurations are looked up in '.vscode/launch.json' found in the given folder. - * Before debugging starts, all unsaved files are saved and the launch configurations are brought up-to-date. - * Folder specific variables used in the configuration (e.g. '${workspaceFolder}') are resolved against the given folder. - * @param folder The [workspace folder](#WorkspaceFolder) for looking up named configurations and resolving variables or `undefined` for a non-folder setup. - * @param nameOrConfiguration Either the name of a debug or compound configuration or a [DebugConfiguration](#DebugConfiguration) object. - * @return A thenable that resolves when debugging could be successfully started. + * Removed breakpoints. */ - export function startDebugging(folder: WorkspaceFolder | undefined, nameOrConfiguration: string | DebugConfiguration): Thenable; + readonly removed: Breakpoint[]; + + /** + * Changed breakpoints. + */ + readonly changed: Breakpoint[]; + } + + /** + * The base class of all breakpoint types. + */ + export class Breakpoint { + /** + * Is breakpoint enabled. + */ + readonly enabled: boolean; + /** + * An optional expression for conditional breakpoints. + */ + readonly condition?: string; + /** + * An optional expression that controls how many hits of the breakpoint are ignored. + */ + readonly hitCondition?: string; + + protected constructor(enabled?: boolean, condition?: string, hitCondition?: string); + } + + /** + * A breakpoint specified by a source location. + */ + export class SourceBreakpoint extends Breakpoint { + /** + * The source and line position of this breakpoint. + */ + readonly location: Location; + + /** + * Create a new breakpoint for a source location. + */ + constructor(location: Location, enabled?: boolean, condition?: string, hitCondition?: string); + } + + /** + * A breakpoint specified by a function name. + */ + export class FunctionBreakpoint extends Breakpoint { + /** + * The name of the function to which this breakpoint is attached. + */ + readonly functionName: string; + + /** + * Create a new function breakpoint. + */ + constructor(functionName: string, enabled?: boolean, condition?: string, hitCondition?: string); + } + + /** + * Namespace for debug functionality. + */ + export namespace debug { /** * The currently active [debug session](#DebugSession) or `undefined`. The active debug session is the one @@ -6360,6 +6489,12 @@ declare module 'vscode' { */ export let activeDebugConsole: DebugConsole; + /** + * List of breakpoints. + */ + export let breakpoints: Breakpoint[]; + + /** * An [event](#Event) which fires when the [active debug session](#debug.activeDebugSession) * has changed. *Note* that the event also fires when the active debug session changes @@ -6382,6 +6517,12 @@ declare module 'vscode' { */ export const onDidTerminateDebugSession: Event; + /** + * An [event](#Event) that is emitted when the set of breakpoints is added, removed, or changed. + */ + export const onDidChangeBreakpoints: Event; + + /** * Register a [debug configuration provider](#DebugConfigurationProvider) for a specifc debug type. * More than one provider can be registered for the same type. @@ -6391,6 +6532,30 @@ declare module 'vscode' { * @return A [disposable](#Disposable) that unregisters this provider when being disposed. */ export function registerDebugConfigurationProvider(debugType: string, provider: DebugConfigurationProvider): Disposable; + + /** + * Start debugging by using either a named launch or named compound configuration, + * or by directly passing a [DebugConfiguration](#DebugConfiguration). + * The named configurations are looked up in '.vscode/launch.json' found in the given folder. + * Before debugging starts, all unsaved files are saved and the launch configurations are brought up-to-date. + * Folder specific variables used in the configuration (e.g. '${workspaceFolder}') are resolved against the given folder. + * @param folder The [workspace folder](#WorkspaceFolder) for looking up named configurations and resolving variables or `undefined` for a non-folder setup. + * @param nameOrConfiguration Either the name of a debug or compound configuration or a [DebugConfiguration](#DebugConfiguration) object. + * @return A thenable that resolves when debugging could be successfully started. + */ + export function startDebugging(folder: WorkspaceFolder | undefined, nameOrConfiguration: string | DebugConfiguration): Thenable; + + /** + * Add breakpoints. + * @param breakpoints The breakpoints to add. + */ + export function addBreakpoints(breakpoints: Breakpoint[]): void; + + /** + * Remove breakpoints. + * @param breakpoints The breakpoints to remove. + */ + export function removeBreakpoints(breakpoints: Breakpoint[]): void; } /**