Skip to content

Change TerminalRenderer API to "Extension Terminal" #70978

@Tyriar

Description

@Tyriar

Initially proposed in #67923 (comment), the TerminalRenderer API will be be deprecated and replaced by a simpler to understand model where an extension implements a "virtual process," essentially acting as a complete replacement for the terminal's process.

export function createTerminal(options: TerminalOptions | TerminalVirtualProcessOptions): Terminal;

export interface TerminalVirtualProcessOptions {
	// For a name property for TerminalVirtualProcessOptions.
	// Note that this is mandatory here as there's no process/shell to grab the title from
	name: string;

	virtualProcess: TerminalVirtualProcess;

	// Allows Windows or non-Windows local link handler to be used based on Live Share host OS
	os?: OperatingSystem;

	// Allows ~ to be resolved in Live Share
	userHome?: string;
}

interface TerminalVirtualProcess {
	// The ext should fire this when they want to write to the terminal
	write: Event<string>;

	// Lets the extension override the dimensions of the terminal
	overrideDimensions?: Event<TerminalDimensions>;

	// Lets the extension exit the process with an exit code, this was not in the TerminalRenderer
	// API but it makes sense to include this as it's the main thing missing for a virtual process
	// to truly act like a process
	exit?: Event<number>;

	// This will be called when the user types
	onDidAcceptInput?(text: string): void;

	// This is called fire when window.onDidChangeTerminalDimensions fires as CustomExecution need
	// access to the "maximum" dimensions and don't want access to Terminal
	onDidChangeDimensions?(dimensions: TerminalDimensions): void;
}

export class CustomExecution {
	constructor(virtualProcess: TerminalVirtualProcess, callback: (cancellationToken: CancellationToken, thisArg?: any) => Thenable<number>);
	callback: (cancellationToken: CancellationToken, thisArg?: any) => Thenable<number>;
}

Example usage:

const writeEmitter: EventEmitter<string>();
const virtualProcess: TerminalVirtualProcess = {
	write: writeEmitter.event,
	onDidAcceptInput: (data) => {
		// do something with typed input
		writeEmitter.fire('echo: ' + data);
	}
};
const terminal = createTerminal({
  name: 'my process',
  virtualProcess
});
writeEmitter.fire('writing to the terminal');
setTimeout(() => {
	terminal.dispose();
}, 5000);

Some of #67923 might need to be pulled over as there was a lot of work in that PR.

Metadata

Metadata

Assignees

Labels

apiapi-proposalfeature-requestRequest for new features or functionalityon-testplanterminalGeneral terminal issues that don't fall under another label

Type

No type

Projects

No projects

Milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions