@theia/plugin 1.30.0-next.8 → 1.30.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theia/plugin",
-  "version": "1.30.0-next.8+03b8549f933",
+  "version": "1.30.0",
   "description": "Theia - Plugin API",
   "types": "./src/theia.d.ts",
   "publishConfig": {
@@ -27,10 +27,10 @@
     "watch": "theiaext watch"
   },
   "devDependencies": {
-    "@theia/ext-scripts": "1.29.0"
+    "@theia/ext-scripts": "1.30.0"
   },
   "nyc": {
     "extends": "../../configs/nyc.json"
   },
-  "gitHead": "03b8549f933e12ec577f235c281902da66be25e4"
+  "gitHead": "1b32ca5626bb8252143b7a6ad6b513410f49366e"
 }

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;
     }
 
     /**
@@ -1712,6 +1727,11 @@ export module '@theia/plugin' {
      */
     export interface FileWillCreateEvent {
 
+        /**
+         * A cancellation token.
+         */
+        readonly token: CancellationToken;
+
         /**
          * The files that are going to be created.
          */
@@ -1767,6 +1787,11 @@ export module '@theia/plugin' {
      */
     export interface FileWillDeleteEvent {
 
+        /**
+         * A cancellation token.
+         */
+        readonly token: CancellationToken;
+
         /**
          * The files that are going to be deleted.
          */
@@ -1822,6 +1847,11 @@ export module '@theia/plugin' {
      */
     export interface FileWillRenameEvent {
 
+        /**
+         * A cancellation token.
+         */
+        readonly token: CancellationToken;
+
         /**
          * The files that are going to be renamed.
          */
@@ -2074,7 +2104,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
@@ -2186,35 +2216,63 @@ export module '@theia/plugin' {
      * Represents an item that can be selected from a list of items.
      */
     export interface QuickPickItem {
+
+        /**
+         * A human-readable string which is rendered prominent. Supports rendering of {@link ThemeIcon theme icons} via
+         * the `$(<name>)`-syntax.
+         */
+        label: string;
+
         /**
          * Defaults to {@link QuickPickItemKind.Default}. If set to {@link QUickPickItemKind.Separator}, the item will not be displayed as a row but only as a separator,
          * and all fields other than {@link QuickPickItem.label label} will be ignored.
          */
         kind?: QuickPickItemKind;
-        /**
-         * The item label
-         */
-        label: string;
 
         /**
-         * The item description
+         * A human-readable string which is rendered less prominent in the same line. Supports rendering of
+         * {@link ThemeIcon theme icons} via the `$(<name>)`-syntax.
+         *
+         * Note: this property is ignored when {@link QuickPickItem.kind kind} is set to {@link QuickPickItemKind.Separator}
          */
         description?: string;
 
         /**
-         * The item detail
+         * A human-readable string which is rendered less prominent in a separate line. Supports rendering of
+         * {@link ThemeIcon theme icons} via the `$(<name>)`-syntax.
+         *
+         * Note: this property is ignored when {@link QuickPickItem.kind kind} is set to {@link QuickPickItemKind.Separator}
          */
         detail?: string;
 
         /**
-         * Used for [QuickPickOptions.canPickMany](#QuickPickOptions.canPickMany)
-         * not implemented yet
+         * Optional flag indicating if this item is picked initially. This is only honored when using
+         * the {@link window.showQuickPick()} API. To do the same thing with the {@link window.createQuickPick()} API,
+         * simply set the {@link QuickPick.selectedItems} to the items you want picked initially.
+         * (*Note:* This is only honored when the picker allows multiple selections.)
+         *
+         * @see {@link QuickPickOptions.canPickMany}
+         *
+         * Note: this property is ignored when {@link QuickPickItem.kind kind} is set to {@link QuickPickItemKind.Separator}
          */
         picked?: boolean;
+
         /**
          * Always show this item.
+         *
+         * Note: this property is ignored when {@link QuickPickItem.kind kind} is set to {@link QuickPickItemKind.Separator}
          */
         alwaysShow?: boolean;
+
+        /**
+         * Optional buttons that will be rendered on this particular item. These buttons will trigger
+         * an {@link QuickPickItemButtonEvent} when clicked. Buttons are only rendered when using a quickpick
+         * created by the {@link window.createQuickPick()} API. Buttons are not rendered when using
+         * the {@link window.showQuickPick()} API.
+         *
+         * Note: this property is ignored when {@link QuickPickItem.kind kind} is set to {@link QuickPickItemKind.Separator}
+         */
+        buttons?: readonly QuickInputButton[];
     }
 
     /**
@@ -2267,6 +2325,12 @@ export module '@theia/plugin' {
          */
         readonly onDidTriggerButton: Event<QuickInputButton>;
 
+        /**
+         * An event signaling when a button in a particular {@link QuickPickItem} was triggered.
+         * This event does not fire for buttons in the title bar.
+         */
+        readonly onDidTriggerItemButton: Event<QuickPickItemButtonEvent<T>>;
+
         /**
          * Items to pick from.
          */
@@ -2782,6 +2846,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 +3061,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 +3164,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 +4440,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 +4678,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 +4688,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 +4716,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 +4726,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 +4754,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 +4764,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.
@@ -5064,6 +5167,21 @@ export module '@theia/plugin' {
         private constructor();
     }
 
+    /**
+     * An event signaling when a button in a particular {@link QuickPickItem} was triggered.
+     * This event does not fire for buttons in the title bar.
+     */
+    export interface QuickPickItemButtonEvent<T extends QuickPickItem> {
+        /**
+         * The button that was clicked.
+         */
+        readonly button: QuickInputButton;
+        /**
+         * The item that the button belongs to.
+         */
+        readonly item: T;
+    }
+
     /**
      * A concrete {@link QuickInput QuickInput} to let the user input a text value.
      *
@@ -5402,7 +5520,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 +5587,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.
@@ -7522,6 +7640,12 @@ export module '@theia/plugin' {
      * [Folding](https://code.visualstudio.com/docs/editor/codebasics#_folding) in the editor.
      */
     export interface FoldingRangeProvider {
+
+        /**
+         * An optional event to signal that the folding ranges from this provider have changed.
+         */
+        onDidChangeFoldingRanges?: Event<void>;
+
         /**
          * Returns a list of folding ranges or null and undefined if the provider
          * does not want to participate or was cancelled.
@@ -8324,7 +8448,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 +8464,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>;
     }
 
     /**
@@ -8551,11 +8675,34 @@ export module '@theia/plugin' {
         intersects(other: CodeActionKind): boolean;
     }
 
+    /**
+     * The reason why code actions were requested.
+     */
+    export enum CodeActionTriggerKind {
+        /**
+         * Code actions were explicitly requested by the user or by an extension.
+         */
+        Invoke = 1,
+
+        /**
+         * Code actions were requested automatically.
+         *
+         * This typically happens when current selection in a file changes, but can
+         * also be triggered when file content changes.
+         */
+        Automatic = 2,
+    }
+
     /**
      * Contains additional diagnostic information about the context in which
      * a {@link CodeActionProvider.provideCodeActions code action} is run.
      */
     export interface CodeActionContext {
+        /**
+         * The reason why code actions were requested.
+         */
+        readonly triggerKind: CodeActionTriggerKind;
+
         /**
          * An array of diagnostics.
          */
@@ -8938,7 +9085,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.