@theia/plugin 1.30.0-next.3 → 1.30.0-next.31

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theia/plugin",
-  "version": "1.30.0-next.3+9e5db775675",
+  "version": "1.30.0-next.31+f4a536f44",
   "description": "Theia - Plugin API",
   "types": "./src/theia.d.ts",
   "publishConfig": {
@@ -32,5 +32,5 @@
   "nyc": {
     "extends": "../../configs/nyc.json"
   },
-  "gitHead": "9e5db7756755fe2cc4155f59fda27f32b3d5bbe4"
+  "gitHead": "f4a536f445b550e5ca7b803c3a73bd6eebffb335"
 }

package/src/theia.d.ts

@@ -227,7 +227,12 @@ export module '@theia/plugin' {
     }
 
     /**
-     * Represents a line and character position.
+     * Represents a line and character position, such as
+     * the position of the cursor.
+     *
+     * Position objects are __immutable__. Use the {@link Position.with with} or
+     * {@link Position.translate translate} methods to derive new positions
+     * from an existing position.
      */
     export class Position {
 
@@ -241,6 +246,10 @@ export module '@theia/plugin' {
          */
         readonly character: number;
 
+        /**
+         * @param line A zero-based line value.
+         * @param character A zero-based character value.
+         */
         constructor(line: number, character: number);
 
         /**
@@ -315,7 +324,7 @@ export module '@theia/plugin' {
          * @return A position that reflects the given delta. Will return `this` position if the change
          * is not changing anything.
          */
-        translate(change: { lineDelta?: number; characterDelta?: number; }): Position;
+        translate(change: { lineDelta?: number; characterDelta?: number }): Position;
 
         /**
          * Create a new position derived from this position.
@@ -333,7 +342,7 @@ export module '@theia/plugin' {
          * @return A position that reflects the given change. Will return `this` position if the change
          * is not changing anything.
          */
-        with(change: { line?: number; character?: number; }): Position;
+        with(change: { line?: number; character?: number }): Position;
     }
 
     /**
@@ -410,15 +419,21 @@ export module '@theia/plugin' {
         /**
          * Derived a new range from this range.
          *
-         * @param start
-         * @param end
+         * @param start A position that should be used as start. The default value is the {@link Range.start current start}.
+         * @param end A position that should be used as end. The default value is the {@link Range.end current end}.
+         * @return A range derived from this range with the given start and end position.
+         * If start and end are not different `this` range will be returned.
          */
         with(start?: Position, end?: Position): Range;
 
         /**
          * Derived a new range from this range.
+         *
+         * @param change An object that describes a change to this range.
+         * @return A range that reflects the given change. Will return `this` range if the change
+         * is not changing anything.
          */
-        with(change: { start?: Position, end?: Position }): Range;
+        with(change: { start?: Position; end?: Position }): Range;
     }
 
     /**
@@ -2074,7 +2089,7 @@ export module '@theia/plugin' {
          * Fire the event and pass data object
          * @param data
          */
-        fire(data?: T): void;
+        fire(data: T): void;
 
         /**
          * Dispose this object
@@ -2782,6 +2797,16 @@ export module '@theia/plugin' {
          */
         clear(): void;
 
+        /**
+         * Reveal this channel in the UI.
+         *
+         * @deprecated Use the overload with just one parameter (`show(preserveFocus?: boolean): void`).
+         *
+         * @param column This argument is **deprecated** and will be ignored.
+         * @param preserveFocus When `true` the channel will not take focus.
+         */
+        show(column?: ViewColumn, preserveFocus?: boolean): void;
+
         /**
          * Reveal this channel in the UI.
          *
@@ -2987,6 +3012,15 @@ export module '@theia/plugin' {
          */
         env?: { [key: string]: string | null };
 
+        /**
+         * Whether the terminal process environment should be exactly as provided in
+         * `TerminalOptions.env`. When this is false (default), the environment will be based on the
+         * window's environment and also apply configured platform settings like
+         * `terminal.integrated.windows.env` on top. When this is true, the complete environment
+         * must be provided as nothing will be inherited from the process or any configuration.
+         */
+        strictEnv?: boolean;
+
         /**
          * A message to write to the terminal on first launch. Note that this is not sent to the
          * process, but rather written directly to the terminal. This supports escape sequences such
@@ -3081,6 +3115,26 @@ export module '@theia/plugin' {
          */
         onDidClose?: Event<void | number>;
 
+        /**
+         * An event that when fired allows changing the name of the terminal.
+         *
+         * Events fired before {@link Pseudoterminal.open} is called will be be ignored.
+         *
+         * **Example:** Change the terminal name to "My new terminal".
+         * ```typescript
+         * const writeEmitter = new vscode.EventEmitter<string>();
+         * const changeNameEmitter = new vscode.EventEmitter<string>();
+         * const pty: vscode.Pseudoterminal = {
+         *   onDidWrite: writeEmitter.event,
+         *   onDidChangeName: changeNameEmitter.event,
+         *   open: () => changeNameEmitter.fire('My new terminal'),
+         *   close: () => {}
+         * };
+         * vscode.window.createTerminal({ name: 'My terminal', pty });
+         * ```
+         */
+        onDidChangeName?: Event<string>;
+
         /**
          * Implement to handle when the pty is opened.
          *
@@ -4337,7 +4391,7 @@ export module '@theia/plugin' {
          *
          * Note that hiding a view using the context menu instead disposes of the view and fires `onDidDispose`.
          */
-        readonly onDidChangeVisibility: Event<boolean>;
+        readonly onDidChangeVisibility: Event<void>;
 
         /**
          * Reveal the view in the UI.
@@ -4575,7 +4629,7 @@ export module '@theia/plugin' {
          * @param items A set of items that will be rendered as actions in the message.
          * @return A promise that resolves to the selected item or `undefined` when being dismissed.
          */
-        export function showInformationMessage(message: string, ...items: string[]): Thenable<string | undefined>;
+        export function showInformationMessage<T extends string>(message: string, ...items: T[]): Thenable<T | undefined>;
 
         /**
          * Show an information message.
@@ -4585,7 +4639,7 @@ export module '@theia/plugin' {
          * @param items A set of items that will be rendered as actions in the message.
          * @return A promise that resolves to the selected item or `undefined` when being dismissed.
          */
-        export function showInformationMessage(message: string, options: MessageOptions, ...items: string[]): Thenable<string | undefined>;
+        export function showInformationMessage<T extends string>(message: string, options: MessageOptions, ...items: T[]): Thenable<T | undefined>;
 
         /**
          * Show an information message.
@@ -4613,7 +4667,7 @@ export module '@theia/plugin' {
          * @param items A set of items that will be rendered as actions in the message.
          * @return A promise that resolves to the selected item or `undefined` when being dismissed.
          */
-        export function showWarningMessage(message: string, ...items: string[]): Thenable<string | undefined>;
+        export function showWarningMessage<T extends string>(message: string, ...items: T[]): Thenable<T | undefined>;
 
         /**
          * Show a warning message.
@@ -4623,7 +4677,7 @@ export module '@theia/plugin' {
          * @param items A set of items that will be rendered as actions in the message.
          * @return A promise that resolves to the selected item or `undefined` when being dismissed.
          */
-        export function showWarningMessage(message: string, options: MessageOptions, ...items: string[]): Thenable<string | undefined>;
+        export function showWarningMessage<T extends string>(message: string, options: MessageOptions, ...items: T[]): Thenable<T | undefined>;
 
         /**
          * Show a warning message.
@@ -4651,7 +4705,7 @@ export module '@theia/plugin' {
          * @param items A set of items that will be rendered as actions in the message.
          * @return A promise that resolves to the selected item or `undefined` when being dismissed.
          */
-        export function showErrorMessage(message: string, ...items: string[]): Thenable<string | undefined>;
+        export function showErrorMessage<T extends string>(message: string, ...items: T[]): Thenable<T | undefined>;
 
         /**
          * Show an error message.
@@ -4661,7 +4715,7 @@ export module '@theia/plugin' {
          * @param items A set of items that will be rendered as actions in the message.
          * @return A promise that resolves to the selected item or `undefined` when being dismissed.
          */
-        export function showErrorMessage(message: string, options: MessageOptions, ...items: string[]): Thenable<string | undefined>;
+        export function showErrorMessage<T extends string>(message: string, options: MessageOptions, ...items: T[]): Thenable<T | undefined>;
 
         /**
          * Show an error message.
@@ -5402,7 +5456,7 @@ export module '@theia/plugin' {
          * This will trigger the view to update the changed element/root and its children recursively (if shown).
          * To signal that root has changed, do not pass any argument or pass `undefined` or `null`.
          */
-        onDidChangeTreeData?: Event<T | undefined | null>;
+        onDidChangeTreeData?: Event<T | T[] | undefined | null | void>;
 
         /**
          * Get {@link TreeItem TreeItem} representation of the `element`
@@ -5469,7 +5523,7 @@ export module '@theia/plugin' {
         /**
          * The tooltip text when you hover over this item.
          */
-        tooltip?: string | undefined;
+        tooltip?: string | MarkdownString | undefined;
 
         /**
          * The {@link Command command} which should be run when the tree item is selected.
@@ -8324,7 +8378,7 @@ export module '@theia/plugin' {
          * @return An array of commands, quick fixes, or refactorings or a thenable of such. The lack of a result can be
          * signaled by returning `undefined`, `null`, or an empty array.
          */
-        provideCodeActions(document: TextDocument, range: Range | Selection, context: CodeActionContext, token: CancellationToken | undefined): ProviderResult<(Command | T)[]>;
+        provideCodeActions(document: TextDocument, range: Range | Selection, context: CodeActionContext, token: CancellationToken): ProviderResult<(Command | T)[]>;
 
         /**
          * Given a code action fill in its `edit`-property. Changes to
@@ -8340,7 +8394,7 @@ export module '@theia/plugin' {
          * @return The resolved code action or a thenable that resolves to such. It is OK to return the given
          * `item`. When no result is returned, the given `item` will be used.
          */
-        resolveCodeAction?(codeAction: T, token: CancellationToken | undefined): ProviderResult<T>;
+        resolveCodeAction?(codeAction: T, token: CancellationToken): ProviderResult<T>;
     }
 
     /**
@@ -8938,7 +8992,7 @@ export module '@theia/plugin' {
          * @param tokenType The token type.
          * @param tokenModifiers The token modifiers.
          */
-        push(range: Range, tokenType: string, tokenModifiers?: string[]): void;
+        push(range: Range, tokenType: string, tokenModifiers?: readonly string[]): void;
 
         /**
          * Finish and create a `SemanticTokens` instance.