Layouts
3.4.6The Layouts library has the following capabilities:
- importing, exporting, removing and getting Layouts;
- saving and restoring Layouts;
- events related to adding, removing, changing or saving Layouts;
- requesting browser permission for the Multi-Screen Window Placement API;
The Layouts API is accessible through the io.layouts object.
APIobject
Description
Layouts API.
Methods
clearDefaultGlobalmethod
Signature
() => Promise<void>
Description
Removes the default Global Layout.
exportmethod
Signature
(layoutType: LayoutType) => Promise<Layout[]>
Description
Returns a collection of all available Layout objects of the provided type.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| layoutType | LayoutType |
getmethod
Signature
(name: string, type: LayoutType) => Promise<Layout>
Description
Fetches a saved Layout if a Layout with the provided name and type exists.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| name | string | Name of the Layout to fetch. |
|
| type | LayoutType | Type of the Layout to fetch. |
getAllmethod
Signature
(type: LayoutType) => Promise<LayoutSummary[]>
Description
Returns a lightweight description of all Layouts of the provided type, without the extensive objects describing the Layout components.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| type | LayoutType | Type of the Layouts to fetch. |
getDefaultGlobalmethod
getGlobalTypeStatemethod
Signature
() => Promise<{ activated: boolean; }>
Description
Checks whether Global Layouts are activated in the io.Connect Browser environment.
getMultiScreenPermissionStatemethod
Signature
() => Promise<{ state: "prompt" | "granted" | "denied"; }>
Description
Retrieves the browser Multi-Screen Window Placement permission state for the io.Connect Browser environment.
importmethod
Signature
(layouts: Layout[], mode?: "replace" | "merge") => Promise<void>
Description
Imports a collection of Layout objects.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| layouts | Layout[] | An array of |
|
| mode | "replace" | "merge" | If |
onAddedmethod
Signature
(callback: (layout: Layout) => void) => () => void
Description
Notifies when a new Layout is added.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| callback | (layout: Layout) => void | Callback function to handle the event. Receives the |
onChangedmethod
Signature
(callback: (layout: Layout) => void) => () => void
Description
Notifies when a Layout is modified.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| callback | (layout: Layout) => void | Callback function to handle the event. Receives the |
onRemovedmethod
Signature
(callback: (layout: Layout) => void) => () => void
Description
Notifies when a Layout is removed.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| callback | (layout: Layout) => void | Callback function to handle the event. Receives the |
onRenamedmethod
Signature
(callback: (layout: Layout) => void) => () => void
Description
Notifies when a Layout is renamed.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| callback | (layout: Layout) => void | Callback function to handle the event. Receives the |
onSaveRequestedmethod
Signature
(callback: (info?: SaveRequestContext) => SaveRequestResponse) => () => void
Description
Subscribes for Layout save requests.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| callback | (info?: SaveRequestContext) => SaveRequestResponse | The callback passed as an argument will be invoked when a Layout save operation is requested. You have the option to save data (context) which will be restored when the Layout is restored. Returns an unsubscribe function. |
removemethod
Signature
(type: LayoutType, name: string) => Promise<void>
Description
Removes a Layout.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| type | LayoutType | Type of the Layout to remove. |
|
| name | string | Name of the Layout to remove. |
renamemethod
Signature
(layout: Layout, newName: string) => Promise<LayoutResult>
Description
Renames a Layout.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| layout | Layout | Existing Layout to rename. |
|
| newName | string | New name for the Layout. |
requestMultiScreenPermissionmethod
Signature
() => Promise<{ permissionGranted: boolean; }>
Description
Opens the browser permission prompt requesting Multi-Screen Window Placement permission from the user for the io.Connect Browser environment. This can only be requested from the Main app (Web Platform) due to the transient activation restrictions of the browsers.
restoremethod
Signature
(options: RestoreOptions) => Promise<void>
Description
Restores a Layout.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| options | RestoreOptions | Options for restoring a Layout. |
savemethod
Signature
(layout: NewLayoutOptions) => Promise<Layout>
Description
Saves a new Layout.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| layout | NewLayoutOptions | Options for saving a Layout. |
setDefaultGlobalmethod
Signature
(name: string) => Promise<void>
Description
Sets a new default Global Layout.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| name | string | Name of the Global Layout to set as default. |
Layoutobject
Description
Describes a Layout and its components.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| components | (WorkspaceComponent | WindowComponent | WorkspaceFrameComponent)[] | Array of component objects describing the apps and Workspaces saved in the Layout. |
||
| context | any | Context object passed when the Layout was saved. |
||
| metadata | any | Metadata passed when the Layout was saved. |
||
| name | string | Name of the Layout. The name is unique per Layout type. |
||
| type | LayoutType | Type of the Layout. |
||
| version | number | Version of the Layout. |
LayoutResultobject
Description
Describes the base result returned by methods for manipulating Layouts - e.g., renaming, hibernating, updating default context.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| status | string | Status of the Layout operation. If successful, will be set to "Success", otherwise, will contain the returned error message. |
LayoutSummaryobject
Description
A lightweight description of a Layout, without the extensive objects describing its components.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| context | any | Context object passed when the Layout was saved. |
||
| metadata | any | Metadata passed when the Layout was saved. |
||
| name | string | Name of the Layout. The name is unique per Layout type. |
||
| type | LayoutType | Type of the Layout. |
NewLayoutOptionsobject
Description
Options for saving a Layout.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| context | any | Context to be saved with the Layout. Used for transferring data to the apps when restoring a Layout. |
||
| ignoreInstances | string[] | Window or app instance IDs of the instances to be ignored when saving the Layout. |
||
| instances | string[] | Window or app instance IDs of the instances to be saved in the Layout. |
||
| metadata | any | Metadata to be saved with the Layout. |
||
| name | string | Name for the Layout. |
RestoreOptionsobject
Description
Options for restoring a Layout.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| closeMe | boolean | true | If |
|
| closeRunningInstances | boolean | true | If |
|
| context | object | Context object that will be passed to the restored apps. It will be merged with the saved context object. |
||
| name | string | Name of the Layout to restore. |
||
| timeout | number | 60000 | Timeout in milliseconds for restoring the Layout. If the time limit is hit, all apps opened up to this point will be closed and an error will be thrown. |
SaveRequestContextobject
Description
Object passed as an argument to the handler for a save Layout request.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| context | unknown | Context for the Layout. |
||
| layoutName | string | Name of the Layout. |
||
| layoutType | LayoutType | Type of the Layout. |
SaveRequestResponseobject
Description
Object returned by the handler for a save Layout request.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| windowContext | object | Context to be saved for the specific app in the Layout. |
ImportModeenumeration
Description
Controls the import behavior. If "replace" (default), all existing Layouts will be removed.
If "merge", the Layouts will be added to the existing ones.
- "replace"
- "merge"
LayoutTypeenumeration
Description
Type of the Layout. Supported Layouts are "Global" and "Workspace".
- "Global"
- "Activity"
- "ApplicationDefault"
- "Swimlane"
- "Workspace"