@interopio/workspaces-api 3.5.6 → 4.0.0

package/workspaces.d.ts

@@ -7,15 +7,14 @@ export default WorkspacesFactory;
 /**
  * @docname Workspaces
  * @intro
- * The Workspaces API offers advanced window management functionalities. Using Workspaces, users are able to arrange multiple applications 
- * within the same visual window (called *Frame*). This arrangement can be performed programmatically or by dragging and dropping applications within the Frame. 
- * Users can also save Workspace Layouts and restore them within the same Frame or even in different Frames.
+ * The Workspaces API offers advanced window management functionalities. Using Workspaces, users are able to arrange multiple apps
+ * within the same visual window (called Frame or a Workspaces App). This arrangement can be performed programmatically or by dragging and dropping
+ * apps within the Frame. Users can also save Workspace Layouts and restore them within the same Frame or even in different Frames.
  *
- * The io.Connect Workspaces enable the users to compose a custom arrangement of applications by treating each application 
- * as an individual building block that can be added, removed, moved or resized within a Workspace. 
+ * The app windows in a Workspace are treated as individual building blocks that can be added, removed, moved, or resized within the Workspace.
  * The Frame can hold multiple Workspaces (as tabs) and can also be maximized, minimized or resized.
- * 
- * The Workspaces API is accessible through the `io.workspaces` object.
+ *
+ * The Workspaces API is accessible via the [`io.workspaces`](#API) object.
  */
 export namespace IOConnectWorkspaces {
 
@@ -50,7 +49,10 @@ export namespace IOConnectWorkspaces {
         /** The type of the workspace element. */
         type: "Workspace";
 
-        /** The name of the workspaces app with which the layout is associated (available only in **io.Connect Desktop**). */
+        /**
+         * The name of the workspaces app with which the layout is associated.
+         * *Available only in **io.Connect Desktop**.*
+         */
         application?: string;
 
         state: WorkspaceLayoutComponentState;
@@ -93,7 +95,7 @@ export namespace IOConnectWorkspaces {
     }
 
     export interface WindowLayoutItemConfig {
-        /** The name of the application as defined in **io.Connect Desktop**. */
+        /** The name of the application as specified in its definition. */
         appName: string;
         /** The id of the window */
         windowId?: string;
@@ -127,7 +129,10 @@ export namespace IOConnectWorkspaces {
         /** A string id of an existing frame. If provided, this workspace will be opened in that specific frame */
         frameId?: string;
 
-        /** The application name of the workspace app that should be used for the new frame (available only for **io.Connect Desktop**) */
+        /**
+         * The application name of the workspace app that should be used for the new frame.
+         * *Available only in **io.Connect Desktop**.*
+         */
         applicationName?: string;
 
         /** A setting used to declare that the workspace must be in a new frame and also provide options for that new frame */
@@ -162,7 +167,9 @@ export namespace IOConnectWorkspaces {
         positionIndex?: number;
 
         /**
-         * Controls the users ability to activate the Workspaces frame when the workspace is restored (available only for **io.Connect Desktop**). Defaults to the configuration passed in the workspaces.json or to false.
+         * Controls the users ability to activate the Workspaces frame when the workspace is restored.
+         * *Available only in **io.Connect Desktop**.*
+         * Defaults to the configuration passed in the `workspaces.json` file or to `false`.
          */
         activateFrame?: boolean;
 
@@ -218,6 +225,21 @@ export namespace IOConnectWorkspaces {
         relative?: boolean;
     }
 
+    /**
+     * Options for closing a Frame.
+     * @since io.Connect Desktop 9.9
+     */
+    export interface FrameCloseOptions {
+        /** 
+         * 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. 
+         */
+        showDialog?: boolean;
+    }
+
     /** An object containing settings applied when creating a new workspace. */
     export interface WorkspaceCreateConfig {
         /** A boolean which defines whether or not the workspace should also be saved as a layout when created. */
@@ -225,7 +247,7 @@ export namespace IOConnectWorkspaces {
     }
 
     /**
-    * The loading strategy used to open new workspaces. 
+    * The loading strategy used to open new workspaces.
     * "direct" will cause all windows to start loading at the same time as soon as the workspace loads
     * "delayed" will cause all visible/active/selected windows to start loading at the same time as soon as the workspace loads. The rest will be loaded gradually at a specific interval.
     * "lazy" will cause all visible/active/selected windows to start loading at the same time as soon as the workspace loads. The rest will start loading when the user selects them and not before that.
@@ -261,7 +283,7 @@ export namespace IOConnectWorkspaces {
         /** Position of the workspace in relation to it's siblings in the frame. */
         position?: number;
 
-        /** 
+        /**
          * Provides the opportunity to open a workspace with no tab header
          * @default false
          */
@@ -285,79 +307,80 @@ export namespace IOConnectWorkspaces {
          */
         allowDropLeft?: boolean;
 
-        /** 
+        /**
          * Controls the users ability to drop windows in the top-most zone of the workspace
          * @default true
          */
         allowDropTop?: boolean;
 
-        /** 
+        /**
          * Controls the users ability to drop windows in the right-most zone of the workspace
          * @default true
          */
         allowDropRight?: boolean;
 
-        /** 
+        /**
          * Controls the users ability to drop windows in the bottom-most zone of the workspace
          * @default true
          */
         allowDropBottom?: boolean;
 
-        /** 
+        /**
          * Controls the users ability to extract windows from the workspace
          * @default true
          */
         allowExtract?: boolean;
 
-        /** 
+        /**
          * Control the users ability to reorder windows in the workspace
          * @default true
          */
         allowWindowReorder?: boolean;
 
-        /** 
+        /**
          * Controls the visibility of the save workspace button located in the workspace tab
          * @default true
          */
         showSaveButton?: boolean;
 
-        /** 
+        /**
          * Controls whether a workspace tab can be reordered in the frame
          * @default true
          */
         allowWorkspaceTabReorder?: boolean;
 
-        /** 
-         * Controls whether a workspace tab can be extracted from the frame (available only for **io.Connect Desktop**).
+        /**
+         * Controls whether a workspace tab can be extracted from the frame.
+         * *Available only in **io.Connect Desktop**.*
          * @default true
          */
         allowWorkspaceTabExtract?: boolean;
 
-        /** 
+        /**
          * Controls the visibility of the close button located in the workspaces tab
          * @default true
          */
         showCloseButton?: boolean;
 
-        /** 
+        /**
          * Prevents the splitters for being draggable, so the windows cannot be resized
          * @default true
          */
         allowSplitters?: boolean;
 
-        /** 
+        /**
          * Controls the visibility of all close button located in the windows' tab elements
          * @default true
          */
         showWindowCloseButtons?: boolean;
 
-        /** 
+        /**
          * Controls the visibility of all eject buttons located in the groups' headers
          * @default true
          */
         showEjectButtons?: boolean;
 
-        /** 
+        /**
          * Controls the visibility of all the add window buttons (the ones with the plus icon) located in the group headers
          * @default true
          */
@@ -386,7 +409,7 @@ export namespace IOConnectWorkspaces {
         positionIndex?: number;
 
         /**
-         * Mode for dragging the windows that are part of the Workspace. If set to `"autoEject"` (available only for **io.Connect Desktop**), when the user drags a Workspace window, it will be ejected from the Workspace during the dragging operation and the user will be able to drop it back inside the Workspace, or out of the Workspace.
+         * Mode for dragging the windows that are part of the Workspace. If set to `"autoEject"` (available only in **io.Connect Desktop**), when the user drags a Workspace window, it will be ejected from the Workspace during the dragging operation and the user will be able to drop it back inside the Workspace, or out of the Workspace.
          * If set to `"keepInside"`, the window won't be ejected from the Workspace when being dragged and the user will be able to drop it only inside the Workspace.
          */
         windowDragMode?: "keepInside" | "autoEject";
@@ -434,7 +457,10 @@ export namespace IOConnectWorkspaces {
         /** Controls the whether the workspace tab can be reordered */
         allowWorkspaceTabReorder?: boolean;
 
-        /** Controls the whether the workspace tab can be extracted (available only for **io.Connect Desktop**). */
+        /**
+         * Controls the whether the workspace tab can be extracted.
+         * *Available only in **io.Connect Desktop**.*
+         */
         allowWorkspaceTabExtract?: boolean;
 
         /** Controls the visibility of all the add window buttons (the ones with the plus icon) located in the group headers */
@@ -634,13 +660,20 @@ export namespace IOConnectWorkspaces {
     }
 
     export interface FrameTargetingOptions {
-        /** If true the frame will be activated when the operation is executed (available only for **io.Connect Desktop**). Defaults to the configuration passed in the workspaces.json or to false. */
+        /**
+         * If `true`, the frame will be activated when the operation is executed.
+         * *Available only in **io.Connect Desktop**.*
+         * Defaults to the configuration passed in the `workspaces.json` file or to `false`.
+         */
         activate?: boolean;
 
         /** A string id of an existing frame. If provided, this workspace will be opened in that specific frame */
         reuseFrameId?: string;
 
-        /** The application name of the workspace app that should be used for the new frame (available only for **io.Connect Desktop**). */
+        /**
+         * The application name of the workspace app that should be used for the new frame.
+         * *Available only in **io.Connect Desktop**.*
+         */
         applicationName?: string;
 
         /** A setting used to declare that the workspace must be in a new frame and also provide options for that new frame */
@@ -740,15 +773,21 @@ export namespace IOConnectWorkspaces {
         /** An unique string name and identifier of the layout */
         name: string;
 
-        /** The name of the workspaces app with which the layout is associated (available only in **io.Connect Desktop**). */
+        /**
+         * The name of the workspaces app with which the layout is associated.
+         * *Available only in **io.Connect Desktop**.*
+         */
         applicationName?: string;
     }
 
     export interface EmptyFrameDefinition {
-        /** The application name of the workspace app that should be used for the new frame (available only for **io.Connect Desktop**). */
+        /**
+         * The application name of the workspace app that should be used for the new frame.
+         * *Available only in **io.Connect Desktop**.*
+         */
         applicationName?: string;
 
-        /**      
+        /**
          * Optional frame related settings
          */
         frameConfig?: IOConnectWorkspaces.NewFrameConfig;
@@ -758,7 +797,7 @@ export namespace IOConnectWorkspaces {
          */
         context?: object;
 
-        /**      
+        /**
          * Optional the id of the layout component which is being restored
          */
         layoutComponentId?: string;
@@ -790,7 +829,8 @@ export namespace IOConnectWorkspaces {
     /** An object describing a frame */
     export interface Frame extends FrameSummary {
         /**
-         * Registers keyboard shortcut to the current frame (available only in **io.Connect Desktop**).
+         * Registers a keyboard shortcut to the current Frame.
+         * *Available only in **io.Connect Desktop**.*
          */
         registerShortcut(shortcut: string, callback: () => void): Promise<Unsubscribe>;
 
@@ -840,10 +880,7 @@ export namespace IOConnectWorkspaces {
          */
         restore(): Promise<void>;
 
-        /**
-         * Closes this frame.
-         */
-        close(): Promise<void>;
+        close(options?: FrameCloseOptions): Promise<void>;
 
         /**
          * Initializes the frame with the provided workspaces in the config when the frame has been opened as empty
@@ -851,6 +888,21 @@ export namespace IOConnectWorkspaces {
          */
         init(config: FrameInitializationConfig): Promise<void>;
 
+        /**
+        * Retrieves the taskbar icon of the `Frame` instance. 
+        * *Available only for **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**.*
+         * @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
+         */
+        setIcon(icon: Icon): Promise<void>;
+
         /**
          * Returns an object detailing the current state of this frame.
          */
@@ -880,6 +932,14 @@ export namespace IOConnectWorkspaces {
          */
         createWorkspace(definition: WorkspaceDefinition, config?: WorkspaceCreateConfig): Promise<Workspace>;
 
+        /** 
+         * 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 
+         */
+        onClosing(callback: (options: FrameClosingData) => void | Promise<void>): Promise<Unsubscribe>;
+
         /**
          * Notifies when this frame is closed.
          * @param callback Callback function to handle the event.
@@ -908,7 +968,8 @@ export namespace IOConnectWorkspaces {
         onNormal(callback: () => void): Promise<Unsubscribe>;
 
         /**
-         * Triggered when either a window in the frame is focused or the frame itself (supported only in **io.Connect Desktop**).
+         * Triggered when either a window in the frame is focused or the frame itself.
+         * *Available only in **io.Connect Desktop**.*
          * @param callback Callback function to handle the event. It receives a data oject which indicates how the focus has changed.
          */
         onFocusChanged(callback: (data: FrameFocusChangedData) => void): Promise<IOConnectWorkspaces.Unsubscribe>;
@@ -1011,7 +1072,10 @@ export namespace IOConnectWorkspaces {
         /** Indicates if the save button for this workspace is visible to the user */
         showSaveButton?: boolean;
 
-        /** Controls whether the workspace tab can be extracted (available only for **io.Connect Desktop**) */
+        /**
+         * Controls whether the workspace tab can be extracted.
+         * *Available only in **io.Connect Desktop**.*
+         */
         allowWorkspaceTabExtract?: boolean;
 
         /** Controls whether the workspace tab can be reordered*/
@@ -1046,10 +1110,10 @@ export namespace IOConnectWorkspaces {
 
         /**
          * Indicates the loading strategy for the Workspace.
-         * *Available only for **io.Connect Desktop**.*
+         * *Available only in **io.Connect Desktop**.*
          */
         loadingStrategy?: LoadingStrategy;
-        
+
         /**
          * Indicates whether the Workspace can be hibernated via the platform configuration.
          * This setting doesn't apply to programmatic hibernation via the `hibernate()` method of a `Workspace` instance.
@@ -1111,7 +1175,7 @@ export namespace IOConnectWorkspaces {
         onContextUpdated(callback: (data: any) => void): Promise<Unsubscribe>;
 
         /**
-         * Updates this workspace reference to reflect the current state of the workspace. 
+         * Updates this workspace reference to reflect the current state of the workspace.
          */
         refreshReference(): Promise<void>;
 
@@ -1244,7 +1308,8 @@ export namespace IOConnectWorkspaces {
         lock(config?: WorkspaceLockConfig | ((config: WorkspaceLockConfig) => WorkspaceLockConfig)): Promise<void>;
 
         /**
-         * Sets the mode for dragging the windows that are part of the Workspace. *Available only for **io.Connect Desktop**.*
+         * Sets the mode for dragging the windows that are part of the Workspace.
+         * *Available only in **io.Connect Desktop**.*
          * @param mode Mode for dragging the Workspace windows. If set to `"autoEject"`, when the user drags a Workspace window, it will be ejected from the Workspace during the dragging operation and the user will be able to drop it back inside the Workspace, or out of the Workspace.
          * If set to `"keepInside"`, the window won't be ejected from the Workspace when being dragged and the user will be able to drop it only inside the Workspace.
          */
@@ -1255,7 +1320,8 @@ export namespace IOConnectWorkspaces {
          * This will override the current loading strategy for the Workspace that may have been specified via configuration or programmatically
          * when creating or restoring the Workspace. The loading strategy specified via this method will be preserved in the Workspace Layout
          * only if the Workspace is saved afterwards and the `"persistCurrentStrategy"` flag is set to `true` in the Workspaces App definition.
-         * *Available only for **io.Connect Desktop**.*
+         * *Available only in **io.Connect Desktop**.*
+         * @since io.Connect Desktop 9.8
          * @param strategy Loading strategy for the Workspace.
          */
         setLoadingStrategy(strategy: LoadingStrategy): Promise<void>;
@@ -1304,7 +1370,7 @@ export namespace IOConnectWorkspaces {
          * @param callback Callback function to handle the event. Receives the loaded window as a parameter.
          */
         onWindowLoaded(callback: (window: WorkspaceWindow) => void): Promise<Unsubscribe>;
-        /** 
+        /**
                 * Notifies when a window was maximized in this workspace and returns an unsubscribe function.
                 * A maximized window means that the window has been maximized either by an API call or from the maximize button by the user.
                 * @param callback Callback function to handle the event. Receives the maximized window as a parameter.
@@ -1330,7 +1396,7 @@ export namespace IOConnectWorkspaces {
         isPinned?: boolean;
 
         /**
-         * Mode for dragging the windows that are part of the Workspace. If set to `"autoEject"` (available only for **io.Connect Desktop**), when the user drags a Workspace window, it will be ejected from the Workspace during the dragging operation and the user will be able to drop it back inside the Workspace, or out of the Workspace.
+         * Mode for dragging the windows that are part of the Workspace. If set to `"autoEject"` (available only in **io.Connect Desktop**), when the user drags a Workspace window, it will be ejected from the Workspace during the dragging operation and the user will be able to drop it back inside the Workspace, or out of the Workspace.
          * If set to `"keepInside"`, the window won't be ejected from the Workspace when being dragged and the user will be able to drop it only inside the Workspace.
          */
         windowDragMode?: "keepInside" | "autoEject";
@@ -1358,17 +1424,19 @@ export namespace IOConnectWorkspaces {
 
         /**
          * Changes the workspace icon to the specified one
-         * @param icon 
+         * @param icon
          */
         setIcon(icon: string): Promise<void>;
 
         /**
-         * Shows the loading animation of the workspace (supported only in **io.Connect Desktop**).
+         * Shows the loading animation of the workspace.
+         * *Available only in **io.Connect Desktop**.*
          */
         showLoadingAnimation(): Promise<void>;
 
         /**
-         * Hides the loading animation of the workspace (supported only in **io.Connect Desktop**).
+         * Hides the loading animation of the workspace.
+         * *Available only in **io.Connect Desktop**.*
          */
         hideLoadingAnimation(): Promise<void>;
     }
@@ -1831,7 +1899,7 @@ export namespace IOConnectWorkspaces {
     /** A configuration object used to save a current workspace as a layout */
     export interface WorkspaceLayoutSaveConfig {
         /**
-         * A string used as name (doubles as id) of the layout, which is later used when restoring it. 
+         * A string used as name (doubles as id) of the layout, which is later used when restoring it.
          */
         name: string;
 
@@ -1872,6 +1940,16 @@ export namespace IOConnectWorkspaces {
         config: any;
     }
 
+    /**
+     * Describes the data passed to the callback for handling the event which fires when a Frame is about to be closed.
+     */
+    export interface FrameClosingData {
+        /**
+         * Function that can be used to prevent closing a Frame.
+         */
+        prevent: () => void;
+    }
+
     export interface FrameClosedData {
         frameId: string;
         frameBounds?: FrameBounds;
@@ -1887,6 +1965,16 @@ export namespace IOConnectWorkspaces {
         frameBounds?: FrameBounds;
     }
 
+    /**
+     * Describes the taskbar icon of a `Frame` instance.
+     */
+    export interface Icon {
+        /**
+         * Icon encoded as a Base64 string.
+         */
+        base64Image: string;
+    }
+
     /** An object describing the complete state of a workspace at the time when the object was created */
     export interface WorkspaceSnapshot extends WorkspaceLayoutComponentState {
         /**
@@ -1993,7 +2081,7 @@ export namespace IOConnectWorkspaces {
 
         /**
          * Returns an instance of the workspace with the passed id. The performance is better than getWorkspace when querying for a workspace by id.
-         * @param workspaceId The id of the desired workspace 
+         * @param workspaceId The id of the desired workspace
          */
         getWorkspaceById(workspaceId: string): Promise<Workspace>;
 
@@ -2032,13 +2120,13 @@ export namespace IOConnectWorkspaces {
         createWorkspace(definition: WorkspaceDefinition, saveConfig?: WorkspaceCreateConfig): Promise<Workspace>;
 
         /**
-         * 
+         *
          * @param definition Optional definition of the frame
          */
         createEmptyFrame(definition?: EmptyFrameDefinition): Promise<IOConnectWorkspaces.Frame>;
 
         /**
-         * Wait for a frame with the specified id to be loaded. 
+         * Wait for a frame with the specified id to be loaded.
          * It's needed when using the workspaces-api from a custom workspaces frame and you have the frameId,
          * but the frame object is not populated in the API yet (e.g. the frame is in the pool)
          * @param id the id of the frame that should be waited