diff --git a/src/vs/vscode.d.ts b/src/vs/vscode.d.ts index 8f84919720eff5bd5af43084fa6e05bfa9fa4ec8..875f9d9696ca4a6d88ae64215c7e3a678f61680c 100644 --- a/src/vs/vscode.d.ts +++ b/src/vs/vscode.d.ts @@ -6855,6 +6855,15 @@ declare module 'vscode' { */ export function createTerminal(options: TerminalOptions): Terminal; + /** + * Creates a [Terminal](#Terminal) where an extension controls its input and output. + * + * @param options An [ExtensionTerminalOptions](#ExtensionTerminalOptions) object describing + * the characteristics of the new terminal. + * @return A new Terminal. + */ + export function createTerminal(options: ExtensionTerminalOptions): Terminal; + /** * Register a [TreeDataProvider](#TreeDataProvider) for the view contributed using the extension point `views`. * This will allow you to contribute data to the [TreeView](#TreeView) and update if the data changes. @@ -7208,6 +7217,169 @@ declare module 'vscode' { hideFromUser?: boolean; } + /** + * Value-object describing what options a virtual process terminal should use. + */ + export interface ExtensionTerminalOptions { + /** + * A human-readable string which will be used to represent the terminal in the UI. + */ + name: string; + + /** + * An implementation of [Pseudoterminal](#Pseudoterminal) that allows an extension to + * control a terminal. + */ + pty: Pseudoterminal; + } + + /** + * Defines the interface of a terminal pty, enabling extensions to control a terminal. + */ + interface Pseudoterminal { + /** + * 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*'); + * ``` + */ + 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 (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 }); + * ``` + */ + onDidOverrideDimensions?: Event; + + /** + * 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 }); + */ + 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; + } + + /** + * Represents the dimensions of a terminal. + */ + export interface TerminalDimensions { + /** + * The number of columns in the terminal. + */ + readonly columns: number; + + /** + * The number of rows in the terminal. + */ + readonly rows: number; + } + /** * A location in the editor at which progress information can be shown. It depends on the * location how progress is visually represented. diff --git a/src/vs/vscode.proposed.d.ts b/src/vs/vscode.proposed.d.ts index aa7cb2e45709ede61e96fd830af5ec63a4e6b9ce..1a53eed0c91d6b6f1c114d0ea7084656252913a5 100644 --- a/src/vs/vscode.proposed.d.ts +++ b/src/vs/vscode.proposed.d.ts @@ -760,184 +760,6 @@ declare module 'vscode' { readonly onDidWriteData: Event; } - /** - * Represents the dimensions of a terminal. - */ - export interface TerminalDimensions { - /** - * The number of columns in the terminal. - */ - readonly columns: number; - - /** - * The number of rows in the terminal. - */ - readonly rows: number; - } - - //#endregion - - //#region Extension terminals - - export namespace window { - /** - * Creates a [Terminal](#Terminal) where an extension controls the terminal. - * - * @param options An [ExtensionTerminalOptions](#ExtensionTerminalOptions) object describing - * the characteristics of the new terminal. - * @return A new Terminal. - */ - export function createTerminal(options: ExtensionTerminalOptions): Terminal; - } - - /** - * Value-object describing what options a virtual process terminal should use. - */ - export interface ExtensionTerminalOptions { - /** - * A human-readable string which will be used to represent the terminal in the UI. - */ - name: string; - - /** - * An implementation of [Pseudoterminal](#Pseudoterminal) that allows an extension to - * control a terminal. - */ - pty: Pseudoterminal; - } - - /** - * Defines the interface of a terminal pty, enabling extensions to control a terminal. - */ - interface Pseudoterminal { - /** - * 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*'); - * ``` - */ - 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 (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 }); - * ``` - */ - onDidOverrideDimensions?: Event; - - /** - * 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 }); - */ - 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; - } - //#endregion //#region Joh -> exclusive document filters diff --git a/src/vs/workbench/api/common/extHost.api.impl.ts b/src/vs/workbench/api/common/extHost.api.impl.ts index 63aeff4ceeffc21d98a1d471f40cb285d1a2dcd5..79317b0233f78830c9a3292a6bb7459731fff90f 100644 --- a/src/vs/workbench/api/common/extHost.api.impl.ts +++ b/src/vs/workbench/api/common/extHost.api.impl.ts @@ -512,7 +512,7 @@ export function createApiFactoryAndRegisterActors(accessor: ServicesAccessor): I } return extHostTerminalService.createTerminalFromOptions(nameOrOptions); } - return extHostTerminalService.createTerminal(nameOrOptions, shellPath, shellArgs); + return extHostTerminalService.createTerminal(nameOrOptions, shellPath, shellArgs); }, registerTreeDataProvider(viewId: string, treeDataProvider: vscode.TreeDataProvider): vscode.Disposable { return extHostTreeViews.registerTreeDataProvider(viewId, treeDataProvider, extension);