@interopio/workspaces-api 4.1.1-beta.0 → 4.1.2

package/workspaces.d.ts

@@ -167,9 +167,11 @@ export namespace IOConnectWorkspaces {
         positionIndex?: number;
 
         /**
-         * Controls the users ability to activate the Workspaces frame when the workspace is restored.
-         * *Available only in **io.Connect Desktop**.*
+         * If `true`, the Workspaces Frame instance containing the restored Workspace will be activated.
+         * This means that the Workspaces Frame window will gain focus, will be restored to its normal state (e.g., if it has been previously minimized),
+         * and will be brought in front of other existing windows.
          * Defaults to the configuration passed in the `workspaces.json` file or to `false`.
+         * *Available only in **io.Connect Desktop**.*
          */
         activateFrame?: boolean;
 
@@ -180,16 +182,54 @@ export namespace IOConnectWorkspaces {
         allowSystemHibernation?: boolean;
     }
 
-    /** An object containing the bounds of a frame */
-    export interface FrameBounds {
-        top: number;
-        left: number;
+    /**
+     * Settings for showing a previously hidden Workspaces Frame instance.
+     */
+    export interface FrameShowConfig {
+
+        /**
+         * If `true`, the Workspaces Frame instance will be activated. This means that the Workspaces Frame window will gain focus,
+         * will be restored to its normal state (e.g., if it has been previously minimized), and will be brought in front of other existing windows.
+         * @default false
+         */
+        activate?: boolean;
+    }
+
+    /**
+     * Describes the size of an io.Connect window.
+     */
+    export interface Size {
+
+        /**
+         * Window width in pixels.
+         */
         width: number;
+
+        /**
+         * Window height in pixels.
+         */
         height: number;
     }
 
+    /**
+     * Describes the bounds of a Workspaces Frame.
+     */
+    export interface FrameBounds extends Size {
+
+        /**
+         * Distance of the top left window corner from the top edge of the screen in pixels.
+         */
+        top: number;
+
+        /**
+         * Distance of the top left window corner from the left edge of the screen in pixels.
+         */
+        left: number;
+    }
+
     /** An object describing the possible settings when defining a new frame. */
     export interface NewFrameConfig {
+
         /** An object describing the possible settings when defining a new frame. */
         bounds?: {
             top?: number;
@@ -197,6 +237,15 @@ export namespace IOConnectWorkspaces {
             width?: number;
             height?: number;
         };
+
+        /**
+         * If `true`, the newly created Workspaces Frame instance will be visible.
+         * *Available only in **io.Connect Desktop**.*
+         * @since io.Connect Desktop 9.9.5
+         * @default true
+         */
+        isVisible?: boolean;
+
         /** A string which will be used as an id of the new frame. The call will reject if a frame with id already exists */
         frameId?: string;
     }
@@ -227,16 +276,16 @@ export namespace IOConnectWorkspaces {
 
     /**
      * Options for closing a Frame.
-     * *Available only for **io.Connect Desktop**.*
+     * *Available only in **io.Connect Desktop**.*
      * @since io.Connect Desktop 9.9
      */
     export interface FrameCloseOptions {
-        /** 
-         * If `true`, will allow preventing the operation for closing the Frame. 
+        /**
+         * If `true`, will allow preventing the operation for closing the Frame.
          */
         allowPrevent?: boolean;
-        /** 
-         * If `true`, will show a dialog for the user to confirm or cancel closing the Frame. 
+        /**
+         * If `true`, will show a dialog for the user to confirm or cancel closing the Frame.
          */
         showDialog?: boolean;
     }
@@ -662,9 +711,10 @@ export namespace IOConnectWorkspaces {
 
     export interface FrameTargetingOptions {
         /**
-         * If `true`, the frame will be activated when the operation is executed.
-         * *Available only in **io.Connect Desktop**.*
+         * If `true`, the targeted Workspaces Frame instance will be activated. This means that the Workspaces Frame window will gain focus,
+         * will be restored to its normal state (e.g., if it has been previously minimized), and will be brought in front of other existing windows.
          * Defaults to the configuration passed in the `workspaces.json` file or to `false`.
+         * *Available only in **io.Connect Desktop**.*
          */
         activate?: boolean;
 
@@ -827,6 +877,170 @@ export namespace IOConnectWorkspaces {
         isInitialized: boolean;
     }
 
+    /**
+     * Type of the dialog to show. Can be either a predefined io.Connect dialog type, or a custom one.
+    *
+    * - `YesNo` - dialog with "Yes" and "No" buttons;
+    * - `YesNoCancel` - dialog with "Yes", "No" and "Cancel" buttons;
+    * - `OkCancel` - dialog with "OK" and "Cancel" buttons;
+    * - `Ok` - dialog with an "OK" button;
+    * - `Custom` - custom dialog;
+    * - `SingleInputDialog` - dialog with a text input field;
+    */
+    export const enum DialogType {
+        YesNo = "YesNo",
+        YesNoCancel = "YesNoCancel",
+        OkCancel = "OkCancel",
+        Ok = "Ok",
+        Custom = "Custom",
+        SingleInputDialog = "SingleInputDialog"
+    }
+
+    /**
+     * Mode for the dialog.
+     *
+     * - `WindowContainer` - only the container (e.g., the Workspaces Frame) of the window that is showing the dialog will be blocked for user interaction.
+     * - `Global` - all visible containers (including frameless io.Connect Windows) will be blocked. All windows within a blocked container will be blocked too.
+     */
+    export const enum DialogMode {
+        WindowContainer = "WindowContainer",
+        Global = "Global"
+    }
+
+    /**
+     * Options for showing a dialog from the Workspaces Frame.
+     */
+    export interface FrameDialogOptions {
+
+        /**
+         * Mode for the dialog.
+         */
+        mode?: DialogMode;
+
+        /**
+         * Type of the dialog to show. Can be either a predefined io.Connect dialog type, or a custom one.
+         */
+        type: DialogType | string;
+
+        /**
+         * Size for the dialog to show.
+         */
+        size?: Size;
+
+        /**
+         * Message to the user that the dialog will contain.
+         */
+        message: string;
+
+        /**
+         * Title for the message that will be displayed in the dialog.
+         */
+        messageTitle?: string;
+
+        /**
+         * If `true`, the user will be able to move the dialog.
+         * @default true
+         */
+        movable?: boolean;
+
+        /**
+         * If `true`, the io.Connect Window containing the dialog will be transparent.
+         * @default false
+         */
+        transparent?: boolean;
+
+        /**
+         * Title for the dialog that will be displayed in the dialog header.
+         */
+        title?: string;
+
+        /**
+         * Context data that can be used by a custom dialog.
+         */
+        context?: unknown;
+
+        /**
+         * Name for the affirmative response button.
+         */
+        affirmativeButtonName?: string;
+
+        /**
+         * If `true`, the affirmative response button will be shown in the dialog.
+         * The default value is for custom dialogs, as predefined dialog types have different defaults.
+         * @default false
+         */
+        showAffirmativeButton?: boolean;
+
+        /**
+         * Name for the canceling button.
+         */
+        cancelButtonName?: string;
+
+        /**
+         * If `true`, the canceling button will be shown in the dialog.
+         * The default value is for custom dialogs, as predefined dialog types have different defaults.
+         * @default false
+         */
+        showCancelButton?: boolean;
+
+        /**
+         * Name for the negative response button.
+         */
+        negativeButtonName?: string;
+
+        /**
+         * If `true`, the negative response button will be shown in the dialog.
+         * The default value is for custom dialogs, predefined dialog types have different defaults.
+         * @default false
+         */
+        showNegativeButton?: boolean;
+
+        /**
+         * Determines which dialog button to be the default one.
+         * The action tied to the default button will be executed when the user presses `ENTER` when no button is active
+         * (i.e., when the buttons aren't on focus and none is selected).
+         */
+        defaultAction?: "affirmative" | "negative" | "cancel";
+
+        /**
+         * Interval in seconds after which the dialog will close automatically.
+         * If `showTimer` is set to `true`, a countdown timer will be displayed in the dialog,
+         * otherwise the dialog will close silently without a warning for the user.
+         * If the user doesn't interact with the dialog before the timer expires,
+         * the `action` property of the `DialogResult` object will be set to `"expired"`.
+         */
+        timerDuration?: number;
+
+        /**
+         * If `true`, a countdown timer will be shown in the dialog, warning the user that the dialog will close automatically after the specified time.
+         * You must also specify a value for `timerDuration`, otherwise a timer won't be shown.
+         * @default false
+         */
+        showTimer?: boolean;
+
+        /**
+         * The amount of characters that can be entered in the input field of a `SingleInputDialog`.
+         */
+        inputMaxLength?: number;
+
+        /**
+         * String pattern that serves as a regular expression for validating the input from the user in a `SingleInputDialog`.
+         * If such pattern is specified and the input doesn't match it, an error will be displayed and the input field
+         * will indicate visually that the user input is invalid.
+         */
+        inputPattern?: string;
+
+        /**
+         * Error message to be displayed if the user input doesn't match the specified validation pattern for a `SingleInputDialog`.
+         */
+        inputPatternErrorMessage?: string;
+
+        /**
+         * Placeholder that will be displayed in the input field of a `SingleInputDialog`.
+         */
+        inputPlaceholder?: string;
+    }
+
     /**
      * Describes a Frame (a Workspaces App instance).
      */
@@ -900,15 +1114,15 @@ export namespace IOConnectWorkspaces {
         init(config: FrameInitializationConfig): Promise<void>;
 
         /**
-        * Retrieves the taskbar icon of the `Frame` instance. 
-        * *Available only for **io.Connect Desktop**.*
+        * Retrieves the taskbar icon of the `Frame` instance.
+        * *Available only in **io.Connect Desktop**.*
         * @since io.Connect Desktop 9.9
         */
         getIcon(): Promise<Icon>;
 
         /**
          * Sets the taskbar icon of the `Frame` instance.
-         * *Available only for **io.Connect Desktop**.*
+         * *Available only in **io.Connect Desktop**.*
          * @param icon New icon to be displayed in the taskbar for the `Frame` instance. The icon must be encoded as a Base64 string.
          * @since io.Connect Desktop 9.9
          */
@@ -929,6 +1143,27 @@ export namespace IOConnectWorkspaces {
         */
         getConstraints(): Promise<FrameConstraints>;
 
+        /**
+         * Retrieves the current visibility state of the Workspaces Frame instance.
+         * *Available only in **io.Connect Desktop**.*
+         * @since io.Connect Desktop 9.9.5
+         */
+        isVisible(): Promise<boolean>;
+
+        /**
+         * Shows the Workspaces Frame instance if it has been previously hidden.
+         * *Available only in **io.Connect Desktop**.*
+         * @since io.Connect Desktop 9.9.5
+         */
+        show(config?: FrameShowConfig): Promise<void>;
+
+        /**
+         * Hides the Workspaces Frame instance if it's currently visible.
+         * *Available only in **io.Connect Desktop**.*
+         * @since io.Connect Desktop 9.9.5
+         */
+        hide(): Promise<void>;
+
         /**
          * Opens a new workspace in this frame by restoring a previously saved workspace layout.
          * @param name The name of a saved workspace layout, which will be restored.
@@ -943,11 +1178,18 @@ export namespace IOConnectWorkspaces {
          */
         createWorkspace(definition: WorkspaceDefinition, config?: WorkspaceCreateConfig): Promise<Workspace>;
 
-        /** 
+        /**
+         * Shows a dialog with a title, message, and response buttons to the user.
+         * *Available only in **io.Connect Desktop**.*
+         * @since io.Connect Desktop 10.0
+         */
+        showDialog<T>(options: FrameDialogOptions): Promise<T>;
+
+        /**
          * Notifies when the Frame is about to be closed.
-         * *Available only for io.Connect Desktop.* 
-         * @param callback Callback function for handling the event. Receives as an argument an object with options for closing the Frame. 
-         * @since io.Connect Desktop 9.9 
+         * *Available only in **io.Connect Desktop**.*
+         * @param callback Callback function for handling the event. Receives as an argument an object with options for closing the Frame.
+         * @since io.Connect Desktop 9.9
          */
         onClosing(callback: (options: FrameClosingData) => void | Promise<void>): Promise<Unsubscribe>;