diff --git a/types/vscode/index.d.ts b/types/vscode/index.d.ts index 4f81092898..e01e612919 100644 --- a/types/vscode/index.d.ts +++ b/types/vscode/index.d.ts @@ -1,4 +1,4 @@ -// Type definitions for Visual Studio Code 1.16 +// Type definitions for Visual Studio Code 1.17 // Project: https://github.com/microsoft/vscode-extension-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.16 Extension API + * Type Definition for Visual Studio Code 1.17 Extension API */ declare module 'vscode' { @@ -743,7 +743,8 @@ declare module 'vscode' { /** * An optional view column in which the [editor](#TextEditor) should be shown. * The default is the [one](#ViewColumn.One), other values are adjusted to - * be __Min(column, columnCount + 1)__. + * be `Min(column, columnCount + 1)`, the [active](#ViewColumn.Active)-column is + * not adjusted. */ viewColumn?: ViewColumn; @@ -783,7 +784,7 @@ declare module 'vscode' { export interface ThemableDecorationRenderOptions { /** * Background color of the decoration. Use rgba() and define transparent background colors to play well with other decorations. - * Alternativly a color from the color registry an be [referenced](#ColorIdentifier). + * Alternatively a color from the color registry can be [referenced](#ThemeColor). */ backgroundColor?: string | ThemeColor; @@ -1189,6 +1190,11 @@ declare module 'vscode' { */ static parse(value: string): Uri; + /** + * Use the `file` and `parse` factory functions to create new `Uri` objects. + */ + private constructor(scheme: string, authority: string, path: string, query: string, fragment: string); + /** * Scheme is the `http` part of `http://www.msft.com/some/path?query#fragment`. * The part before the first colon. @@ -1508,6 +1514,80 @@ declare module 'vscode' { onDidSelectItem?(item: QuickPickItem | string): any; } + /** + * Options to configure the behaviour of a file open dialog. + * + * * Note 1: A dialog can select files, folders, or both. This is not true for Windows + * which enforces to open either files or folder, but *not both*. + * * Note 2: Explictly setting `canSelectFiles` and `canSelectFolders` to `false` is futile + * and the editor then silently adjusts the options to select files. + */ + export interface OpenDialogOptions { + /** + * The resource the dialog shows when opened. + */ + defaultUri?: Uri; + + /** + * A human-readable string for the open button. + */ + openLabel?: string; + + /** + * Allow to select files, defaults to `true`. + */ + canSelectFiles?: boolean; + + /** + * Allow to select folders, defaults to `false`. + */ + canSelectFolders?: boolean; + + /** + * Allow to select many files or folders. + */ + canSelectMany?: boolean; + + /** + * A set of file filters that are used by the dialog. Each entry is a human readable label, + * like "TypeScript", and an array of extensions, e.g. + * ```ts + * { + * 'Images': ['png', 'jpg'] + * 'TypeScript': ['ts', 'tsx'] + * } + * ``` + */ + filters?: { [name: string]: string[] }; + } + + /** + * Options to configure the behaviour of a file save dialog. + */ + export interface SaveDialogOptions { + /** + * The resource the dialog shows when opened. + */ + defaultUri?: Uri; + + /** + * A human-readable string for the save button. + */ + saveLabel?: string; + + /** + * A set of file filters that are used by the dialog. Each entry is a human readable label, + * like "TypeScript", and an array of extensions, e.g. + * ```ts + * { + * 'Images': ['png', 'jpg'] + * 'TypeScript': ['ts', 'tsx'] + * } + * ``` + */ + filters?: { [name: string]: string[] }; + } + /** * Represents an action that is shown with an information, warning, or * error message. @@ -1594,6 +1674,44 @@ declare module 'vscode' { validateInput?(value: string): string | undefined | null; } + /** + * A relative pattern is a helper to construct glob patterns that are matched + * relatively to a base path. The base path can either be an absolute file path + * or a [workspace folder](#WorkspaceFolder). + */ + class RelativePattern { + + /** + * A base file path to which this pattern will be matched against relatively. + */ + base: string; + + /** + * A file glob pattern like `*.{ts,js}` that will be matched on file paths + * relative to the base path. + * + * Example: Given a base of `/home/work/folder` and a file path of `/home/work/folder/index.js`, + * the file glob pattern will match on `index.js`. + */ + pattern: string; + + /** + * Creates a new relative pattern object with a base path and pattern to match. This pattern + * will be matched on file paths relative to the base path. + * + * @param base A base file path to which this pattern will be matched against relatively. + * @param pattern A file glob pattern like `*.{ts,js}` that will be matched on file paths + * relative to the base path. + */ + constructor(base: WorkspaceFolder | string, pattern: string) + } + + /** + * A file glob pattern to match file paths against. This can either be a glob pattern string + * (like `**∕*.{ts,js}` or `*.{ts,js}`) or a [relative pattern](#RelativePattern). + */ + export type GlobPattern = string | RelativePattern; + /** * A document filter denotes a document by different properties like * the [language](#TextDocument.languageId), the [scheme](#Uri.scheme) of @@ -1615,9 +1733,10 @@ declare module 'vscode' { scheme?: string; /** - * A glob pattern, like `*.{ts,js}`. + * A [glob pattern](#GlobPattern) that is matched on the absolute path of the document. Use a [relative pattern](#RelativePattern) + * to filter documents to a [workspace folder](#WorkspaceFolder). */ - pattern?: string; + pattern?: GlobPattern; } /** @@ -1629,7 +1748,6 @@ declare module 'vscode' { */ export type DocumentSelector = string | DocumentFilter | (string | DocumentFilter)[]; - /** * A provider result represents the values a provider, like the [`HoverProvider`](#HoverProvider), * may return. For once this is the actual result type `T`, like `Hover`, or a thenable that resolves @@ -2097,6 +2215,11 @@ declare module 'vscode' { * skip the [location](#SymbolInformation.location) of symbols and implement `resolveWorkspaceSymbol` to do that * later. * + * The `query`-parameter should be interpreted in a *relaxed way* as the editor will apply its own highlighting + * and scoring on the results. A good rule of thumb is to match case-insensitive and to simply check that the + * characters of *query* appear in their order in a candidate symbol. Don't use prefix, substring, or similar + * strict matching. + * * @param query A non-empty query string. * @param token A cancellation token. * @return An array of document highlights or a thenable that resolves to such. The lack of a result can be @@ -2468,7 +2591,7 @@ declare module 'vscode' { * The human-readable doc-comment of this signature. Will be shown * in the UI but can be omitted. */ - documentation?: string; + documentation?: string | MarkdownString; /** * Creates a new parameter information object. @@ -2476,7 +2599,7 @@ declare module 'vscode' { * @param label A label string. * @param documentation A doc string. */ - constructor(label: string, documentation?: string); + constructor(label: string, documentation?: string | MarkdownString); } /** @@ -2496,7 +2619,7 @@ declare module 'vscode' { * The human-readable doc-comment of this signature. Will be shown * in the UI but can be omitted. */ - documentation?: string; + documentation?: string | MarkdownString; /** * The parameters of this signature. @@ -2509,7 +2632,7 @@ declare module 'vscode' { * @param label A label string. * @param documentation A doc string. */ - constructor(label: string, documentation?: string); + constructor(label: string, documentation?: string | MarkdownString); } /** @@ -2623,7 +2746,7 @@ declare module 'vscode' { /** * A human-readable string that represents a doc-comment. */ - documentation?: string; + documentation?: string | MarkdownString; /** * A string that should be used when comparing this item @@ -2728,6 +2851,40 @@ declare module 'vscode' { constructor(items?: CompletionItem[], isIncomplete?: boolean); } + /** + * How a [completion provider](#CompletionItemProvider) was triggered + */ + export enum CompletionTriggerKind { + /** + * Completion was triggered normally. + */ + Invoke = 0, + /** + * Completion was triggered by a trigger character. + */ + TriggerCharacter = 1 + } + + /** + * Contains additional information about the context in which + * [completion provider](#CompletionItemProvider.provideCompletionItems) is triggered. + */ + export interface CompletionContext { + /** + * How the completion was triggered. + */ + readonly triggerKind: CompletionTriggerKind; + + /** + * Character that triggered the completion item provider. + * + * `undefined` if provider was not triggered by a character. + * + * The trigger character is already in the document when the completion provider is triggered. + */ + readonly triggerCharacter?: string; + } + /** * The completion item provider interface defines the contract between extensions and * [IntelliSense](https://code.visualstudio.com/docs/editor/intellisense). @@ -2750,10 +2907,12 @@ declare module 'vscode' { * @param document The document in which the command was invoked. * @param position The position at which the command was invoked. * @param token A cancellation token. + * @param context How the completion was triggered. + * * @return An array of completions, a [completion list](#CompletionList), or a thenable that resolves to either. * The lack of a result can be signaled by returning `undefined`, `null`, or an empty array. */ - provideCompletionItems(document: TextDocument, position: Position, token: CancellationToken): ProviderResult; + provideCompletionItems(document: TextDocument, position: Position, token: CancellationToken, context: CompletionContext): ProviderResult; /** * Given a completion item fill in more data, like [doc-comment](#CompletionItem.documentation) @@ -3321,8 +3480,24 @@ declare module 'vscode' { * used to show editors side by side. */ export enum ViewColumn { + /** + * A *symbolic* editor column representing the currently + * active column. This value can be used when opening editors, but the + * *resolved* [viewColumn](#TextEditor.viewColumn)-value of editors will always + * be `One`, `Two`, `Three`, or `undefined` but never `Active`. + */ + Active = -1, + /** + * The left most editor column. + */ One = 1, + /** + * The center editor column. + */ Two = 2, + /** + * The right most editor column. + */ Three = 3 } @@ -3879,13 +4054,30 @@ declare module 'vscode' { options?: ShellExecutionOptions; } + /** + * The scope of a task. + */ + export enum TaskScope { + /** + * The task is a global task + */ + Global = 1, + + /** + * The task is a workspace task + */ + Workspace = 2 + } + /** * A task to execute */ export class Task { /** - * Creates a new task. + * ~~Creates a new task.~~ + * + * @deprecated Use the new constructors that allow specifying a target for the task. * * @param definition The task definition as defined in the taskDefinitions extension point. * @param name The task's name. Is presented in the user interface. @@ -3897,11 +4089,30 @@ declare module 'vscode' { */ constructor(taskDefinition: TaskDefinition, name: string, source: string, execution?: ProcessExecution | ShellExecution, problemMatchers?: string | string[]); + /** + * Creates a new task. + * + * @param definition The task definition as defined in the taskDefinitions extension point. + * @param target Specifies the task's target. It is either a global or a workspace task or a task for a specific workspace folder. + * @param name The task's name. Is presented in the user interface. + * @param source The task's source (e.g. 'gulp', 'npm', ...). Is presented in the user interface. + * @param execution The process or shell execution. + * @param problemMatchers the names of problem matchers to use, like '$tsc' + * or '$eslint'. Problem matchers can be contributed by an extension using + * the `problemMatchers` extension point. + */ + constructor(taskDefinition: TaskDefinition, target: WorkspaceFolder | TaskScope.Global | TaskScope.Workspace, name: string, source: string, execution?: ProcessExecution | ShellExecution, problemMatchers?: string | string[]); + /** * The task's definition. */ definition: TaskDefinition; + /** + * The task's scope. + */ + scope?: TaskScope.Global | TaskScope.Workspace | WorkspaceFolder; + /** * The task's name */ @@ -4185,8 +4396,9 @@ declare module 'vscode' { * to control where the editor is being shown. Might change the [active editor](#window.activeTextEditor). * * @param document A text document to be shown. - * @param column A view column in which the editor should be shown. The default is the [one](#ViewColumn.One), other values - * are adjusted to be __Min(column, columnCount + 1)__. + * @param column A view column in which the [editor](#TextEditor) should be shown. The default is the [one](#ViewColumn.One), other values + * are adjusted to be `Min(column, columnCount + 1)`, the [active](#ViewColumn.Active)-column is + * not adjusted. * @param preserveFocus When `true` the editor will not take focus. * @return A promise that resolves to an [editor](#TextEditor). */ @@ -4197,7 +4409,7 @@ declare module 'vscode' { * to control options of the editor is being shown. Might change the [active editor](#window.activeTextEditor). * * @param document A text document to be shown. - * @param options [Editor options](#ShowTextDocumentOptions) to configure the behavior of showing the [editor](#TextEditor). + * @param options [Editor options](#TextDocumentShowOptions) to configure the behavior of showing the [editor](#TextEditor). * @return A promise that resolves to an [editor](#TextEditor). */ export function showTextDocument(document: TextDocument, options?: TextDocumentShowOptions): Thenable; @@ -4208,7 +4420,7 @@ declare module 'vscode' { * @see [openTextDocument](#openTextDocument) * * @param uri A resource identifier. - * @param options [Editor options](#ShowTextDocumentOptions) to configure the behavior of showing the [editor](#TextEditor). + * @param options [Editor options](#TextDocumentShowOptions) to configure the behavior of showing the [editor](#TextEditor). * @return A promise that resolves to an [editor](#TextEditor). */ export function showTextDocument(uri: Uri, options?: TextDocumentShowOptions): Thenable; @@ -4377,6 +4589,24 @@ declare module 'vscode' { */ export function showQuickPick(items: T[] | Thenable, options?: QuickPickOptions, token?: CancellationToken): Thenable; + /** + * Shows a file open dialog to the user which allows to select a file + * for opening-purposes. + * + * @param options Options that control the dialog. + * @returns A promise that resolves to the selected resources or `undefined`. + */ + export function showOpenDialog(options: OpenDialogOptions): Thenable; + + /** + * Shows a file save dialog to the user which allows to select a file + * for saving-purposes. + * + * @param options Options that control the dialog. + * @returns A promise that resolves to the selected resource or `undefined`. + */ + export function showSaveDialog(options: SaveDialogOptions): Thenable; + /** * Opens an input box to ask the user for input. * @@ -4766,13 +4996,16 @@ declare module 'vscode' { export interface WorkspaceFolder { /** - * The associated URI for this workspace folder. + * The associated uri for this workspace folder. + * + * *Note:* The [Uri](#Uri)-type was intentionally chosen such that future releases of the editor can support + * workspace folders that are not stored on the local disk, e.g. `ftp://server/workspaces/foo`. */ readonly uri: Uri; /** * The name of this workspace folder. Defaults to - * the basename its [uri-path](#Uri.path) + * the basename of its [uri-path](#Uri.path) */ readonly name: string; @@ -4817,8 +5050,9 @@ declare module 'vscode' { export const onDidChangeWorkspaceFolders: Event; /** - * Returns a [workspace folder](#WorkspaceFolder) for the provided resource. When the resource - * is a workspace folder itself, its parent workspace folder or `undefined` is returned. + * Returns the [workspace folder](#WorkspaceFolder) that contains a given uri. + * * returns `undefined` when the given uri doesn't match any workspace folder + * * returns the *input* when the given uri is a workspace folder itself * * @param uri An uri. * @return A workspace folder or `undefined` @@ -4842,30 +5076,35 @@ declare module 'vscode' { /** * Creates a file system watcher. * - * A glob pattern that filters the file events must be provided. Optionally, flags to ignore certain - * kinds of events can be provided. To stop listening to events the watcher must be disposed. + * A glob pattern that filters the file events on their absolute path must be provided. Optionally, + * flags to ignore certain kinds of events can be provided. To stop listening to events the watcher must be disposed. * * *Note* that only files within the current [workspace folders](#workspace.workspaceFolders) can be watched. * - * @param globPattern A glob pattern that is applied to the names of created, changed, and deleted files. + * @param globPattern A [glob pattern](#GlobPattern) that is applied to the absolute paths of created, changed, + * and deleted files. Use a [relative pattern](#RelativePattern) to limit events to a certain [workspace folder](#WorkspaceFolder). * @param ignoreCreateEvents Ignore when files have been created. * @param ignoreChangeEvents Ignore when files have been changed. * @param ignoreDeleteEvents Ignore when files have been deleted. * @return A new file system watcher instance. */ - export function createFileSystemWatcher(globPattern: string, ignoreCreateEvents?: boolean, ignoreChangeEvents?: boolean, ignoreDeleteEvents?: boolean): FileSystemWatcher; + export function createFileSystemWatcher(globPattern: GlobPattern, ignoreCreateEvents?: boolean, ignoreChangeEvents?: boolean, ignoreDeleteEvents?: boolean): FileSystemWatcher; /** - * Find files in the workspace. + * Find files across all [workspace folders](#workspace.workspaceFolders) in the workspace. * * @sample `findFiles('**∕*.js', '**∕node_modules∕**', 10)` - * @param include A glob pattern that defines the files to search for. - * @param exclude A glob pattern that defines files and folders to exclude. + * @param include A [glob pattern](#GlobPattern) that defines the files to search for. The glob pattern + * will be matched against the file paths of resulting matches relative to their workspace. Use a [relative pattern](#RelativePattern) + * to restrict the search results to a [workspace folder](#WorkspaceFolder). + * @param exclude A [glob pattern](#GlobPattern) that defines files and folders to exclude. The glob pattern + * will be matched against the file paths of resulting matches relative to their workspace. * @param maxResults An upper-bound for the result. * @param token A token that can be used to signal cancellation to the underlying search engine. - * @return A thenable that resolves to an array of resource identifiers. + * @return A thenable that resolves to an array of resource identifiers. Will return no results if no + * [workspace folders](#workspace.workspaceFolders) are opened. */ - export function findFiles(include: string, exclude?: string, maxResults?: number, token?: CancellationToken): Thenable; + export function findFiles(include: GlobPattern, exclude?: GlobPattern, maxResults?: number, token?: CancellationToken): Thenable; /** * Save all dirty files. @@ -4957,7 +5196,7 @@ declare module 'vscode' { /** * An event that is emitted when a [text document](#TextDocument) is changed. This usually happens * when the [contents](#TextDocument.getText) changes but also when other things like the - * [dirty](TextDocument#isDirty)-state changes. + * [dirty](#TextDocument.isDirty)-state changes. */ export const onDidChangeTextDocument: Event; @@ -5479,6 +5718,11 @@ declare module 'vscode' { */ readonly label: string; + /** + * The (optional) Uri of the root of this source control. + */ + readonly rootUri: Uri | undefined; + /** * The [input box](#SourceControlInputBox) for this source control. */ @@ -5538,7 +5782,7 @@ declare module 'vscode' { * ~~The [input box](#SourceControlInputBox) for the last source control * created by the extension.~~ * - * @deprecated Use [SourceControl.inputBox](#SourceControl.inputBox) instead + * @deprecated Use SourceControl.inputBox instead */ export const inputBox: SourceControlInputBox; @@ -5547,9 +5791,10 @@ declare module 'vscode' { * * @param id An `id` for the source control. Something short, eg: `git`. * @param label A human-readable string for the source control. Eg: `Git`. + * @param rootUri An optional Uri of the root of the source control. Eg: `Uri.parse(workspaceRoot)`. * @return An instance of [source control](#SourceControl). */ - export function createSourceControl(id: string, label: string): SourceControl; + export function createSourceControl(id: string, label: string, rootUri?: Uri): SourceControl; } /** @@ -5623,6 +5868,35 @@ declare module 'vscode' { body?: any; } + /** + * A debug configuration provider allows to add the initial debug configurations to a newly created launch.json + * and allows to resolve a launch configuration before it is used to start a new debug session. + * A debug configuration provider is registered via #workspace.registerDebugConfigurationProvider. + */ + export interface DebugConfigurationProvider { + /** + * Provides initial [debug configuration](#DebugConfiguration). If more than one debug configuration provider is + * registered for the same type, debug configurations are concatenated in arbitrary order. + * + * @param folder The workspace folder for which the configurations are used or undefined for a folderless setup. + * @param token A cancellation token. + * @return An array of [debug configurations](#DebugConfiguration). + */ + provideDebugConfigurations?(folder: WorkspaceFolder | undefined, token?: CancellationToken): ProviderResult; + + /** + * Resolves a [debug configuration](#DebugConfiguration) by filling in missing values or by adding/changing/removing attributes. + * If more than one debug configuration provider is registered for the same type, the resolveDebugConfiguration calls are chained + * in arbitrary order and the initial debug configuration is piped through the chain. + * + * @param folder The workspace folder from which the configuration originates from or undefined for a folderless setup. + * @param debugConfiguration The [debug configuration](#DebugConfiguration) to resolve. + * @param token A cancellation token. + * @return The resolved debug configuration. + */ + resolveDebugConfiguration?(folder: WorkspaceFolder | undefined, debugConfiguration: DebugConfiguration, token?: CancellationToken): ProviderResult; + } + /** * Namespace for dealing with debug sessions. */ @@ -5633,7 +5907,7 @@ declare module 'vscode' { * 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. '${workspaceRoot}') are resolved against the given folder. + * 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. @@ -5668,6 +5942,16 @@ declare module 'vscode' { * An [event](#Event) which fires when a [debug session](#DebugSession) has terminated. */ export const onDidTerminateDebugSession: Event; + + /** + * Register a [debug configuration provider](#DebugConfigurationProvider) for a specifc debug type. + * More than one provider can be registered for the same type. + * + * @param type The debug type for which the provider is registered. + * @param provider The [debug configuration provider](#DebugConfigurationProvider) to register. + * @return A [disposable](#Disposable) that unregisters this provider when being disposed. + */ + export function registerDebugConfigurationProvider(debugType: string, provider: DebugConfigurationProvider): Disposable; } /**