From e65c542a0747be5ffd24ec78ef087af071fe5ba8 Mon Sep 17 00:00:00 2001 From: Alex Ross Date: Wed, 9 Oct 2019 17:29:14 +0200 Subject: [PATCH] Add title to treeview sample --- tree-view-sample/package.json | 4 + tree-view-sample/src/testView.ts | 6 + tree-view-sample/vscode.proposed.d.ts | 1116 +++++++++---------------- 3 files changed, 414 insertions(+), 712 deletions(-) diff --git a/tree-view-sample/package.json b/tree-view-sample/package.json index 4039c10d..3dfeaec8 100644 --- a/tree-view-sample/package.json +++ b/tree-view-sample/package.json @@ -135,6 +135,10 @@ { "command": "testView.reveal", "title": "Test View: Reveal" + }, + { + "command": "testView.changeTitle", + "title": "Test View: Change Title" } ], "menus": { diff --git a/tree-view-sample/src/testView.ts b/tree-view-sample/src/testView.ts index 4d5c2ae1..2a9a9bd7 100644 --- a/tree-view-sample/src/testView.ts +++ b/tree-view-sample/src/testView.ts @@ -10,6 +10,12 @@ export class TestView { await view.reveal({ key }, { focus: true, select: false, expand: true }); } }); + vscode.commands.registerCommand('testView.changeTitle', async () => { + const title = await vscode.window.showInputBox({ prompt: 'Type the new title for the Test View', placeHolder: view.title }); + if (title) { + view.title = title; + } + }); } } diff --git a/tree-view-sample/vscode.proposed.d.ts b/tree-view-sample/vscode.proposed.d.ts index 1f376c0f..03314c7b 100644 --- a/tree-view-sample/vscode.proposed.d.ts +++ b/tree-view-sample/vscode.proposed.d.ts @@ -16,62 +16,91 @@ declare module 'vscode' { - //#region Joh - ExecutionContext - // THIS is a deprecated proposal - export enum ExtensionExecutionContext { - Local = 1, - Remote = 2 - } - export interface ExtensionContext { - executionContext: ExtensionExecutionContext; - } - //#endregion - //#region Joh - call hierarchy - export enum CallHierarchyDirection { - CallsFrom = 1, - CallsTo = 2, + /** + * Symbol tags are extra annotations that tweak the rendering of a symbol. + */ + export enum SymbolTag { + + /** + * Render a symbol as obsolete, usually using a strike-out. + */ + Deprecated = 1 } export class CallHierarchyItem { - kind: SymbolKind; + /** + * The name of this item. + */ name: string; + + /** + * The kind of this item. + */ + kind: SymbolKind; + + /** + * Tags for this item. + */ + tags?: ReadonlyArray; + + /** + * More detail for this item, e.g. the signature of a function. + */ detail?: string; + + /** + * The resource identifier of this item. + */ uri: Uri; + + /** + * The range enclosing this symbol not including leading/trailing whitespace but everything else, e.g. comments and code. + */ range: Range; + + /** + * 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). + */ selectionRange: Range; constructor(kind: SymbolKind, name: string, detail: string, uri: Uri, range: Range, selectionRange: Range); } + export class CallHierarchyIncomingCall { + source: CallHierarchyItem; + sourceRanges: Range[]; + constructor(item: CallHierarchyItem, sourceRanges: Range[]); + } + + export class CallHierarchyOutgoingCall { + sourceRanges: Range[]; + target: CallHierarchyItem; + constructor(item: CallHierarchyItem, sourceRanges: Range[]); + } + export interface CallHierarchyItemProvider { /** - * Given a document and position compute a call hierarchy item. This is justed as - * anchor for call hierarchy and then `resolveCallHierarchyItem` is being called. + * Provide a list of callers for the provided item, e.g. all function calling a function. */ - provideCallHierarchyItem( - document: TextDocument, - position: Position, - token: CancellationToken - ): ProviderResult; + provideCallHierarchyIncomingCalls(document: TextDocument, position: Position, token: CancellationToken): ProviderResult; /** - * Resolve a call hierarchy item, e.g. compute all calls from or to a function. - * The result is an array of item/location-tuples. The location in the returned tuples - * is always relative to the "caller" with the caller either being the provided item or - * the returned item. - * - * @param item A call hierarchy item previously returned from `provideCallHierarchyItem` or `resolveCallHierarchyItem` - * @param direction Resolve calls from a function or calls to a function - * @param token A cancellation token + * Provide a list of calls for the provided item, e.g. all functions call from a function. */ - resolveCallHierarchyItem( - item: CallHierarchyItem, - direction: CallHierarchyDirection, - token: CancellationToken - ): ProviderResult<[CallHierarchyItem, Location[]][]>; + 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 namespace languages { @@ -94,6 +123,12 @@ declare module 'vscode' { constructor(host: string, port: number); } + export interface ResolvedOptions { + extensionHostEnv?: { [key: string]: string | null }; + } + + export type ResolverResult = ResolvedAuthority & ResolvedOptions; + export class RemoteAuthorityResolverError extends Error { static NotAvailable(message?: string, handled?: boolean): RemoteAuthorityResolverError; static TemporarilyNotAvailable(message?: string): RemoteAuthorityResolverError; @@ -102,7 +137,7 @@ declare module 'vscode' { } export interface RemoteAuthorityResolver { - resolve(authority: string, context: RemoteAuthorityResolverContext): ResolvedAuthority | Thenable; + resolve(authority: string, context: RemoteAuthorityResolverContext): ResolverResult | Thenable; } export interface ResourceLabelFormatter { @@ -561,25 +596,17 @@ declare module 'vscode' { //#region Joh: decorations - //todo@joh -> make class - export interface DecorationData { + export class Decoration { letter?: string; title?: string; color?: ThemeColor; priority?: number; bubble?: boolean; - source?: string; // hacky... we should remove it and use equality under the hood - } - - export interface SourceControlResourceDecorations { - source?: string; - letter?: string; - color?: ThemeColor; } export interface DecorationProvider { onDidChangeDecorations: Event; - provideDecoration(uri: Uri, token: CancellationToken): ProviderResult; + provideDecoration(uri: Uri, token: CancellationToken): ProviderResult; } export namespace window { @@ -600,6 +627,56 @@ 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 @@ -713,418 +790,139 @@ declare module 'vscode' { //#endregion - //#region Comments - /** - * Comments provider related APIs are still in early stages, they may be changed significantly during our API experiments. - */ - - interface CommentInfo { - /** - * All of the comment threads associated with the document. - */ - threads: CommentThread[]; - - /** - * The ranges of the document which support commenting. - */ - commentingRanges?: Range[]; - - /** - * If it's in draft mode or not - */ - inDraftMode?: boolean; - } - - /** - * A comment is displayed within the editor or the Comments Panel, depending on how it is provided. - */ - export interface Comment { - /** - * The display name of the user who created the comment - */ - readonly userName: string; - - /** - * The icon path for the user who created the comment - */ - readonly userIconPath?: Uri; - - /** - * The id of the comment - * - * @deprecated Use Id instead - */ - readonly commentId: string; - - /** - * @deprecated Use userIconPath instead. The avatar src of the user who created the comment - */ - gravatar?: string; - - /** - * Whether the current user has permission to edit the comment. - * - * This will be treated as false if the comment is provided by a `WorkspaceCommentProvider`, or - * if it is provided by a `DocumentCommentProvider` and no `editComment` method is given. - * - * DEPRECATED, use editCommand - */ - canEdit?: boolean; - - /** - * Whether the current user has permission to delete the comment. - * - * This will be treated as false if the comment is provided by a `WorkspaceCommentProvider`, or - * if it is provided by a `DocumentCommentProvider` and no `deleteComment` method is given. - * - * DEPRECATED, use deleteCommand - */ - canDelete?: boolean; - - /** - * @deprecated - * The command to be executed if the comment is selected in the Comments Panel - */ - command?: Command; - - /** - * Deprecated - */ - isDraft?: boolean; - - /** - * The command to be executed when users try to delete the comment - */ - deleteCommand?: Command; - - /** - * Proposed Comment Reaction - */ - commentReactions?: CommentReaction[]; - } - - /** - * Deprecated - */ - export interface CommentThreadChangedEvent { - /** - * Added comment threads. - */ - readonly added: ReadonlyArray; - - /** - * Removed comment threads. - */ - readonly removed: ReadonlyArray; - - /** - * Changed comment threads. - */ - readonly changed: ReadonlyArray; - - /** - * Changed draft mode - */ - readonly inDraftMode: boolean; - } - - /** - * Comment Reactions - * Stay in proposed. - */ - interface CommentReaction { - readonly hasReacted?: boolean; - } - - /** - * DEPRECATED - */ - interface DocumentCommentProvider { - /** - * Provide the commenting ranges and comment threads for the given document. The comments are displayed within the editor. - */ - provideDocumentComments(document: TextDocument, token: CancellationToken): Promise; - - /** - * Called when a user adds a new comment thread in the document at the specified range, with body text. - */ - createNewCommentThread(document: TextDocument, range: Range, text: string, token: CancellationToken): Promise; - - /** - * Called when a user replies to a new comment thread in the document at the specified range, with body text. - */ - replyToCommentThread(document: TextDocument, range: Range, commentThread: CommentThread, text: string, token: CancellationToken): Promise; - - /** - * Called when a user edits the comment body to the be new text. - */ - editComment?(document: TextDocument, comment: Comment, text: string, token: CancellationToken): Promise; - - /** - * Called when a user deletes the comment. - */ - deleteComment?(document: TextDocument, comment: Comment, token: CancellationToken): Promise; - - startDraft?(document: TextDocument, token: CancellationToken): Promise; - deleteDraft?(document: TextDocument, token: CancellationToken): Promise; - finishDraft?(document: TextDocument, token: CancellationToken): Promise; - - startDraftLabel?: string; - deleteDraftLabel?: string; - finishDraftLabel?: string; - - addReaction?(document: TextDocument, comment: Comment, reaction: CommentReaction): Promise; - deleteReaction?(document: TextDocument, comment: Comment, reaction: CommentReaction): Promise; - reactionGroup?: CommentReaction[]; - - /** - * Notify of updates to comment threads. - */ - onDidChangeCommentThreads: Event; - } - - /** - * DEPRECATED - */ - interface WorkspaceCommentProvider { - /** - * Provide all comments for the workspace. Comments are shown within the comments panel. Selecting a comment - * from the panel runs the comment's command. - */ - provideWorkspaceComments(token: CancellationToken): Promise; - - /** - * Notify of updates to comment threads. - */ - onDidChangeCommentThreads: Event; - } - - /** - * Stay in proposed - */ - export interface CommentReactionProvider { - availableReactions: CommentReaction[]; - toggleReaction?(document: TextDocument, comment: Comment, reaction: CommentReaction): Promise; - } - - export interface CommentThread { - /** - * The uri of the document the thread has been created on. - */ - readonly resource: Uri; - - /** - * Optional additonal commands. - * - * `additionalCommands` are the secondary actions rendered on Comment Widget. - */ - additionalCommands?: Command[]; - - /** - * The command to be executed when users try to delete the comment thread. Currently, this is only called - * when the user collapses a comment thread that has no comments in it. - */ - deleteCommand?: Command; - } - - - export interface CommentController { - /** - * Optional reaction provider - * Stay in proposed. - */ - reactionProvider?: CommentReactionProvider; - } - - namespace workspace { - /** - * DEPRECATED - * Use vscode.comment.createCommentController instead. - */ - export function registerDocumentCommentProvider(provider: DocumentCommentProvider): Disposable; - /** - * DEPRECATED - * Use vscode.comment.createCommentController instead and we don't differentiate document comments and workspace comments anymore. - */ - export function registerWorkspaceCommentProvider(provider: WorkspaceCommentProvider): Disposable; - } - - /** - * A collection of [comments](#Comment) representing a conversation at a particular range in a document. - */ - export interface CommentThread { - /** - * A unique identifier of the comment thread. - */ - readonly id: string; - - /** - * The uri of the document the thread has been created on. - */ - readonly uri: Uri; - - /** - * Optional accept input command - * - * `acceptInputCommand` is the default action rendered on Comment Widget, which is always placed rightmost. - * This command will be invoked when users the user accepts the value in the comment editor. - * This command will disabled when the comment editor is empty. - */ - acceptInputCommand?: Command; - } - - /** - * A comment is displayed within the editor or the Comments Panel, depending on how it is provided. - */ - export interface Comment { - /** - * The id of the comment - */ - id: string; - - /** - * The command to be executed if the comment is selected in the Comments Panel - */ - selectCommand?: Command; - - /** - * The command to be executed when users try to save the edits to the comment - */ - editCommand?: Command; - } - - /** - * The comment input box in Comment Widget. - */ - export interface CommentInputBox { - /** - * Setter and getter for the contents of the comment input box - */ - value: string; - } - - /** - * Commenting range provider for a [comment controller](#CommentController). - */ - export interface CommentingRangeProvider { - /** - * Provide a list of ranges which allow new comment threads creation or null for a given document - */ - provideCommentingRanges(document: TextDocument, token: CancellationToken): ProviderResult; - } - - export interface EmptyCommentThreadFactory { - /** - * The method `createEmptyCommentThread` is called when users attempt to create new comment thread from the gutter or command palette. - * Extensions still need to call `createCommentThread` inside this call when appropriate. - */ - createEmptyCommentThread(document: TextDocument, range: Range): ProviderResult; - } - - /** - * A comment controller is able to provide [comments](#CommentThread) support to the editor and - * provide users various ways to interact with comments. - */ - export interface CommentController { - - /** - * The active [comment input box](#CommentInputBox) or `undefined`. The active `inputBox` is the input box of - * the comment thread widget that currently has focus. It's `undefined` when the focus is not in any CommentInputBox. - */ - readonly inputBox?: CommentInputBox; - - /** - * Create a [comment thread](#CommentThread). The comment thread will be displayed in visible text editors (if the resource matches) - * and Comments Panel once created. - * - * @param id An `id` for the comment thread. - * @param resource The uri of the document the thread has been created on. - * @param range The range the comment thread is located within the document. - * @param comments The ordered comments of the thread. - */ - createCommentThread(id: string, resource: Uri, range: Range, comments: Comment[]): CommentThread; - - /** - * Optional new comment thread factory. - */ - emptyCommentThreadFactory?: EmptyCommentThreadFactory; - - /** - * Optional reaction provider - */ - reactionProvider?: CommentReactionProvider; - - /** - * Dispose this comment controller. - * - * Once disposed, all [comment threads](#CommentThread) created by this comment controller will also be removed from the editor - * and Comments Panel. - */ - dispose(): void; - } - - namespace comment { - /** - * Creates a new [comment controller](#CommentController) instance. - * - * @param id An `id` for the comment controller. - * @param label A human-readable string for the comment controller. - * @return An instance of [comment controller](#CommentController). - */ - export function createCommentController(id: string, label: string): CommentController; - } - - //#endregion //#region Terminal - /** - * An [event](#Event) which fires when a [Terminal](#Terminal)'s dimensions change. +/** + * Defines the interface of a terminal pty, enabling extensions to control a terminal. */ - export interface TerminalDimensionsChangeEvent { + interface Pseudoterminal { /** - * The [terminal](#Terminal) for which the dimensions have changed. + * An event that when fired will write data to the terminal. Unlike + * [Terminal.sendText](#Terminal.sendText) which sends text to the underlying _process_ + * (the pty "slave"), this will write the text to the terminal itself (the pty "master"). + * + * **Example:** Write red text to the terminal + * ```typescript + * const writeEmitter = new vscode.EventEmitter(); + * const pty: vscode.Pseudoterminal = { + * onDidWrite: writeEmitter.event, + * open: () => writeEmitter.fire('\x1b[31mHello world\x1b[0m'), + * close: () => {} + * }; + * vscode.window.createTerminal({ name: 'My terminal', pty }); + * ``` + * + * **Example:** Move the cursor to the 10th row and 20th column and write an asterisk + * ```typescript + * writeEmitter.fire('\x1b[10;20H*'); + * ``` */ - readonly terminal: Terminal; - /** - * The new value for the [terminal's dimensions](#Terminal.dimensions). - */ - readonly dimensions: TerminalDimensions; - } - - namespace window { - /** - * An event which fires when the [dimensions](#Terminal.dimensions) of the terminal change. - */ - export const onDidChangeTerminalDimensions: Event; - } - - export interface Terminal { - /** - * The current dimensions of the terminal. This will be `undefined` immediately after the - * terminal is created as the dimensions are not known until shortly after the terminal is - * created. - */ - readonly dimensions: TerminalDimensions | undefined; + onDidWrite: Event; /** - * 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. + * An event that when fired allows overriding the [dimensions](#Terminal.dimensions) of the + * terminal. Note that when set, the overridden dimensions will only take effect when they + * are lower than the actual dimensions of the terminal (ie. there will never be a scroll + * bar). Set to `undefined` for the terminal to go back to the regular dimensions (fit to + * the size of the panel). + * + * **Example:** Override the dimensions of a terminal to 20 columns and 10 rows + * ```typescript + * const dimensionsEmitter = new vscode.EventEmitter(); + * const pty: vscode.Pseudoterminal = { + * onDidWrite: writeEmitter.event, + * onDidOverrideDimensions: dimensionsEmitter.event, + * open: () => { + * dimensionsEmitter.fire({ + * columns: 20, + * rows: 10 + * }); + * }, + * close: () => {} + * }; + * vscode.window.createTerminal({ name: 'My terminal', pty }); + * ``` */ - readonly onDidWriteData: Event; - } + onDidOverrideDimensions?: Event; - - export interface TerminalOptions { /** - * When enabled the terminal will run the process as normal but not be surfaced to the user - * until `Terminal.show` is called. The typical usage for this is when you need to run - * something that may need interactivity but only want to tell the user about it when - * interaction is needed. Note that the terminals will still be exposed to all extensions - * as normal. + * An event that when fired will signal that the pty is closed and dispose of the terminal. + * + * A number can be used to provide an exit code for the terminal. Exit codes must be + * positive and a non-zero exit codes signals failure which shows a notification for a + * regular terminal and allows dependent tasks to proceed when used with the + * `CustomExecution2` API. + * + * **Example:** Exit the terminal when "y" is pressed, otherwise show a notification. + * ```typescript + * const writeEmitter = new vscode.EventEmitter(); + * const closeEmitter = new vscode.EventEmitter(); + * const pty: vscode.Pseudoterminal = { + * onDidWrite: writeEmitter.event, + * onDidClose: closeEmitter.event, + * open: () => writeEmitter.fire('Press y to exit successfully'), + * close: () => {}, + * handleInput: data => { + * if (data !== 'y') { + * vscode.window.showInformationMessage('Something went wrong'); + * } + * closeEmitter.fire(); + * } + * }; + * vscode.window.createTerminal({ name: 'Exit example', pty }); */ - runInBackground?: boolean; + onDidClose?: Event; + + /** + * Implement to handle when the pty is open and ready to start firing events. + * + * @param initialDimensions The dimensions of the terminal, this will be undefined if the + * terminal panel has not been opened before this is called. + */ + open(initialDimensions: TerminalDimensions | undefined): void; + + /** + * Implement to handle when the terminal is closed by an act of the user. + */ + close(): void; + + /** + * Implement to handle incoming keystrokes in the terminal or when an extension calls + * [Terminal.sendText](#Terminal.sendText). `data` contains the keystrokes/text serialized into + * their corresponding VT sequence representation. + * + * @param data The incoming data. + * + * **Example:** Echo input in the terminal. The sequence for enter (`\r`) is translated to + * CRLF to go to a new line and move the cursor to the start of the line. + * ```typescript + * const writeEmitter = new vscode.EventEmitter(); + * const pty: vscode.Pseudoterminal = { + * onDidWrite: writeEmitter.event, + * open: () => {}, + * close: () => {}, + * handleInput: data => writeEmitter.fire(data === '\r' ? '\r\n' : data) + * }; + * vscode.window.createTerminal({ name: 'Local echo', pty }); + * ``` + */ + handleInput?(data: string): void; + + /** + * Implement to handle when the number of rows and columns that fit into the terminal panel + * changes, for example when font size changes or when the panel is resized. The initial + * state of a terminal's dimensions should be treated as `undefined` until this is triggered + * as the size of a terminal isn't know until it shows up in the user interface. + * + * When dimensions are overridden by + * [onDidOverrideDimensions](#Pseudoterminal.onDidOverrideDimensions), `setDimensions` will + * continue to be called with the regular panel dimensions, allowing the extension continue + * to react dimension changes. + * + * @param dimensions The new dimensions. + */ + setDimensions?(dimensions: TerminalDimensions): void; } /** @@ -1143,257 +941,51 @@ declare module 'vscode' { } /** - * Represents a terminal without a process where all interaction and output in the terminal is - * controlled by an extension. This is similar to an output window but has the same VT sequence - * compatibility as the regular terminal. - * - * Note that an instance of [Terminal](#Terminal) will be created when a TerminalRenderer is - * created with all its APIs available for use by extensions. When using the Terminal object - * of a TerminalRenderer it acts just like normal only the extension that created the - * TerminalRenderer essentially acts as a process. For example when an - * [Terminal.onDidWriteData](#Terminal.onDidWriteData) listener is registered, that will fire - * when [TerminalRenderer.write](#TerminalRenderer.write) is called. Similarly when - * [Terminal.sendText](#Terminal.sendText) is triggered that will fire the - * [TerminalRenderer.onDidAcceptInput](#TerminalRenderer.onDidAcceptInput) event. - * - * @deprecated Use [virtual processes](#TerminalVirtualProcess) instead. - * - * **Example:** Create a terminal renderer, show it and write hello world in red - * ```typescript - * const renderer = window.createTerminalRenderer('foo'); - * renderer.terminal.then(t => t.show()); - * renderer.write('\x1b[31mHello world\x1b[0m'); - * ``` + * An [event](#Event) which fires when a [Terminal](#Terminal)'s dimensions change. */ - export interface TerminalRenderer { + export interface TerminalDimensionsChangeEvent { /** - * The name of the terminal, this will appear in the terminal selector. - * @deprecated Use [virtual processes](#TerminalVirtualProcess) instead. - */ - name: string; - - /** - * The dimensions of the terminal, the rows and columns of the terminal can only be set to - * a value smaller than the maximum value, if this is undefined the terminal will auto fit - * to the maximum value [maximumDimensions](TerminalRenderer.maximumDimensions). - * - * @deprecated Use [virtual processes](#TerminalVirtualProcess) instead. - * - * **Example:** Override the dimensions of a TerminalRenderer to 20 columns and 10 rows - * ```typescript - * terminalRenderer.dimensions = { - * cols: 20, - * rows: 10 - * }; - * ``` - */ - dimensions: TerminalDimensions | undefined; - - /** - * The maximum dimensions of the terminal, this will be undefined immediately after a - * terminal renderer is created and also until the terminal becomes visible in the UI. - * Listen to [onDidChangeMaximumDimensions](TerminalRenderer.onDidChangeMaximumDimensions) - * to get notified when this value changes. - * - * @deprecated Use [virtual processes](#TerminalVirtualProcess) instead. - */ - readonly maximumDimensions: TerminalDimensions | undefined; - - /** - * The corresponding [Terminal](#Terminal) for this TerminalRenderer. - * - * @deprecated Use [virtual processes](#TerminalVirtualProcess) instead. + * The [terminal](#Terminal) for which the dimensions have changed. */ readonly terminal: Terminal; - /** - * Write text to the terminal. Unlike [Terminal.sendText](#Terminal.sendText) which sends - * text to the underlying _process_, this will write the text to the terminal itself. - * - * @param text The text to write. - * @deprecated Use [virtual processes](#TerminalVirtualProcess) instead. - * - * **Example:** Write red text to the terminal - * ```typescript - * terminalRenderer.write('\x1b[31mHello world\x1b[0m'); - * ``` - * - * **Example:** Move the cursor to the 10th row and 20th column and write an asterisk - * ```typescript - * terminalRenderer.write('\x1b[10;20H*'); - * ``` + * The new value for the [terminal's dimensions](#Terminal.dimensions). */ - write(text: string): void; - - /** - * An event which fires on keystrokes in the terminal or when an extension calls - * [Terminal.sendText](#Terminal.sendText). Keystrokes are converted into their - * corresponding VT sequence representation. - * - * @deprecated Use [virtual processes](#TerminalVirtualProcess) instead. - * - * **Example:** Simulate interaction with the terminal from an outside extension or a - * workbench command such as `workbench.action.terminal.runSelectedText` - * ```typescript - * const terminalRenderer = window.createTerminalRenderer('test'); - * terminalRenderer.onDidAcceptInput(data => { - * console.log(data); // 'Hello world' - * }); - * terminalRenderer.terminal.sendText('Hello world'); - * ``` - */ - readonly onDidAcceptInput: Event; - - /** - * An event which fires when the [maximum dimensions](#TerminalRenderer.maximumDimensions) of - * the terminal renderer change. - * - * @deprecated Use [virtual processes](#TerminalVirtualProcess) instead. - */ - readonly onDidChangeMaximumDimensions: Event; + readonly dimensions: TerminalDimensions; } - export namespace window { + export interface TerminalDataWriteEvent { /** - * Create a [TerminalRenderer](#TerminalRenderer). - * - * @param name The name of the terminal renderer, this shows up in the terminal selector. - * @deprecated Use [virtual processes](#TerminalVirtualProcess) instead. + * The [terminal](#Terminal) for which the data was written. */ - export function createTerminalRenderer(name: string): TerminalRenderer; + readonly terminal: Terminal; + /** + * The data being written. + */ + readonly data: string; } - //#endregion - - //#region Terminal virtual process - - export namespace window { + namespace window { /** - * Creates a [Terminal](#Terminal) where an extension acts as the process. - * - * @param options A [TerminalVirtualProcessOptions](#TerminalVirtualProcessOptions) object describing the - * characteristics of the new terminal. - * @return A new Terminal. + * An event which fires when the [dimensions](#Terminal.dimensions) of the terminal change. */ - export function createTerminal(options: TerminalVirtualProcessOptions): Terminal; + 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; } - /** - * Value-object describing what options a virtual process terminal should use. - */ - export interface TerminalVirtualProcessOptions { + export interface Terminal { /** - * A human-readable string which will be used to represent the terminal in the UI. + * The current dimensions of the terminal. This will be `undefined` immediately after the + * terminal is created as the dimensions are not known until shortly after the terminal is + * created. */ - name: string; - - /** - * An implementation of [TerminalVirtualProcess](#TerminalVirtualProcess) that allows an - * extension to act as a terminal's backing process. - */ - virtualProcess: TerminalVirtualProcess; - } - - /** - * Defines the interface of a terminal virtual process, enabling extensions to act as a process - * in the terminal. - */ - interface TerminalVirtualProcess { - /** - * An event that when fired will write data to the terminal. Unlike - * [Terminal.sendText](#Terminal.sendText) which sends text to the underlying _process_, - * this will write the text to the terminal itself. - * - * **Example:** Write red text to the terminal - * ```typescript - * const writeEmitter = new vscode.EventEmitter(); - * const virtualProcess: TerminalVirtualProcess = { - * onDidWrite: writeEmitter.event - * }; - * vscode.window.createTerminal({ name: 'My terminal', virtualProcess }); - * writeEmitter.fire('\x1b[31mHello world\x1b[0m'); - * ``` - * - * **Example:** Move the cursor to the 10th row and 20th column and write an asterisk - * ```typescript - * writeEmitter.fire('\x1b[10;20H*'); - * ``` - */ - onDidWrite: Event; - - /** - * An event that when fired allows overriding the [dimensions](#Terminal.dimensions) of the - * terminal. Note that when set the overridden dimensions will only take effect when they - * are lower than the actual dimensions of the terminal (ie. there will never be a scroll - * bar). Set to `undefined` for the terminal to go back to the regular dimensions. - * - * **Example:** Override the dimensions of a terminal to 20 columns and 10 rows - * ```typescript - * const dimensionsEmitter = new vscode.EventEmitter(); - * const virtualProcess: TerminalVirtualProcess = { - * onDidWrite: writeEmitter.event, - * onDidOverrideDimensions: dimensionsEmitter.event - * }; - * vscode.window.createTerminal({ name: 'My terminal', virtualProcess }); - * dimensionsEmitter.fire({ - * columns: 20, - * rows: 10 - * }); - * ``` - */ - onDidOverrideDimensions?: Event; - - /** - * An event that when fired will exit the process with an exit code, this will behave the - * same for a virtual process as when a regular process exits with an exit code. - * - * **Example:** Exit with an exit code of `0` if the y key is pressed, otherwise `1`. - * ```typescript - * const writeEmitter = new vscode.EventEmitter(); - * const exitEmitter = new vscode.EventEmitter(); - * const virtualProcess: TerminalVirtualProcess = { - * onDidWrite: writeEmitter.event, - * input: data => exitEmitter.fire(data === 'y' ? 0 : 1) - * }; - * vscode.window.createTerminal({ name: 'Exit example', virtualProcess }); - * writeEmitter.fire('Press y to exit successfully'); - */ - onDidExit?: Event; - - /** - * Implement to handle keystrokes in the terminal or when an extension calls - * [Terminal.sendText](#Terminal.sendText). Keystrokes are converted into their - * corresponding VT sequence representation. - * - * @param data The sent data. - * - * **Example:** Echo input in the terminal. The sequence for enter (`\r`) is translated to - * CRLF to go to a new line and move the cursor to the start of the line. - * ```typescript - * const writeEmitter = new vscode.EventEmitter(); - * const virtualProcess: TerminalVirtualProcess = { - * onDidWrite: writeEmitter.event, - * input: data => writeEmitter.fire(data === '\r' ? '\r\n' : data) - * }; - * vscode.window.createTerminal({ name: 'Local echo', virtualProcess }); - * ``` - */ - input?(data: string): void; - - /** - * Implement to handle when the number of rows and columns that fit into the terminal panel - * changes, for example when font size changes or when the panel is resized. The initial - * state of a terminal's dimensions should be treated as `undefined` until this is triggered - * as the size of a terminal isn't know until it shows up in the user interface. - * - * @param dimensions The new dimensions. - */ - setDimensions?(dimensions: TerminalDimensions): void; - - /** - * Implement to handle when the terminal shuts down by an act of the user. - */ - shutdown?(): void; + readonly dimensions: TerminalDimensions | undefined; } //#endregion @@ -1436,12 +1028,17 @@ declare module 'vscode' { //#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; /** * An optional human-readable message that will be rendered in the view. + * Setting the message to null, undefined, or empty string will remove the message from the view. */ - message?: string | MarkdownString; - + message?: string; } /** @@ -1476,22 +1073,21 @@ declare module 'vscode' { } //#endregion + //#region CustomExecution /** * Class used to execute an extension callback as a task. */ - export class CustomExecution { + export class CustomExecution2 { /** - * @param callback The callback that will be called when the extension callback task is executed. + * 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: (terminalRenderer: TerminalRenderer, cancellationToken: CancellationToken, thisArg?: any) => Thenable); - - /** - * The callback used to execute the task. - * @param terminalRenderer Used by the task to render output and receive input. - * @param cancellationToken Cancellation used to signal a cancel request to the executing task. - * @returns The callback should return '0' for success and a non-zero value for failure. - */ - callback: (terminalRenderer: TerminalRenderer, cancellationToken: CancellationToken, thisArg?: any) => Thenable; + constructor(callback: () => Thenable); } /** @@ -1510,13 +1106,14 @@ declare module 'vscode' { * 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 | CustomExecution, problemMatchers?: string | string[]); + 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 | CustomExecution; + execution2?: ProcessExecution | ShellExecution | CustomExecution2; } + //#endregion //#region Tasks export interface TaskPresentationOptions { @@ -1575,37 +1172,132 @@ declare module 'vscode' { //#endregion - //#region Webview Resource Roots + // #region Ben - extension auth flow (desktop+web) + + export interface AppUriOptions { + payload?: { + path?: string; + query?: string; + fragment?: string; + }; + } + + export namespace env { - export interface Webview { /** - * Root url from which local resources are loaded inside of webviews. + * 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. * - * This is `vscode-resource:` when vscode is run on the desktop. When vscode is run - * on the web, this points to a server endpoint. + * 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: 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). + * + * **Example** of an authentication flow: + * ```typescript + * vscode.window.registerUriHandler({ + * handleUri(uri: vscode.Uri): vscode.ProviderResult { + * if (uri.path === '/did-authenticate') { + * console.log(uri.toString()); + * } + * } + * }); + * + * const callableUri = await vscode.env.createAppUri({ payload: { path: '/did-authenticate' } }); + * await vscode.env.openExternal(callableUri); + * ``` */ - readonly resourceRoot: Thenable; + export function createAppUri(options?: AppUriOptions): Thenable; } //#endregion + // #region Ben - UIKind - //#region Joh - read/write files of any scheme + /** + * Possible kinds of UI that can use extensions. + */ + export enum UIKind { - export interface FileSystem { - stat(uri: Uri): Thenable; - readDirectory(uri: Uri): Thenable<[string, FileType][]>; - createDirectory(uri: Uri): Thenable; - readFile(uri: Uri): Thenable; - writeFile(uri: Uri, content: Uint8Array, options?: { create: boolean, overwrite: boolean }): Thenable; - delete(uri: Uri, options?: { recursive: boolean }): Thenable; - rename(source: Uri, target: Uri, options?: { overwrite: boolean }): Thenable; - copy(source: Uri, target: Uri, options?: { overwrite: boolean }): Thenable; + /** + * Extensions are accessed from a desktop application. + */ + Desktop = 1, + + /** + * Extensions are accessed from a web browser. + */ + Web = 2 } - export namespace workspace { + export namespace env { - export const fs: FileSystem; + /** + * 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. + */ + export const uiKind: UIKind; + } + + //#endregion + + //#region Custom editors, mjbvz + + export interface WebviewEditor extends WebviewPanel { + } + + export interface WebviewEditorProvider { + /** + * Fills out a `WebviewEditor` for a given resource. + * + * The provider should take ownership of passed in `editor`. + */ + resolveWebviewEditor( + resource: Uri, + editor: WebviewEditor + ): Thenable; + } + + namespace window { + export function registerWebviewEditorProvider( + viewType: string, + provider: WebviewEditorProvider, + ): Disposable; + } + + //#endregion + + // #region asExternalUri — mjbvz + + namespace env { + /** + * 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. + * + * This is a no-op if the extension is running on the client machine. Currently only supports + * `https:` and `http:` uris. + * + * 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. + * + * 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`. + * + * Note: uris passed through `openExternal` are automatically resolved and you should not call `asExternalUri` + * on them. + * + * @return A uri that can be used on the client machine. + */ + export function asExternalUri(target: Uri): Thenable; } //#endregion