diff --git a/tree-view-sample/package-lock.json b/tree-view-sample/package-lock.json index d67e16330..02a0b379d 100644 --- a/tree-view-sample/package-lock.json +++ b/tree-view-sample/package-lock.json @@ -73,9 +73,9 @@ } }, "@types/vscode": { - "version": "1.39.0", - "resolved": "https://registry.npmjs.org/@types/vscode/-/vscode-1.39.0.tgz", - "integrity": "sha512-rlg0okXDt7NjAyHXbZ2nO1I/VY/8y9w67ltLRrOxXQ46ayvrYZavD4A6zpYrGbs2+ZOEQzcUs+QZOqcVGQIxXQ==", + "version": "1.42.0", + "resolved": "https://registry.npmjs.org/@types/vscode/-/vscode-1.42.0.tgz", + "integrity": "sha512-ds6TceMsh77Fs0Mq0Vap6Y72JbGWB8Bay4DrnJlf5d9ui2RSe1wis13oQm+XhguOeH1HUfLGzaDAoupTUtgabw==", "dev": true }, "ansi-styles": { diff --git a/tree-view-sample/package.json b/tree-view-sample/package.json index 4e2ca6cd4..a8baa1803 100644 --- a/tree-view-sample/package.json +++ b/tree-view-sample/package.json @@ -6,7 +6,7 @@ "publisher": "vscode-samples", "enableProposedApi": true, "engines": { - "vscode": "^1.39.0" + "vscode": "^1.42.0" }, "categories": [ "Other" @@ -215,7 +215,7 @@ "@types/mkdirp": "^0.5.2", "@types/node": "^10.12.21", "@types/rimraf": "^2.0.2", - "@types/vscode": "^1.39.0", + "@types/vscode": "^1.42.0", "typescript": "^3.5.1", "tslint": "^5.12.1" }, diff --git a/tree-view-sample/vscode.proposed.d.ts b/tree-view-sample/vscode.proposed.d.ts index 93afe709f..d1ccd81b8 100644 --- a/tree-view-sample/vscode.proposed.d.ts +++ b/tree-view-sample/vscode.proposed.d.ts @@ -16,89 +16,70 @@ declare module 'vscode' { - //#region Joh - call hierarchy + // #region auth provider: https://github.com/microsoft/vscode/issues/88309 - export class CallHierarchyItem { - /** - * The name of this item. - */ - name: string; + export interface AuthenticationSession { + id: string; + getAccessToken(): Thenable; + accountName: string; + scopes: string[] + } + /** + * An [event](#Event) which fires when an [AuthenticationProvider](#AuthenticationProvider) is added or removed. + */ + export interface AuthenticationProvidersChangeEvent { /** - * The kind of this item. + * The ids of the [authenticationProvider](#AuthenticationProvider)s that have been added. */ - kind: SymbolKind; + readonly added: string[]; /** - * Tags for this item. + * The ids of the [authenticationProvider](#AuthenticationProvider)s that have been removed.. */ - tags?: ReadonlyArray; + readonly removed: string[]; + } + export interface AuthenticationProvider { /** - * More detail for this item, e.g. the signature of a function. + * Used as an identifier for extensions trying to work with a particular + * provider: 'Microsoft', 'GitHub', etc. id must be unique, registering + * another provider with the same id will fail. */ - detail?: string; + readonly id: string; + readonly displayName: string; /** - * The resource identifier of this item. + * A [enent](#Event) which fires when the array of sessions has changed, or data + * within a session has changed. */ - uri: Uri; + readonly onDidChangeSessions: Event; /** - * The range enclosing this symbol not including leading/trailing whitespace but everything else, e.g. comments and code. + * Returns an array of current sessions. */ - range: Range; + getSessions(): Thenable>; /** - * The range that should be selected and reveal when this symbol is being picked, e.g. the name of a function. - * Must be contained by the [`range`](#CallHierarchyItem.range). + * Prompts a user to login. */ - selectionRange: Range; - - constructor(kind: SymbolKind, name: string, detail: string, uri: Uri, range: Range, selectionRange: Range); - } - - export class CallHierarchyIncomingCall { - from: CallHierarchyItem; - fromRanges: Range[]; - constructor(item: CallHierarchyItem, fromRanges: Range[]); + login(scopes: string[]): Thenable; + logout(sessionId: string): Thenable; } - export class CallHierarchyOutgoingCall { - fromRanges: Range[]; - to: CallHierarchyItem; - constructor(item: CallHierarchyItem, fromRanges: Range[]); - } - - export interface CallHierarchyItemProvider { - - /** - * Provide a list of callers for the provided item, e.g. all function calling a function. - */ - provideCallHierarchyIncomingCalls(document: TextDocument, position: Position, token: CancellationToken): ProviderResult; + export namespace authentication { + export function registerAuthenticationProvider(provider: AuthenticationProvider): Disposable; /** - * Provide a list of calls for the provided item, e.g. all functions call from a function. + * Fires with the provider id that was registered or unregistered. */ - provideCallHierarchyOutgoingCalls(document: TextDocument, position: Position, token: CancellationToken): ProviderResult; - - // todo@joh this could return as 'prepareCallHierarchy' (similar to the RenameProvider#prepareRename) - // - // /** - // * - // * Given a document and position compute a call hierarchy item. This is justed as - // * anchor for call hierarchy and then `resolveCallHierarchyItem` is being called. - // */ - // resolveCallHierarchyItem(document: TextDocument, position: Position, token: CancellationToken): ProviderResult; - } + export const onDidChangeAuthenticationProviders: Event; - export namespace languages { - export function registerCallHierarchyProvider(selector: DocumentSelector, provider: CallHierarchyItemProvider): Disposable; + export const providers: ReadonlyArray; } //#endregion - //#region Alex - resolvers export interface RemoteAuthorityResolverContext { @@ -116,7 +97,40 @@ declare module 'vscode' { extensionHostEnv?: { [key: string]: string | null }; } - export type ResolverResult = ResolvedAuthority & ResolvedOptions; + export interface TunnelOptions { + remoteAddress: { port: number, host: string }; + // The desired local port. If this port can't be used, then another will be chosen. + localAddressPort?: number; + label?: string; + } + + export interface TunnelDescription { + remoteAddress: { port: number, host: string }; + //The complete local address(ex. localhost:1234) + localAddress: string; + } + + export interface Tunnel extends TunnelDescription { + // Implementers of Tunnel should fire onDidDispose when dispose is called. + onDidDispose: Event; + dispose(): void; + } + + /** + * Used as part of the ResolverResult if the extension has any candidate, + * published, or forwarded ports. + */ + export interface TunnelInformation { + /** + * Tunnels that are detected by the extension. The remotePort is used for display purposes. + * The localAddress should be the complete local address (ex. localhost:1234) for connecting to the port. Tunnels provided through + * detected are read-only from the forwarded ports UI. + */ + environmentTunnels?: TunnelDescription[]; + + } + + export type ResolverResult = ResolvedAuthority & ResolvedOptions & TunnelInformation; export class RemoteAuthorityResolverError extends Error { static NotAvailable(message?: string, handled?: boolean): RemoteAuthorityResolverError; @@ -127,6 +141,44 @@ declare module 'vscode' { export interface RemoteAuthorityResolver { resolve(authority: string, context: RemoteAuthorityResolverContext): ResolverResult | Thenable; + /** + * Can be optionally implemented if the extension can forward ports better than the core. + * When not implemented, the core will use its default forwarding logic. + * When implemented, the core will use this to forward ports. + */ + tunnelFactory?: (tunnelOptions: TunnelOptions) => Thenable | undefined; + + /** + * Provides filtering for candidate ports. + */ + showCandidatePort?: (host: string, port: number, detail: string) => Thenable; + } + + export namespace workspace { + /** + * Forwards a port. If the current resolver implements RemoteAuthorityResolver:forwardPort then that will be used to make the tunnel. + * By default, openTunnel only support localhost; however, RemoteAuthorityResolver:tunnelFactory can be used to support other ips. + * @param tunnelOptions The `localPort` is a suggestion only. If that port is not available another will be chosen. + */ + export function openTunnel(tunnelOptions: TunnelOptions): Thenable; + + /** + * Gets an array of the currently available tunnels. This does not include environment tunnels, only tunnels that have been created by the user. + * Note that these are of type TunnelDescription and cannot be disposed. + */ + export let tunnels: Thenable; + + /** + * Fired when the list of tunnels has changed. + * @deprecated use onDidChangeTunnels instead + */ + // TODO@alexr + // eslint-disable-next-line vscode-dts-event-naming + export const onDidTunnelsChange: Event; + /** + * Fired when the list of tunnels has changed. + */ + export const onDidChangeTunnels: Event; } export interface ResourceLabelFormatter { @@ -137,6 +189,8 @@ declare module 'vscode' { export interface ResourceLabelFormatting { label: string; // myLabel:/${path} + // TODO@isi + // eslint-disable-next-line vscode-dts-literal-or-types separator: '/' | '\\' | ''; tildify?: boolean; normalizeDriveLetter?: boolean; @@ -151,8 +205,216 @@ declare module 'vscode' { //#endregion + //#region Semantic tokens: https://github.com/microsoft/vscode/issues/86415 + + export class SemanticTokensLegend { + public readonly tokenTypes: string[]; + public readonly tokenModifiers: string[]; + + constructor(tokenTypes: string[], tokenModifiers: string[]); + } + + export class SemanticTokensBuilder { + constructor(); + push(line: number, char: number, length: number, tokenType: number, tokenModifiers: number): void; + build(): Uint32Array; + } + + export class SemanticTokens { + /** + * The result id of the tokens. + * + * This is the id that will be passed to `DocumentSemanticTokensProvider.provideDocumentSemanticTokensEdits` (if implemented). + */ + readonly resultId?: string; + readonly data: Uint32Array; + + constructor(data: Uint32Array, resultId?: string); + } + + export class SemanticTokensEdits { + /** + * The result id of the tokens. + * + * This is the id that will be passed to `DocumentSemanticTokensProvider.provideDocumentSemanticTokensEdits` (if implemented). + */ + readonly resultId?: string; + readonly edits: SemanticTokensEdit[]; + + constructor(edits: SemanticTokensEdit[], resultId?: string); + } + + export class SemanticTokensEdit { + readonly start: number; + readonly deleteCount: number; + readonly data?: Uint32Array; + + constructor(start: number, deleteCount: number, data?: Uint32Array); + } + + /** + * The document semantic tokens provider interface defines the contract between extensions and + * semantic tokens. + */ + export interface DocumentSemanticTokensProvider { + /** + * A file can contain many tokens, perhaps even hundreds of thousands of tokens. Therefore, to improve + * the memory consumption around describing semantic tokens, we have decided to avoid allocating an object + * for each token and we represent tokens from a file as an array of integers. Furthermore, the position + * of each token is expressed relative to the token before it because most tokens remain stable relative to + * each other when edits are made in a file. + * + * --- + * In short, each token takes 5 integers to represent, so a specific token `i` in the file consists of the following array indices: + * - at index `5*i` - `deltaLine`: token line number, relative to the previous token + * - at index `5*i+1` - `deltaStart`: token start character, relative to the previous token (relative to 0 or the previous token's start if they are on the same line) + * - at index `5*i+2` - `length`: the length of the token. A token cannot be multiline. + * - at index `5*i+3` - `tokenType`: will be looked up in `SemanticTokensLegend.tokenTypes`. We currently ask that `tokenType` < 65536. + * - at index `5*i+4` - `tokenModifiers`: each set bit will be looked up in `SemanticTokensLegend.tokenModifiers` + * + * --- + * ### How to encode tokens + * + * Here is an example for encoding a file with 3 tokens in a uint32 array: + * ``` + * { line: 2, startChar: 5, length: 3, tokenType: "property", tokenModifiers: ["private", "static"] }, + * { line: 2, startChar: 10, length: 4, tokenType: "type", tokenModifiers: [] }, + * { line: 5, startChar: 2, length: 7, tokenType: "class", tokenModifiers: [] } + * ``` + * + * 1. First of all, a legend must be devised. This legend must be provided up-front and capture all possible token types. + * For this example, we will choose the following legend which must be passed in when registering the provider: + * ``` + * tokenTypes: ['property', 'type', 'class'], + * tokenModifiers: ['private', 'static'] + * ``` + * + * 2. The first transformation step is to encode `tokenType` and `tokenModifiers` as integers using the legend. Token types are looked + * up by index, so a `tokenType` value of `1` means `tokenTypes[1]`. Multiple token modifiers can be set by using bit flags, + * so a `tokenModifier` value of `3` is first viewed as binary `0b00000011`, which means `[tokenModifiers[0], tokenModifiers[1]]` because + * bits 0 and 1 are set. Using this legend, the tokens now are: + * ``` + * { line: 2, startChar: 5, length: 3, tokenType: 0, tokenModifiers: 3 }, + * { line: 2, startChar: 10, length: 4, tokenType: 1, tokenModifiers: 0 }, + * { line: 5, startChar: 2, length: 7, tokenType: 2, tokenModifiers: 0 } + * ``` + * + * 3. The next step is to represent each token relative to the previous token in the file. In this case, the second token + * is on the same line as the first token, so the `startChar` of the second token is made relative to the `startChar` + * of the first token, so it will be `10 - 5`. The third token is on a different line than the second token, so the + * `startChar` of the third token will not be altered: + * ``` + * { deltaLine: 2, deltaStartChar: 5, length: 3, tokenType: 0, tokenModifiers: 3 }, + * { deltaLine: 0, deltaStartChar: 5, length: 4, tokenType: 1, tokenModifiers: 0 }, + * { deltaLine: 3, deltaStartChar: 2, length: 7, tokenType: 2, tokenModifiers: 0 } + * ``` + * + * 4. Finally, the last step is to inline each of the 5 fields for a token in a single array, which is a memory friendly representation: + * ``` + * // 1st token, 2nd token, 3rd token + * [ 2,5,3,0,3, 0,5,4,1,0, 3,2,7,2,0 ] + * ``` + */ + provideDocumentSemanticTokens(document: TextDocument, token: CancellationToken): ProviderResult; + + /** + * Instead of always returning all the tokens in a file, it is possible for a `DocumentSemanticTokensProvider` to implement + * this method (`updateSemanticTokens`) and then return incremental updates to the previously provided semantic tokens. + * + * --- + * ### How tokens change when the document changes + * + * Let's look at how tokens might change. + * + * Continuing with the above example, suppose a new line was inserted at the top of the file. + * That would make all the tokens move down by one line (notice how the line has changed for each one): + * ``` + * { line: 3, startChar: 5, length: 3, tokenType: "property", tokenModifiers: ["private", "static"] }, + * { line: 3, startChar: 10, length: 4, tokenType: "type", tokenModifiers: [] }, + * { line: 6, startChar: 2, length: 7, tokenType: "class", tokenModifiers: [] } + * ``` + * The integer encoding of the tokens does not change substantially because of the delta-encoding of positions: + * ``` + * // 1st token, 2nd token, 3rd token + * [ 3,5,3,0,3, 0,5,4,1,0, 3,2,7,2,0 ] + * ``` + * It is possible to express these new tokens in terms of an edit applied to the previous tokens: + * ``` + * [ 2,5,3,0,3, 0,5,4,1,0, 3,2,7,2,0 ] // old tokens + * [ 3,5,3,0,3, 0,5,4,1,0, 3,2,7,2,0 ] // new tokens + * + * edit: { start: 0, deleteCount: 1, data: [3] } // replace integer at offset 0 with 3 + * ``` + * + * Furthermore, let's assume that a new token has appeared on line 4: + * ``` + * { line: 3, startChar: 5, length: 3, tokenType: "property", tokenModifiers: ["private", "static"] }, + * { line: 3, startChar: 10, length: 4, tokenType: "type", tokenModifiers: [] }, + * { line: 4, startChar: 3, length: 5, tokenType: "property", tokenModifiers: ["static"] }, + * { line: 6, startChar: 2, length: 7, tokenType: "class", tokenModifiers: [] } + * ``` + * The integer encoding of the tokens is: + * ``` + * // 1st token, 2nd token, 3rd token, 4th token + * [ 3,5,3,0,3, 0,5,4,1,0, 1,3,5,0,2, 2,2,7,2,0, ] + * ``` + * Again, it is possible to express these new tokens in terms of an edit applied to the previous tokens: + * ``` + * [ 3,5,3,0,3, 0,5,4,1,0, 3,2,7,2,0 ] // old tokens + * [ 3,5,3,0,3, 0,5,4,1,0, 1,3,5,0,2, 2,2,7,2,0, ] // new tokens + * + * edit: { start: 10, deleteCount: 1, data: [1,3,5,0,2,2] } // replace integer at offset 10 with [1,3,5,0,2,2] + * ``` + * + * *NOTE*: When doing edits, it is possible that multiple edits occur until VS Code decides to invoke the semantic tokens provider. + * *NOTE*: If the provider cannot compute `SemanticTokensEdits`, it can "give up" and return all the tokens in the document again. + * *NOTE*: All edits in `SemanticTokensEdits` contain indices in the old integers array, so they all refer to the previous result state. + */ + provideDocumentSemanticTokensEdits?(document: TextDocument, previousResultId: string, token: CancellationToken): ProviderResult; + } + + /** + * The document range semantic tokens provider interface defines the contract between extensions and + * semantic tokens. + */ + export interface DocumentRangeSemanticTokensProvider { + /** + * See [provideDocumentSemanticTokens](#DocumentSemanticTokensProvider.provideDocumentSemanticTokens). + */ + provideDocumentRangeSemanticTokens(document: TextDocument, range: Range, token: CancellationToken): ProviderResult; + } + + export namespace languages { + /** + * Register a semantic tokens provider for a whole document. + * + * Multiple providers can be registered for a language. In that case providers are sorted + * by their [score](#languages.match) and the best-matching provider is used. Failure + * of the selected provider will cause a failure of the whole operation. + * + * @param selector A selector that defines the documents this provider is applicable to. + * @param provider A document semantic tokens provider. + * @return A [disposable](#Disposable) that unregisters this provider when being disposed. + */ + export function registerDocumentSemanticTokensProvider(selector: DocumentSelector, provider: DocumentSemanticTokensProvider, legend: SemanticTokensLegend): Disposable; + + /** + * Register a semantic tokens provider for a document range. + * + * Multiple providers can be registered for a language. In that case providers are sorted + * by their [score](#languages.match) and the best-matching provider is used. Failure + * of the selected provider will cause a failure of the whole operation. + * + * @param selector A selector that defines the documents this provider is applicable to. + * @param provider A document range semantic tokens provider. + * @return A [disposable](#Disposable) that unregisters this provider when being disposed. + */ + export function registerDocumentRangeSemanticTokensProvider(selector: DocumentSelector, provider: DocumentRangeSemanticTokensProvider, legend: SemanticTokensLegend): Disposable; + } + + //#endregion - // #region Joh - code insets + //#region editor insets: https://github.com/microsoft/vscode/issues/85682 export interface WebviewEditorInset { readonly editor: TextEditor; @@ -169,7 +431,7 @@ declare module 'vscode' { //#endregion - //#region Joh - read/write in chunks + //#region read/write in chunks: https://github.com/microsoft/vscode/issues/84515 export interface FileSystemProvider { open?(resource: Uri, options: { create: boolean }): number | Thenable; @@ -180,7 +442,7 @@ declare module 'vscode' { //#endregion - //#region Rob: search provider + //#region TextSearchProvider: https://github.com/microsoft/vscode/issues/59921 /** * The parameters of a query for text search. @@ -324,32 +586,6 @@ declare module 'vscode' { limitHit?: boolean; } - /** - * The parameters of a query for file search. - */ - export interface FileSearchQuery { - /** - * The search pattern to match against file paths. - */ - pattern: string; - } - - /** - * Options that apply to file search. - */ - export interface FileSearchOptions extends SearchOptions { - /** - * The maximum number of results to be returned. - */ - maxResults?: number; - - /** - * A CancellationToken that represents the session for this search query. If the provider chooses to, this object can be used as the key for a cache, - * and searches with the same session object can search the same cache. When the token is cancelled, the session is complete and the cache can be cleared. - */ - session?: CancellationToken; - } - /** * A preview of the text result. */ @@ -409,6 +645,50 @@ declare module 'vscode' { export type TextSearchResult = TextSearchMatch | TextSearchContext; + /** + * A TextSearchProvider provides search results for text results inside files in the workspace. + */ + export interface TextSearchProvider { + /** + * Provide results that match the given text pattern. + * @param query The parameters for this query. + * @param options A set of options to consider while searching. + * @param progress A progress callback that must be invoked for all results. + * @param token A cancellation token. + */ + provideTextSearchResults(query: TextSearchQuery, options: TextSearchOptions, progress: Progress, token: CancellationToken): ProviderResult; + } + + //#endregion + + //#region FileSearchProvider: https://github.com/microsoft/vscode/issues/73524 + + /** + * The parameters of a query for file search. + */ + export interface FileSearchQuery { + /** + * The search pattern to match against file paths. + */ + pattern: string; + } + + /** + * Options that apply to file search. + */ + export interface FileSearchOptions extends SearchOptions { + /** + * The maximum number of results to be returned. + */ + maxResults?: number; + + /** + * A CancellationToken that represents the session for this search query. If the provider chooses to, this object can be used as the key for a cache, + * and searches with the same session object can search the same cache. When the token is cancelled, the session is complete and the cache can be cleared. + */ + session?: CancellationToken; + } + /** * A FileSearchProvider provides search results for files in the given folder that match a query string. It can be invoked by quickopen or other extensions. * @@ -428,20 +708,34 @@ declare module 'vscode' { provideFileSearchResults(query: FileSearchQuery, options: FileSearchOptions, token: CancellationToken): ProviderResult; } - /** - * A TextSearchProvider provides search results for text results inside files in the workspace. - */ - export interface TextSearchProvider { + export namespace workspace { /** - * Provide results that match the given text pattern. - * @param query The parameters for this query. - * @param options A set of options to consider while searching. - * @param progress A progress callback that must be invoked for all results. - * @param token A cancellation token. + * Register a search provider. + * + * Only one provider can be registered per scheme. + * + * @param scheme The provider will be invoked for workspace folders that have this file scheme. + * @param provider The provider. + * @return A [disposable](#Disposable) that unregisters this provider when being disposed. */ - provideTextSearchResults(query: TextSearchQuery, options: TextSearchOptions, progress: Progress, token: CancellationToken): ProviderResult; + export function registerFileSearchProvider(scheme: string, provider: FileSearchProvider): Disposable; + + /** + * Register a text search provider. + * + * Only one provider can be registered per scheme. + * + * @param scheme The provider will be invoked for workspace folders that have this file scheme. + * @param provider The provider. + * @return A [disposable](#Disposable) that unregisters this provider when being disposed. + */ + export function registerTextSearchProvider(scheme: string, provider: TextSearchProvider): Disposable; } + //#endregion + + //#region findTextInFiles: https://github.com/microsoft/vscode/issues/59924 + /** * Options that can be set on a findTextInFiles search. */ @@ -507,35 +801,13 @@ declare module 'vscode' { export namespace workspace { /** - * Register a search provider. - * - * Only one provider can be registered per scheme. - * - * @param scheme The provider will be invoked for workspace folders that have this file scheme. - * @param provider The provider. - * @return A [disposable](#Disposable) that unregisters this provider when being disposed. + * Search text in files across all [workspace folders](#workspace.workspaceFolders) in the workspace. + * @param query The query parameters for the search - the search string, whether it's case-sensitive, or a regex, or matches whole words. + * @param callback A callback, called for each result + * @param token A token that can be used to signal cancellation to the underlying search engine. + * @return A thenable that resolves when the search is complete. */ - export function registerFileSearchProvider(scheme: string, provider: FileSearchProvider): Disposable; - - /** - * Register a text search provider. - * - * Only one provider can be registered per scheme. - * - * @param scheme The provider will be invoked for workspace folders that have this file scheme. - * @param provider The provider. - * @return A [disposable](#Disposable) that unregisters this provider when being disposed. - */ - export function registerTextSearchProvider(scheme: string, provider: TextSearchProvider): Disposable; - - /** - * Search text in files across all [workspace folders](#workspace.workspaceFolders) in the workspace. - * @param query The query parameters for the search - the search string, whether it's case-sensitive, or a regex, or matches whole words. - * @param callback A callback, called for each result - * @param token A token that can be used to signal cancellation to the underlying search engine. - * @return A thenable that resolves when the search is complete. - */ - export function findTextInFiles(query: TextSearchQuery, callback: (result: TextSearchResult) => void, token?: CancellationToken): Thenable; + export function findTextInFiles(query: TextSearchQuery, callback: (result: TextSearchResult) => void, token?: CancellationToken): Thenable; /** * Search text in files across all [workspace folders](#workspace.workspaceFolders) in the workspace. @@ -550,7 +822,7 @@ declare module 'vscode' { //#endregion - //#region Joao: diff command + //#region diff command: https://github.com/microsoft/vscode/issues/84899 /** * The contiguous set of modified lines in a diff. @@ -583,7 +855,7 @@ declare module 'vscode' { //#endregion - //#region Joh: decorations + //#region file-decorations: https://github.com/microsoft/vscode/issues/54938 export class Decoration { letter?: string; @@ -604,9 +876,7 @@ declare module 'vscode' { //#endregion - //#region André: debug - - // deprecated + //#region deprecated debug API export interface DebugConfigurationProvider { /** @@ -616,59 +886,9 @@ declare module 'vscode' { debugAdapterExecutable?(folder: WorkspaceFolder | undefined, token?: CancellationToken): ProviderResult; } - /** - * Debug console mode used by debug session, see [options](#DebugSessionOptions). - */ - export enum DebugConsoleMode { - /** - * Debug session should have a separate debug console. - */ - Separate = 0, - - /** - * Debug session should share debug console with its parent session. - * This value has no effect for sessions which do not have a parent session. - */ - MergeWithParent = 1 - } - - /** - * Options for [starting a debug session](#debug.startDebugging). - */ - export interface DebugSessionOptions { - - /** - * When specified the newly created debug session is registered as a "child" session of this - * "parent" debug session. - */ - parentSession?: DebugSession; - - /** - * Controls whether this session should have a separate debug console or share it - * with the parent session. Has no effect for sessions which do not have a parent session. - * Defaults to Separate. - */ - consoleMode?: DebugConsoleMode; - } - - export namespace debug { - /** - * 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. - * @param parentSessionOrOptions Debug sesison options. When passed a parent [debug session](#DebugSession), assumes options with just this parent session. - * @return A thenable that resolves when debugging could be successfully started. - */ - export function startDebugging(folder: WorkspaceFolder | undefined, nameOrConfiguration: string | DebugConfiguration, parentSessionOrOptions?: DebugSession | DebugSessionOptions): Thenable; - } - //#endregion - //#region Rob, Matt: logging + //#region LogLevel: https://github.com/microsoft/vscode/issues/85992 /** * The severity level of a log message @@ -772,15 +992,38 @@ declare module 'vscode' { export interface SourceControlInputBox { /** - * Controls whether the input box is visible (default is `true`). - */ + * Controls whether the input box is visible (default is `true`). + */ visible: boolean; } //#endregion + //#region Terminal data write event https://github.com/microsoft/vscode/issues/78502 - //#region Terminal + export interface TerminalDataWriteEvent { + /** + * The [terminal](#Terminal) for which the data was written. + */ + readonly terminal: Terminal; + /** + * The data being written. + */ + readonly data: string; + } + + namespace window { + /** + * An event which fires when the terminal's pty slave pseudo-device is written to. In other + * words, this provides access to the raw data stream from the process running within the + * terminal, including VT sequences. + */ + export const onDidWriteTerminalData: Event; + } + + //#endregion + + //#region Terminal dimensions property and change event https://github.com/microsoft/vscode/issues/55718 /** * An [event](#Event) which fires when a [Terminal](#Terminal)'s dimensions change. @@ -796,29 +1039,11 @@ declare module 'vscode' { readonly dimensions: TerminalDimensions; } - export interface TerminalDataWriteEvent { - /** - * The [terminal](#Terminal) for which the data was written. - */ - readonly terminal: Terminal; - /** - * The data being written. - */ - readonly data: string; - } - namespace window { /** * An event which fires when the [dimensions](#Terminal.dimensions) of the terminal change. */ export const onDidChangeTerminalDimensions: Event; - - /** - * An event which fires when the terminal's pty slave pseudo-device is written to. In other - * words, this provides access to the raw data stream from the process running within the - * terminal, including VT sequences. - */ - export const onDidWriteTerminalData: Event; } export interface Terminal { @@ -840,24 +1065,6 @@ declare module 'vscode' { //#endregion - //#region mjbvz,joh: https://github.com/Microsoft/vscode/issues/43768 - export interface FileRenameEvent { - readonly oldUri: Uri; - readonly newUri: Uri; - } - - export interface FileWillRenameEvent { - readonly oldUri: Uri; - readonly newUri: Uri; - waitUntil(thenable: Thenable): void; - } - - export namespace workspace { - export const onWillRenameFile: Event; - export const onDidRenameFile: Event; - } - //#endregion - //#region Alex - OnEnter enhancement export interface OnEnterRule { /** @@ -867,16 +1074,7 @@ declare module 'vscode' { } //#endregion - //#region Tree View - - export interface TreeView { - /** - * The tree view title is initially taken from the extension package.json - * Changes to the title property will be properly reflected in the UI in the title of the view. - */ - title?: string; - } - + //#region Tree View: https://github.com/microsoft/vscode/issues/61313 /** * Label describing the [Tree item](#TreeItem) */ @@ -909,49 +1107,28 @@ declare module 'vscode' { } //#endregion - //#region CustomExecution + //#region CustomExecution: https://github.com/microsoft/vscode/issues/81007 /** - * Class used to execute an extension callback as a task. + * A task to execute */ - export class CustomExecution2 { + export class Task2 extends Task { + detail?: string; + } + + export class CustomExecution2 extends CustomExecution { /** * Constructs a CustomExecution task object. The callback will be executed the task is run, at which point the * extension should return the Pseudoterminal it will "run in". The task should wait to do further execution until * [Pseudoterminal.open](#Pseudoterminal.open) is called. Task cancellation should be handled using * [Pseudoterminal.close](#Pseudoterminal.close). When the task is complete fire * [Pseudoterminal.onDidClose](#Pseudoterminal.onDidClose). - * @param process The [Pseudoterminal](#Pseudoterminal) to be used by the task to display output. * @param callback The callback that will be called when the task is started by a user. */ - constructor(callback: () => Thenable); - } - - /** - * A task to execute - */ - export class Task2 extends Task { - /** - * Creates a new task. - * - * @param definition The task definition as defined in the taskDefinitions extension point. - * @param scope Specifies the task's scope. 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, scope: WorkspaceFolder | TaskScope.Global | TaskScope.Workspace, name: string, source: string, execution?: ProcessExecution | ShellExecution | CustomExecution2, problemMatchers?: string | string[]); - - /** - * The task's execution engine - */ - execution2?: ProcessExecution | ShellExecution | CustomExecution2; + constructor(callback: (resolvedDefinition?: TaskDefinition) => Thenable); } //#endregion - //#region Tasks + //#region Task presentation group: https://github.com/microsoft/vscode/issues/47265 export interface TaskPresentationOptions { /** * Controls whether the task is executed in a specific terminal group using split panes. @@ -960,7 +1137,7 @@ declare module 'vscode' { } //#endregion - // #region Ben - status bar item with ID and Name + //#region Status bar item with ID and Name: https://github.com/microsoft/vscode/issues/74972 export namespace window { @@ -1008,132 +1185,546 @@ declare module 'vscode' { //#endregion - // #region Ben - extension auth flow (desktop+web) + //#region Custom editors: https://github.com/microsoft/vscode/issues/77131 - export interface AppUriOptions { - payload?: { - path?: string; - query?: string; - fragment?: string; - }; + // TODO: + // - Think about where a rename would live. + // - Think about handling go to line? (add other editor options? reveal?) + // - Should we expose edits? + // - More properties from `TextDocument`? + + /** + * Defines the capabilities of a custom webview editor. + */ + interface CustomEditorCapabilities { + /** + * Defines the editing capability of a custom webview document. + * + * When not provided, the document is considered readonly. + */ + readonly editing?: CustomEditorEditingCapability; } - export namespace env { + /** + * Defines the editing capability of a custom webview editor. This allows the webview editor to hook into standard + * editor events such as `undo` or `save`. + * + * @param EditType Type of edits. + */ + interface CustomEditorEditingCapability { + /** + * Save the resource. + * + * @return Thenable signaling that the save has completed. + */ + save(): Thenable; + + /** + * Save the existing resource at a new path. + * + * @param targetResource Location to save to. + * + * @return Thenable signaling that the save has completed. + */ + saveAs(targetResource: Uri): Thenable; + + /** + * Event triggered by extensions to signal to VS Code that an edit has occurred. + */ + readonly onDidEdit: Event; /** - * Creates a Uri that - if opened in a browser - will result in a - * registered [UriHandler](#UriHandler) to fire. The handler's - * Uri will be configured with the path, query and fragment of - * [AppUriOptions](#AppUriOptions) if provided, otherwise it will be empty. + * Apply a set of edits. * - * Extensions should not make any assumptions about the resulting - * Uri and should not alter it in anyway. Rather, extensions can e.g. - * use this Uri in an authentication flow, by adding the Uri as - * callback query argument to the server to authenticate to. + * Note that is not invoked when `onDidEdit` is called because `onDidEdit` implies also updating the view to reflect the edit. * - * Note: If the server decides to add additional query parameters to the Uri - * (e.g. a token or secret), it will appear in the Uri that is passed - * to the [UriHandler](#UriHandler). + * @param edit Array of edits. Sorted from oldest to most recent. * - * **Example** of an authentication flow: - * ```typescript - * vscode.window.registerUriHandler({ - * handleUri(uri: vscode.Uri): vscode.ProviderResult { - * if (uri.path === '/did-authenticate') { - * console.log(uri.toString()); - * } - * } - * }); + * @return Thenable signaling that the change has completed. + */ + applyEdits(edits: readonly EditType[]): Thenable; + + /** + * Undo a set of edits. * - * const callableUri = await vscode.env.createAppUri({ payload: { path: '/did-authenticate' } }); - * await vscode.env.openExternal(callableUri); - * ``` + * This is triggered when a user undoes an edit or when revert is called on a file. + * + * @param edit Array of edits. Sorted from most recent to oldest. + * + * @return Thenable signaling that the change has completed. */ - export function createAppUri(options?: AppUriOptions): Thenable; + undoEdits(edits: readonly EditType[]): Thenable; + + /** + * Back up the resource in its current state. + * + * Backups are used for hot exit and to prevent data loss. Your `backup` method should persist the resource in + * its current state, i.e. with the edits applied. Most commonly this means saving the resource to disk in + * the `ExtensionContext.storagePath`. When VS Code reloads and your custom editor is opened for a resource, + * your extension should first check to see if any backups exist for the resource. If there is a backup, your + * extension should load the file contents from there instead of from the resource in the workspace. + * + * `backup` is triggered whenever an edit it made. Calls to `backup` are debounced so that if multiple edits are + * made in quick succession, `backup` is only triggered after the last one. `backup` is not invoked when + * `auto save` is enabled (since auto save already persists resource ). + * + * @param cancellation Token that signals the current backup since a new backup is coming in. It is up to your + * extension to decided how to respond to cancellation. If for example your extension is backing up a large file + * in an operation that takes time to complete, your extension may decide to finish the ongoing backup rather + * than cancelling it to ensure that VS Code has some valid backup. + */ + backup(cancellation: CancellationToken): Thenable; + } + + /** + * Represents a custom document for a custom webview editor. + * + * Custom documents are only used within a given `CustomEditorProvider`. The lifecycle of a + * `CustomDocument` is managed by VS Code. When more more references remain to a given `CustomDocument` + * then it is disposed of. + * + * @param UserDataType Type of custom object that extensions can store on the document. + */ + interface CustomDocument { + /** + * The associated viewType for this document. + */ + readonly viewType: string; + + /** + * The associated uri for this document. + */ + readonly uri: Uri; + + /** + * Event fired when there are no more references to the `CustomDocument`. + */ + readonly onDidDispose: Event; + + /** + * Custom data that an extension can store on the document. + */ + userData?: UserDataType; + + // TODO: Should we expose edits here? + // This could be helpful for tracking the life cycle of edits + } + + /** + * Provider for webview editors that use a custom data model. + * + * Custom webview editors use [`CustomDocument`](#CustomDocument) as their data model. + * This gives extensions full control over actions such as edit, save, and backup. + * + * You should use custom text based editors when dealing with binary files or more complex scenarios. For simple text + * based documents, use [`WebviewTextEditorProvider`](#WebviewTextEditorProvider) instead. + */ + export interface CustomEditorProvider { + /** + * Resolve the model for a given resource. + * + * @param document Document to resolve. + * + * @return The capabilities of the resolved document. + */ + resolveCustomDocument(document: CustomDocument): Thenable; + + /** + * Resolve a webview editor for a given resource. + * + * To resolve a webview editor, the provider must fill in its initial html content and hook up all + * the event listeners it is interested it. The provider should also take ownership of the passed in `WebviewPanel`. + * + * @param document Document for the resource being resolved. + * @param webviewPanel Webview to resolve. The provider should take ownership of this webview. + * + * @return Thenable indicating that the webview editor has been resolved. + */ + resolveCustomEditor(document: CustomDocument, webviewPanel: WebviewPanel): Thenable; + } + + /** + * Provider for text based webview editors. + * + * Text based webview editors use a [`TextDocument`](#TextDocument) as their data model. This considerably simplifies + * implementing a webview editor as it allows VS Code to handle many common operations such as + * undo and backup. The provider is responsible for synchronizing text changes between the webview and the `TextDocument`. + * + * You should use text based webview editors when dealing with text based file formats, such as `xml` or `json`. + * For binary files or more specialized use cases, see [CustomEditorProvider](#CustomEditorProvider). + */ + export interface CustomTextEditorProvider { + /** + * Resolve a webview editor for a given resource. + * + * To resolve a webview editor, the provider must fill in its initial html content and hook up all + * the event listeners it is interested it. The provider should also take ownership of the passed in `WebviewPanel`. + * + * @param document Resource being resolved. + * @param webviewPanel Webview to resolve. The provider should take ownership of this webview. + * + * @return Thenable indicating that the webview editor has been resolved. + */ + resolveCustomTextEditor(document: TextDocument, webviewPanel: WebviewPanel): Thenable; + } + + namespace window { + /** + * Register a new provider for a custom editor. + * + * @param viewType Type of the webview editor provider. This should match the `viewType` from the + * `package.json` contributions. + * @param provider Provider that resolves editors. + * @param webviewOptions Content settings for the webview panels that the provider is given. + * + * @return Disposable that unregisters the provider. + */ + export function registerCustomEditorProvider( + viewType: string, + provider: CustomEditorProvider | CustomTextEditorProvider, + webviewOptions?: WebviewPanelOptions, + ): Disposable; + } + + //#endregion + + + //#region allow QuickPicks to skip sorting: https://github.com/microsoft/vscode/issues/73904 + + export interface QuickPick extends QuickInput { + /** + * An optional flag to sort the final results by index of first query match in label. Defaults to true. + */ + sortByLabel: boolean; + } + + //#endregion + + //#region Allow theme icons in hovers: https://github.com/microsoft/vscode/issues/84695 + + export interface MarkdownString { + + /** + * Indicates that this markdown string can contain [ThemeIcons](#ThemeIcon), e.g. `$(zap)`. + */ + readonly supportThemeIcons?: boolean; } //#endregion - // #region Ben - UIKind + //#region color theme access /** - * Possible kinds of UI that can use extensions. + * Represents a color theme kind. */ - export enum UIKind { + export enum ColorThemeKind { + Light = 1, + Dark = 2, + HighContrast = 3 + } + + /** + * Represents a color theme. + */ + export interface ColorTheme { + + /** + * The kind of this color theme: light, dark or high contrast. + */ + readonly kind: ColorThemeKind; + } + export namespace window { /** - * Extensions are accessed from a desktop application. + * The currently active color theme as configured in the settings. The active + * theme can be changed via the `workbench.colorTheme` setting. */ - Desktop = 1, + export let activeColorTheme: ColorTheme; /** - * Extensions are accessed from a web browser. + * An [event](#Event) which fires when the active theme changes or one of it's colors chnage. */ - Web = 2 + export const onDidChangeActiveColorTheme: Event; } - export namespace env { + //#endregion + + //#region https://github.com/microsoft/vscode/issues/39441 + + export interface CompletionItem { /** - * The UI kind property indicates from which UI extensions - * are accessed from. For example, extensions could be accessed - * from a desktop application or a web browser. + * Will be merged into CompletionItem#label */ - export const uiKind: UIKind; + label2?: CompletionItemLabel; + } + + export interface CompletionItemLabel { + /** + * The function or variable. Rendered leftmost. + */ + name: string; + + /** + * The signature without the return type. Render after `name`. + */ + signature?: string; + + /** + * The fully qualified name, like package name or file path. Rendered after `signature`. + */ + qualifier?: string; + + /** + * The return-type of a function or type of a property/variable. Rendered rightmost. + */ + type?: string; } //#endregion - //#region Custom editors, mjbvz - export interface WebviewEditor extends WebviewPanel { + //#region eamodio - timeline: https://github.com/microsoft/vscode/issues/84297 + + export class TimelineItem { + /** + * A timestamp (in milliseconds since 1 January 1970 00:00:00) for when the timeline item occurred. + */ + timestamp: number; + + /** + * A human-readable string describing the timeline item. + */ + label: string; + + /** + * Optional id for the timeline item. It must be unique across all the timeline items provided by this source. + * + * If not provided, an id is generated using the timeline item's timestamp. + */ + id?: string; + + /** + * The icon path or [ThemeIcon](#ThemeIcon) for the timeline item. + */ + iconPath?: Uri | { light: Uri; dark: Uri } | ThemeIcon; + + /** + * A human readable string describing less prominent details of the timeline item. + */ + description?: string; + + /** + * The tooltip text when you hover over the timeline item. + */ + detail?: string; + + /** + * The [command](#Command) that should be executed when the timeline item is selected. + */ + command?: Command; + + /** + * Context value of the timeline item. This can be used to contribute specific actions to the item. + * For example, a timeline item is given a context value as `commit`. When contributing actions to `timeline/item/context` + * using `menus` extension point, you can specify context value for key `timelineItem` in `when` expression like `timelineItem == commit`. + * ``` + * "contributes": { + * "menus": { + * "timeline/item/context": [ + * { + * "command": "extension.copyCommitId", + * "when": "timelineItem == commit" + * } + * ] + * } + * } + * ``` + * This will show the `extension.copyCommitId` action only for items where `contextValue` is `commit`. + */ + contextValue?: string; + + /** + * @param label A human-readable string describing the timeline item + * @param timestamp A timestamp (in milliseconds since 1 January 1970 00:00:00) for when the timeline item occurred + */ + constructor(label: string, timestamp: number); } - export interface WebviewEditorProvider { + export interface TimelineChangeEvent { + /** + * The [uri](#Uri) of the resource for which the timeline changed. + * If the [uri](#Uri) is `undefined` that signals that the timeline source for all resources changed. + */ + uri?: Uri; + + /** + * A flag which indicates whether the entire timeline should be reset. + */ + reset?: boolean; + } + + export interface Timeline { + readonly paging?: { + /** + * A set of provider-defined cursors specifing the range of timeline items returned. + */ + readonly cursors: { + readonly before: string; + readonly after?: string + }; + + /** + * A flag which indicates whether there are more items that weren't returned. + */ + readonly more?: boolean; + } + /** - * Fills out a `WebviewEditor` for a given resource. - * - * The provider should take ownership of passed in `editor`. + * An array of [timeline items](#TimelineItem). + */ + readonly items: readonly TimelineItem[]; + } + + export interface TimelineOptions { + /** + * A provider-defined cursor specifing the range of timeline items that should be returned. + */ + cursor?: string; + + /** + * A flag to specify whether the timeline items being requested should be before or after (default) the provided cursor. + */ + before?: boolean; + + /** + * The maximum number or the ending cursor of timeline items that should be returned. + */ + limit?: number | string; + } + + export interface TimelineProvider { + /** + * An optional event to signal that the timeline for a source has changed. + * To signal that the timeline for all resources (uris) has changed, do not pass any argument or pass `undefined`. + */ + onDidChange?: Event; + + /** + * An identifier of the source of the timeline items. This can be used to filter sources. + */ + readonly id: string; + + /** + * A human-readable string describing the source of the timeline items. This can be used as the display label when filtering sources. + */ + readonly label: string; + + /** + * Provide [timeline items](#TimelineItem) for a [Uri](#Uri). + * + * @param uri The [uri](#Uri) of the file to provide the timeline for. + * @param options A set of options to determine how results should be returned. + * @param token A cancellation token. + * @return The [timeline result](#TimelineResult) or a thenable that resolves to such. The lack of a result + * can be signaled by returning `undefined`, `null`, or an empty array. + */ + provideTimeline(uri: Uri, options: TimelineOptions, token: CancellationToken): ProviderResult; + } + + export namespace workspace { + /** + * Register a timeline provider. + * + * Multiple providers can be registered. In that case, providers are asked in + * parallel and the results are merged. A failing provider (rejected promise or exception) will + * not cause a failure of the whole operation. + * + * @param scheme A scheme or schemes that defines which documents this provider is applicable to. Can be `*` to target all documents. + * @param provider A timeline provider. + * @return A [disposable](#Disposable) that unregisters this provider when being disposed. */ - resolveWebviewEditor( - resource: Uri, - editor: WebviewEditor - ): Thenable; + export function registerTimelineProvider(scheme: string | string[], provider: TimelineProvider): Disposable; } - namespace window { - export function registerWebviewEditorProvider( - viewType: string, - provider: WebviewEditorProvider, - ): Disposable; + //#endregion + + + //#region https://github.com/microsoft/vscode/issues/90208 + + export interface ExtensionContext { + /** + * Get the uri of a resource contained in the extension. + * + * @param relativePath A relative path to a resource contained in the extension. + * @return The uri of the resource. + */ + asExtensionUri(relativePath: string): Uri; + } + + export interface Extension { + /** + * Get the uri of a resource contained in the extension. + * + * @param relativePath A relative path to a resource contained in the extension. + * @return The uri of the resource. + */ + asExtensionUri(relativePath: string): Uri; } //#endregion - // #region asExternalUri — mjbvz + //#region https://github.com/microsoft/vscode/issues/86788 - namespace env { + export interface CodeActionProviderMetadata { /** - * Resolves an *external* uri, such as a `http:` or `https:` link, from where the extension is running to a - * uri to the same resource on the client machine. + * Static documentation for a class of code actions. * - * This is a no-op if the extension is running on the client machine. Currently only supports - * `https:` and `http:` uris. + * The documentation is shown in the code actions menu if either: * - * If the extension is running remotely, this function automatically establishes a port forwarding tunnel - * from the local machine to `target` on the remote and returns a local uri to the tunnel. The lifetime of - * the port fowarding tunnel is managed by VS Code and the tunnel can be closed by the user. + * - Code actions of `kind` are requested by VS Code. In this case, VS Code will show the documentation that + * most closely matches the requested code action kind. For example, if a provider has documentation for + * both `Refactor` and `RefactorExtract`, when the user requests code actions for `RefactorExtract`, + * VS Code will use the documentation for `RefactorExtract` intead of the documentation for `Refactor`. * - * Extensions should not cache the result of `asExternalUri` as the resolved uri may become invalid due to - * a system or user action — for example, in remote cases, a user may close a port forwardng tunnel - * that was opened by `asExternalUri`. + * - Any code actions of `kind` are returned by the provider. + */ + readonly documentation?: ReadonlyArray<{ readonly kind: CodeActionKind, readonly command: Command }>; + } + + //#endregion + + //#region Dialog title: https://github.com/microsoft/vscode/issues/82871 + + /** + * 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: Explicitly setting `canSelectFiles` and `canSelectFolders` to `false` is futile + * and the editor then silently adjusts the options to select files. + */ + export interface OpenDialogOptions { + /** + * Dialog title. * - * Note: uris passed through `openExternal` are automatically resolved and you should not call `asExternalUri` - * on them. + * Depending on the underlying operating system this parameter might be ignored, since some + * systems do not present title on open dialogs. + */ + title?: string; + } + + /** + * Options to configure the behaviour of a file save dialog. + */ + export interface SaveDialogOptions { + /** + * Dialog title. * - * @return A uri that can be used on the client machine. + * Depending on the underlying operating system this parameter might be ignored, since some + * systems do not present title on save dialogs. */ - export function asExternalUri(target: Uri): Thenable; + title?: string; } //#endregion