Align window.createTerminal API with VSCode (#10683)

* Align window.createTerminal API with VSCode * Add `since` to `deprecated` annotation Deprecated PseudoTerminalOptions and created ExternalTerminalOptions to align with VSCode API. Contributed on behalf of STMicroelectronics.
eclipse-theia · Jan 31, 2022 · be4eba9 · be4eba9
1 parent b00dc83
commit be4eba9
Show file tree

Hide file tree

Showing 4 changed files with 38 additions and 3 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,13 @@
 # Change Log
 
+## v1.23.0 - 2/24/2022
+
+[1.23.0 Milestone](https://github.com/eclipse-theia/theia/milestone/31)
+
+<a name="breaking_changes_1.23.0">[Breaking Changes:](#breaking_changes_1.23.0)</a>
+
+- [plugin] Deprecated `PseudoTerminalOptions`. `ExternalTerminalOptions` should be used from now on instead. [#10683](https://github.com/eclipse-theia/theia/pull/10683) - Contributed on behalf of STMicroelectronics
+
 ## v1.22.0 - 1/27/2022
 
 [1.22.0 Milestone](https://github.com/eclipse-theia/theia/milestone/30)

diff --git a/packages/plugin-ext/src/plugin/plugin-context.ts b/packages/plugin-ext/src/plugin/plugin-context.ts
@@ -416,7 +416,9 @@ export function createAPIFactory(
             onDidChangeWindowState(listener, thisArg?, disposables?): theia.Disposable {
                 return windowStateExt.onDidChangeWindowState(listener, thisArg, disposables);
             },
-            createTerminal(nameOrOptions: theia.TerminalOptions | theia.PseudoTerminalOptions | (string | undefined), shellPath?: string, shellArgs?: string[]): theia.Terminal {
+            createTerminal(nameOrOptions: theia.TerminalOptions | theia.PseudoTerminalOptions | theia.ExtensionTerminalOptions | (string | undefined),
+                shellPath?: string,
+                shellArgs?: string[]): theia.Terminal {
                 return terminalExt.createTerminal(nameOrOptions, shellPath, shellArgs);
             },
             onDidCloseTerminal,

diff --git a/packages/plugin-ext/src/plugin/terminal-ext.ts b/packages/plugin-ext/src/plugin/terminal-ext.ts
@@ -14,7 +14,7 @@
  * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
  ********************************************************************************/
 import { UUID } from '@theia/core/shared/@phosphor/coreutils';
-import { Terminal, TerminalOptions, PseudoTerminalOptions } from '@theia/plugin';
+import { Terminal, TerminalOptions, PseudoTerminalOptions, ExtensionTerminalOptions } from '@theia/plugin';
 import { TerminalServiceExt, TerminalServiceMain, PLUGIN_RPC_CONTEXT } from '../common/plugin-api-rpc';
 import { RPCProtocol } from '../common/rpc-protocol';
 import { Event, Emitter } from '@theia/core/lib/common/event';
@@ -54,7 +54,7 @@ export class TerminalServiceExtImpl implements TerminalServiceExt {
         return [...this._terminals.values()];
     }
 
-    createTerminal(nameOrOptions: TerminalOptions | PseudoTerminalOptions | (string | undefined), shellPath?: string, shellArgs?: string[]): Terminal {
+    createTerminal(nameOrOptions: TerminalOptions | PseudoTerminalOptions | ExtensionTerminalOptions | (string | undefined), shellPath?: string, shellArgs?: string[]): Terminal {
         let options: TerminalOptions;
         let pseudoTerminal: theia.Pseudoterminal | undefined = undefined;
         const id = `plugin-terminal-${UUID.uuid4()}`;

diff --git a/packages/plugin/src/theia.d.ts b/packages/plugin/src/theia.d.ts
@@ -2745,6 +2745,7 @@ export module '@theia/plugin' {
 
     /**
      * Options a virtual process terminal.
+     * @deprecated since 1.23.0 - Use [ExtensionTerminalOptions](#ExtensionTerminalOptions) instead.
      */
     export interface PseudoTerminalOptions {
         /**
@@ -2759,6 +2760,22 @@ export module '@theia/plugin' {
         pty: Pseudoterminal;
     }
 
+    /**
+     * Options a virtual process terminal.
+     */
+    export interface ExtensionTerminalOptions {
+        /**
+         * The name of the terminal.
+         */
+        name: string;
+
+        /**
+         * An implementation of [Pseudoterminal](#Pseudoterminal) where an extension can
+         * control it.
+         */
+        pty: Pseudoterminal;
+    }
+
     /**
      * Defines the interface of a terminal pty, enabling extensions to control a terminal.
      */
@@ -4439,6 +4456,14 @@ export module '@theia/plugin' {
          */
         export function createTerminal(options: PseudoTerminalOptions): Terminal;
 
+        /**
+         * Creates a pseudo where an extension controls its input and output.
+         *
+         * @param options ExtensionTerminalOptions.
+         * @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.