• Back to io.Connect Desktop docs
io.Connect Desktop Documentation

API Reference Documentation

  • Back to io.Connect Desktop docs
Press/
  • io.Connect Desktop
  • App Management
  • App Preferences
  • Channels
  • Cookies
  • Displays
  • Hotkeys
  • Intents
  • Interception
  • Interop
  • Layouts
  • Logger
  • Metrics
  • Notifications
  • Pub Sub
  • Search
  • Shared Contexts
  • Themes
  • Windows
  • Workspaces

Layouts

6.13.0

The 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

  • clearDefaultGlobal
  • export
  • forceRefresh
  • get
  • getAll
  • getCurrentLayout
  • getDefaultGlobal
  • getRestoredLayoutsInfo
  • hibernate
  • import
  • list
  • onAdded
  • onChanged
  • onLayoutModified
  • onRemoved
  • onRenamed
  • onRestored
  • onSaveRequested
  • remove
  • rename
  • reset
  • restore
  • resume
  • save
  • setDefaultGlobal
  • updateAppContextInCurrent
  • updateDefaultContext
  • updateMetadata

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

Signature

() => Promise<Layout>

Description

Retrieves the last restored Global Layout.

getDefaultGlobalmethod

Signature

() => Promise<Layout>

Description

Retrieves the default Global Layout, if any.

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

Signature

() => Layout[]

Description

Retrieves a list of all Layouts.

onAddedmethod

Signature

(callback: (layout: Layout) => void) => UnsubscribeFunction

Description

Notifies when a new Layout is added.

Parameters

Name Type Required Description
callback (layout: Layout) => void

Callback function for handling the event.

onChangedmethod

Signature

(callback: (layout: Layout) => void) => UnsubscribeFunction

Description

Notifies when a Layout is changed.

Parameters

Name Type Required Description
callback (layout: Layout) => void

Callback function for handling the event.

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

Signature

(callback: (layout: Layout) => void) => UnsubscribeFunction

Description

Notifies when a Layout is removed.

Parameters

Name Type Required Description
callback (layout: Layout) => void

Callback function for handling the event.

onRenamedmethod

Signature

(callback: (layout: Layout) => void) => UnsubscribeFunction

Description

Notifies when a Layout is renamed.

Parameters

Name Type Required Description
callback (layout: Layout) => void

Callback function for handling the event.

onRestoredmethod

Signature

(callback: (Layout: Layout) => void) => UnsubscribeFunction

Description

Notifies when a Layout is restored.

Parameters

Name Type Required Description
callback (Layout: Layout) => void

Callback function for handling the event.

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.

updateMetadatamethod

Signature

(layout: Layout) => Promise<void>

Description

Updates the metadata of a Layout.

Parameters

Name Type Required Description
layout Layout

Existing Layout to update.

Configurationobject

Description

Configuration for the Layouts library.

Properties

Property Type Default Required Description
autoSaveWindowContext boolean | LayoutType[] false

If true, the context of the current window will be saved. You can also specify a list of Layout types for which to save the window context.

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 "Success", otherwise, will contain the returned error message.

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 "Success", otherwise, will contain the returned error message.

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 "window", the component is a window instance of an app. If "Workspace", the component is a Workspace instance in a Layout of type "Workspace". If "workspaceFrame", the component is a Workspaces App with one or more Workspaces in it, participating in a Layout of type "Global".

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 "Success", otherwise, will contain the returned error message.

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.

ignoreInstances string[]

Only if the Layout type is "Global". The instances with the provided IDs will be ignored.

instances string[]

Only if the Layout type is "Global". The instances with the provided IDs will be saved.

metadata any

Metadata to be saved with the Layout.

name string

Name for the Layout.

setAsCurrent boolean

If true, will set the saved Layout as the current Global Layout.

type LayoutType "Global"

Type of the Layout.

ResetLayoutOptionsobject

Description

Options for resetting a Layout.

Properties

Property Type Default Required Description
createMissing boolean true

If true, will create any missing apps that may have been closed by the user or programmatically.

layoutId string

ID of the Layout to reset.

resetState boolean true

If true, will reset the Layout to its default state. Set to false to preserve any current app context or Channel selection.

visibleOnly boolean false

If true, will reset only the visible apps. Any apps that may have been hidden programmatically won't be included in the Layout reset process.

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 true, will close the current app before restoring a Layout. If closeRunningInstances is set to false, this will default to false too.

closeRunningInstances boolean true

Only if the Layout type is "Global". If true, will close all visible running instances before restoring the Layout. Exceptions are apps which are configured as shell, service, auto started, or ignored from Layouts.

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"

  • Home
  • Privacy policy
  • Contact Us
  • interop.io
  • Overview
  • API
  • Configuration
  • GetRestoredLayoutsInfoResult
  • HibernateResult
  • HibernationOptions
  • ImportLayoutResult
  • Layout
  • LayoutComponent
  • LayoutModifiedEvent
  • LayoutResult
  • LayoutSummary
  • NewLayoutOptions
  • ResetLayoutOptions
  • RestoredInstance
  • RestoredLayoutDetails
  • RestoredLayoutInstanceInfo
  • RestoreOptions
  • RestoreResumeResult
  • ResumeOptions
  • SaveRequestContext
  • SaveRequestResponse
  • ImportMode
  • LayoutType
  • Mode
Navigate
Go