Layouts
6.14.0The Layouts API allows you to save the arrangement and context of any set of apps running in io.Connect Desktop as a named Layout and later restore it. You can also choose a default Global Layout which io.Connect Desktop will load upon startup.
The Layouts library supports different types of Layouts - Global, App Default, Workspace.
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
Retrieves all available Layouts.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| layoutType | LayoutType | Type of the Layouts to retrieve. |
forceRefreshmethod
Signature
() => Promise<void>
Description
Forces a refresh of the connection to io.Manager or any other REST Layout stores, updating the list of available Layouts.
getmethod
Signature
(name: string, type: LayoutType) => Promise<Layout>
Description
Retrieves a Layout.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| name | string | Name of the Layout to retrieve. |
|
| type | LayoutType | Type of the Layout to retrieve. |
getAllmethod
Signature
(type: LayoutType) => Promise<LayoutSummary[]>
Description
Retrieves a lightweight, summarized version of all Layouts of the provided type.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| type | LayoutType | Type of the Layouts whose summaries to retrieve. |
getCurrentLayoutmethod
getDefaultGlobalmethod
getRestoredLayoutsInfomethod
Signature
() => Promise<GetRestoredLayoutsInfoResult>
Description
Retrieves info about the currently active Layout (ID, type, name, participating app instances), as well as about any previously active Layouts that still have running instances of their participating apps.
hibernatemethod
Signature
(name: string, options?: HibernationOptions) => Promise<HibernateResult>
Description
Hibernates a Layout.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| name | string | Name of the Layout to hibernate. |
|
| options | HibernationOptions | Options for hibernating a Layout. |
importmethod
Signature
(layouts: Layout[], mode?: "replace" | "merge") => Promise<ImportLayoutResult>
Description
Imports one or more Layouts.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| layouts | Layout[] | Array of Layouts to import. |
|
| mode | "replace" | "merge" | Mode for importing the Layouts. |
listmethod
onAddedmethod
onChangedmethod
onDefaultGlobalChangedmethod
Signature
(callback: (layout?: { name: string; }) => void) => UnsubscribeFunction
Description
Notifies when a new default Global Layout has been selected or when the current one has been cleared.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| callback | (layout?: { name: string; }) => void | Callback function for handling the event. Receives as an argument an object with a |
onLayoutModifiedmethod
Signature
(callback: (info: LayoutModifiedEvent) => SaveRequestResponse) => UnsubscribeFunction
Description
This event will be raised the first time the currently loaded global layout has been modified. Modified means that the layout has been changed:
- an app has been started or stopped
- an app has ben moved
- a workspace that is part of the layout has been modified This event can be used to mark the layout as dirty. This event will be raised only the first time the layout is modified. A second modification won't raise the event again. Saving the layout will reset that and the event will be raised again the next time the layout is modified.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| callback | (info: LayoutModifiedEvent) => SaveRequestResponse | Callback function for handling the event. |
onRemovedmethod
onRenamedmethod
Signature
(callback: (layout: Layout, previous: { name: string; }) => void) => UnsubscribeFunction
Description
Notifies when a Layout is renamed.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| callback | (layout: Layout, previous: { name: string; }) => void | Callback function for handling the event.
Receives as a first argument the |
onRestoredmethod
onSaveRequestedmethod
Signature
(callback: (info?: SaveRequestContext) => SaveRequestResponse) => UnsubscribeFunction
Description
Notifies when a Layout save is requested.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| callback | (info?: SaveRequestContext) => SaveRequestResponse | Callback function for handling the event. |
removemethod
Signature
(type: string, name: string) => Promise<void>
Description
Removes a Layout
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| type | string | 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. |
resetmethod
Signature
(options: ResetLayoutOptions) => Promise<RestoreResumeResult>
Description
Resets a Layout.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| options | ResetLayoutOptions | Options for resetting a Layout. |
restoremethod
Signature
(options: RestoreOptions) => Promise<RestoreResumeResult>
Description
Restores a Layout.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| options | RestoreOptions | Options for restoring a Layout. |
resumemethod
Signature
(name: string, context?: any, options?: ResumeOptions) => Promise<RestoreResumeResult>
Description
Resumes a Layout.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| name | string | Name of the Layout to resume. |
|
| context | any | Context for the Layout. |
|
| options | ResumeOptions | Options for resuming 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 Layout to set as the new default Global Layout. |
updateAppContextInCurrentmethod
Signature
(context: object) => Promise<void>
Description
Updates the context saved for your app in the currently loaded Layout.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| context | object | New context for the app. |
updateDefaultContextmethod
Signature
(context: object) => Promise<LayoutResult>
Description
Updates the context that will be saved as a default context for the current window.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| context | object | New context that will be saved as a default window context. |
Configurationobject
Description
Configuration for the Layouts library.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| autoSaveWindowContext | boolean | LayoutType[] | false | If |
|
| mode | Mode | Layouts library mode. |
GetRestoredLayoutsInfoResultobject
Description
Describes the currently active Layout (ID, type, name and participating app instances), as well as any previously active Layouts that still have running instances of their participating apps.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| layoutInfo | RestoredLayoutDetails[] | List of objects each describing the currently active Layout or any previously active Layouts. |
HibernateResultobject
Description
Describes the result returned from hibernating a Layout.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| layout | Layout | Hibernated layout. |
||
| status | string | Status of the Layout operation. If successful, will be set to |
HibernationOptionsobject
Description
Options for hibernating Layouts.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| context | object | Context object that will be passed to the restored apps. It will be merged with the saved context object. |
||
| metadata | any | Metadata to be saved with the Layout. |
ImportLayoutResultobject
Description
Describes the result returned from importing Layouts.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| failed | { name: string; type: LayoutType; }[] | Array of objects describing all Layouts that failed to import. Each object contains the name and the type of the Layout. |
||
| status | string | Status of the Layout operation. If successful, will be set to |
Layoutobject
Description
Describes a Layout.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| components | LayoutComponent[] | Array of component objects describing the apps that are saved in the Layout. |
||
| context | any | Layout context. |
||
| metadata | any | Layout metadata. |
||
| name | string | Name of the Layout, unique per Layout type. |
||
| type | LayoutType | Type of the Layout. |
||
| version | number | Version of the Layout. |
LayoutComponentobject
Description
Describes a Layout component - an app participating in the Layout and its state.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| application | string | Name of the app to which belongs the window instance, or the name of the Workspaces App to which belongs the Workspace instance. |
||
| state | any | Provides information about the instance ID, bounds, context, state and more of the Layout component. |
||
| type | string | Type of the Layout component. If |
LayoutModifiedEventobject
Description
Describes a modified Layout and the reason for its modification.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| layout | { name: string; type: string; } | Object holding the name and the type of the modified Layout. |
||
| reason | { application?: string; action?: string; instance?: string; } | Object holding information about the name of the app or the ID of the instance that is responsible for the Layout changes, and the action that has caused them (e.g., started or stopped instance, changed state of a Workspaces App, and more). |
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 |
LayoutSummaryobject
Description
Summarized description of a Layout.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| context | any | Layout context. |
||
| metadata | any | Layout metadata. |
||
| name | string | Name of the Layout, unique per Layout type. |
||
| type | LayoutType | Type of the Layout. |
NewLayoutOptionsobject
Description
Options for saving a new Layout.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| context | any | Context to be saved with the Layout. |
||
| ignoreContexts | boolean | If |
||
| ignoreInstances | string[] | Only if the Layout type is |
||
| instances | string[] | Only if the Layout type is |
||
| metadata | any | Metadata to be saved with the Layout. |
||
| name | string | Name for the Layout. |
||
| setAsCurrent | boolean | If |
||
| type | LayoutType | "Global" | Type of the Layout. |
ResetLayoutOptionsobject
Description
Options for resetting a Layout.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| createMissing | boolean | true | If |
|
| layoutId | string | ID of the Layout to reset. |
||
| resetState | boolean | true | If |
|
| visibleOnly | boolean | false | If |
RestoredInstanceobject
Description
Describes an app instance participating in a restored or resumed Layout.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| appName | string | Name of the app within the io.Connect framework. |
||
| instanceId | string | Unique ID of the app instance within the io.Connect framework. |
RestoredLayoutDetailsobject
Description
Describes a currently active Layout, or a previously active Layout that may still have running instances of its participating apps.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| id | string | ID of the Layout. |
||
| instances | RestoredLayoutInstanceInfo[] | List of objects each describing the app instances participating in the Layout. |
||
| name | string | Name of the Layout. |
||
| type | string | Type of the Layout. |
RestoredLayoutInstanceInfoobject
Description
Describes an app instance participating in a Layout.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| appName | string | Name of the app within the io.Connect framework. |
||
| instanceId | string | Unique ID of the app instance within the io.Connect framework. |
||
| stopped | boolean | Flag indicating whether the app instance has been stopped. |
RestoreOptionsobject
Description
Options for restoring a Layout.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| closeMe | boolean | true | If |
|
| closeRunningInstances | boolean | true | Only if the Layout type is |
|
| context | unknown | 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 | 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. |
||
| type | string | "Global" | Type of the Layout to restore. |
RestoreResumeResultobject
Description
Describes the result returned from restoring or resuming a Layout.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| instances | RestoredInstance[] | List of objects describing the app instances participating in the restored or resumed Layout. |
||
| layoutId | string | ID of the Layout that was restored or resumed. |
||
| status | "Success" | "Failed" | Status of the Layout restore or resume operation. |
ResumeOptionsobject
Description
Options for resuming a Layout.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| cleanUp | boolean | Whether to stop any already running apps before resuming the Layout. |
SaveRequestContextobject
Description
Context passed as an argument to the callback for handling Layout save request events.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| context | unknown | Context to be saved. |
||
| layoutName | string | Name of the Layout that is to be saved. |
||
| layoutType | LayoutType | Type of the Layout to be saved. |
SaveRequestResponseobject
Description
Result returned in response to a request for saving a Layout.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| windowContext | object | Context object specific to the app. |
ImportModeenumeration
Description
Mode for importing Layouts.
"replace"- all existing Layouts will be removed and replaced with the imported ones (default);"merge"- the imported Layouts will be merged with the existing ones;
- "replace"
- "merge"
LayoutTypeenumeration
Description
The supported Layout types are "Global", "ApplicationDefault" and "Workspace".
The "Activity" and "Swimlane" types are deprecated.
In a Global Layout, all running apps and their state is saved. By default, hidden windows are ignored.
The App Default Layout describes the default Layout for an app instance - the last saved window bounds,
state and context. The Workspace Layout describes the arrangement of the Workspace elements, its bounds and context of individual windows.
- "Global"
- "ApplicationDefault"
- "Workspace"
- "Activity"
- "Swimlane"
Modeenumeration
Description
Layouts library initialization mode:
"full"- all Layout functionalities are available;"fullWaitSnapshot"- same as the"full"mode, except that the Layouts library will notify that it is ready a little later - when a snapshot of the available Layouts has been received;"slim"- Layout events aren't tracked and Layouts can't be manipulated;
- "full"
- "fullWaitSnapshot"
- "slim"