@interopio/desktop API Reference

Access via:io.v2

Layouts API.

Properties (3)

Property Type Default Required Description
advancedLayoutsSupported⚓︎ boolean x

Flag indicating whether Layout sharing (advanced Layouts) is enabled. If true, io.Manager is used as a Layout store and Layout sharing is enabled both in io.Connect Desktop and in io.Manager.
current⚓︎ CurrentLayoutAPI x

API for retrieving and tracking the currently active Global Layout.
default⚓︎ DefaultLayoutAPI x

API for managing the default Global Layout which io.Connect Desktop will load upon startup.

24 Methods

export()⚓︎

(type?: LayoutType) => Promise<Layout[]>

Retrieves all available Layouts.

Parameters (1)

Name Type Required Description
type⚓︎ LayoutType x

Type of the Layouts to retrieve. If not specified, all Layouts will be retrieved.

get()⚓︎

(layout: GetLayoutOptions) => Promise<Layout | null>

Retrieves a Layout by ID. Resolves with null if the Layout doesn't exist.

Parameters (1)

Name Type Required Description
layout⚓︎ GetLayoutOptions

Options for retrieving a Layout.

getContents()⚓︎

(layout: LayoutSelect, options?: GetContentsOptions) => Promise<LayoutContents>

Retrieves the contents of a Global Layout or a Workspace Layout. When used for retrieving the contents of a Global Layout, the returned result will contain all components participating in the Global Layout: individual app instances (including all Workspaces App instances), all Workspace instances hosted in all Workspaces App instances, and all windows participating in all Workspaces. When used for retrieving the contents of a Workspace Layout, the returned result will contain only the windows participating in the Workspace.

Parameters (2)

Name Type Required Description
layout⚓︎ LayoutSelect

The Layout whose contents to retrieve.
options⚓︎ GetContentsOptions x

Options for retrieving the Layout contents.

getMany()⚓︎

(filter?: LayoutFilter) => Promise<Layout[]>

Retrieves all Layouts matching the specified filter. If no filter is specified, all available Layouts will be retrieved.

Parameters (1)

Name Type Required Description
filter⚓︎ LayoutFilter x

Filter for retrieving Layouts.

getRestoreHistory()⚓︎

() => Promise<RestoreLayoutHistory | null>

Retrieves information about the currently active Global Layout, as well as about any previously active Global Layouts that may still have running instances of their participating apps. Resolves with null if no Layout has been restored in the current session.

hibernate()⚓︎

(layout: LayoutSelect, options?: HibernateOptions) => Promise<Layout>

Hibernates a Layout. The Layout is saved and its participating app instances are hidden from the user instead of being closed. Instances of apps configured to close on hibernation are closed.

Parameters (2)

Name Type Required Description
layout⚓︎ LayoutSelect

The Layout to hibernate.
options⚓︎ HibernateOptions x

Options for hibernating a Layout.

import()⚓︎

(layouts: Layout[], mode?: ImportMode) => Promise<ImportLayoutResult>

Imports one or more Layouts.

Parameters (2)

Name Type Required Description
layouts⚓︎ Layout[]

Array of Layouts to import.
mode⚓︎ ImportMode x

Mode for importing the Layouts.

onAdded()⚓︎

(handler: LayoutEventHandler) => Promise<UnsubscribeFunction>

Notifies when a Layout is added. The callback is invoked for all existing Layouts when you subscribe. Resolves with an unsubscribe function. The Layout objects received by the callback don't contain the components, the context, and the access information of the Layouts. To retrieve them, use the get() method.

Parameters (1)

Name Type Required Description
handler⚓︎ LayoutEventHandler

Callback function for handling the event.

onChanged()⚓︎

(handler: LayoutEventHandler) => Promise<UnsubscribeFunction>

Notifies when a Layout is changed (e.g., when it's saved or its metadata is updated). Resolves with an unsubscribe function. To get notified about changes to the currently active Global Layout, use the onChanged() and onModified() methods of the current object. The Layout object received by the callback doesn't contain the components, the context, and the access information of the Layout. To retrieve them, use the get() method.

Parameters (1)

Name Type Required Description
handler⚓︎ LayoutEventHandler

Callback function for handling the event.

onHibernated()⚓︎

(handler: LayoutEventHandler) => Promise<UnsubscribeFunction>

Notifies when a Layout is hibernated. Resolves with an unsubscribe function. The Layout object received by the callback doesn't contain the components, the context, and the access information of the Layout. To retrieve them, use the get() method.

Parameters (1)

Name Type Required Description
handler⚓︎ LayoutEventHandler

Callback function for handling the event.

onRemoved()⚓︎

(handler: LayoutEventHandler) => Promise<UnsubscribeFunction>

Notifies when a Layout is removed. Resolves with an unsubscribe function. The Layout object received by the callback doesn't contain the components, the context, and the access information of the Layout.

Parameters (1)

Name Type Required Description
handler⚓︎ LayoutEventHandler

Callback function for handling the event. Receives the removed Layout as an argument.

onRenamed()⚓︎

(handler: LayoutEventHandler) => Promise<UnsubscribeFunction>

Notifies when a Layout is renamed. Resolves with an unsubscribe function. The Layout object received by the callback doesn't contain the components, the context, and the access information of the Layout. To retrieve them, use the get() method.

Parameters (1)

Name Type Required Description
handler⚓︎ LayoutEventHandler

Callback function for handling the event.

onRestored()⚓︎

(handler: RestoredLayoutEventHandler) => Promise<UnsubscribeFunction>

Notifies when a Layout is restored. Resolves with an unsubscribe function. The Layout object received by the callback doesn't contain the components, the context, and the access information of the Layout. To retrieve them, use the get() method.

Parameters (1)

Name Type Required Description
handler⚓︎ RestoredLayoutEventHandler

Callback function for handling the event. Receives the restored Layout and the ID of the restore session as an argument.

onResumed()⚓︎

(handler: LayoutEventHandler) => Promise<UnsubscribeFunction>

Notifies when a hibernated Layout is resumed. Resuming a Layout doesn't raise the event for restoring a Layout. Resolves with an unsubscribe function. The Layout object received by the callback doesn't contain the components, the context, and the access information of the Layout. To retrieve them, use the get() method.

Parameters (1)

Name Type Required Description
handler⚓︎ LayoutEventHandler

Callback function for handling the event.

onSaveRequested()⚓︎

(handler: (info: SaveRequestContext) => SaveRequestResponse | Promise<SaveRequestResponse>) => Promise<UnsubscribeFunction>

Notifies when a Layout save is requested. Use this method to save context data for the current app in the Layout. Resolves with an unsubscribe function.

Parameters (1)

Name Type Required Description
handler⚓︎ (info: SaveRequestContext) => SaveRequestResponse | Promise<SaveRequestResponse>

Callback function for handling the event. Must return an object with a windowContext property holding the context to save.

remove()⚓︎

(layout: LayoutSelect) => Promise<void>

Removes a Layout.

Parameters (1)

Name Type Required Description
layout⚓︎ LayoutSelect

The Layout to remove.

rename()⚓︎

(layout: LayoutSelect, newName: string) => Promise<void>

Renames a Layout. If the Layout is stored in io.Manager, its ID is preserved. In other Layout stores, the ID is formed by the name and the type of the Layout, so renaming the Layout changes its ID.

Parameters (2)

Name Type Required Description
layout⚓︎ LayoutSelect

The Layout to rename.
newName⚓︎ string

New name for the Layout.

reset()⚓︎

(session: RestoreSessionSelect, options?: ResetOptions) => Promise<ResetResult>

Resets a restored Global Layout to its default state.

Parameters (2)

Name Type Required Description
session⚓︎ RestoreSessionSelect

Object containing the ID of the restore session for the Layout to reset.
options⚓︎ ResetOptions x

Options for resetting a Layout.

restore()⚓︎

(layout: LayoutSelect, options?: RestoreOptions) => Promise<RestoreResult>

Restores a Layout.

Parameters (2)

Name Type Required Description
layout⚓︎ LayoutSelect

The Layout to restore.
options⚓︎ RestoreOptions x

Options for restoring a Layout.

resume()⚓︎

(layout: LayoutSelect, options?: ResumeOptions) => Promise<ResumeResult>

Resumes a hibernated Layout.

Parameters (2)

Name Type Required Description
layout⚓︎ LayoutSelect

The Layout to resume.
options⚓︎ ResumeOptions x

Options for resuming a Layout.

save()⚓︎

(options: SaveLayoutOptions) => Promise<Layout>

Saves a new Layout or overwrites an existing one.

Parameters (1)

Name Type Required Description
options⚓︎ SaveLayoutOptions

Options for saving a Layout.

updateAccess()⚓︎

(layout: LayoutSelect, accessInfo: SaveLayoutAccessInfo) => Promise<void>

Changes the access to a Layout without modifying its components or context. The owner of the Layout is preserved. Available only when Layout sharing is enabled.

Parameters (2)

Name Type Required Description
layout⚓︎ LayoutSelect

The Layout whose access to change.
accessInfo⚓︎ SaveLayoutAccessInfo

New access information for the Layout.

updateComponentContext()⚓︎

(context: Record<string, unknown>) => Promise<void>

Updates the context that will be saved for the current app. If the app participates in the currently active Global Layout or in a Workspace Layout, its context will be updated in that Layout. Otherwise, the context will be updated in the App Default Layout of the app. The context of the Layout itself isn't modified.

Parameters (1)

Name Type Required Description
context⚓︎ Record<string, unknown>

New context for the app.

updateMetadata()⚓︎

(layout: LayoutSelect, metadata: object, options?: UpdateMetadataOptions) => Promise<void>

Updates the metadata of a Layout without modifying its components or context. By default, the new metadata replaces the existing one.

Parameters (3)

Name Type Required Description
layout⚓︎ LayoutSelect

The Layout whose metadata to update.
metadata⚓︎ object

New metadata for the Layout.
options⚓︎ UpdateMetadataOptions x

Options for updating the Layout metadata.