Layouts

5.2.4

Layouts allows you to save the arrangement of any set of applications running in Glue42 Desktop and later restore it. The Layouts API can be accessed using glue.layouts.

The Layouts library supports different types of layouts:

See also the Layouts documentation for more details.

object

Description

Layouts API.

methodready
() => Promise<void>

Description

Notifies when the library is ready to be used.

Returns

Promise<void>

methodlist
() => Layout[]

Description

Lists all layouts.

Returns

Layout[]

methodsave
(layout: NewLayoutOptions) => Promise<Layout>

Description

Saves a new layout.

Parameters

Name
Type
Required
Description

layout

NewLayoutOptions

yes

Options for saving a layout.

Returns

Promise<Layout>

methodimport
(layouts: Layout[], mode: ImportMode) => Promise<void>

Description

Imports one or more layouts.

Parameters

Name
Type
Required
Description

layouts

Layout[]

yes

Layouts to import.

mode

ImportMode

no

Mode for importing the layouts - replace or merge.

Returns

Promise<void>

methodexport
() => Promise<Layout[]>

Description

Returns all layouts in the system.

Returns

Promise<Layout[]>

methodrestore
(options: RestoreOptions) => Promise<void>

Description

Restores a layout.

Parameters

Name
Type
Required
Description

options

RestoreOptions

yes

Options for restoring a layout.

Returns

Promise<void>

methodremove
(type: string, name: string) => Promise<void>

Description

Removes a layout

Parameters

Name
Type
Required
Description

type

string

yes

Type of the layout to remove.

name

string

yes

Name of the layout to remove.

Returns

Promise<void>

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

Description

Renames a layout.

Parameters

Name
Type
Required
Description

layout

Layout

yes

Existing layout to rename.

newName

string

yes

The new name of the layout.

Returns

Promise<void>

methodupdateMetadata
(layout: Layout) => Promise<void>

Description

Updates the metadata of a layout.

Parameters

Name
Type
Required
Description

layout

Layout

yes

Existing layout to update.

Returns

Promise<void>

methodgetCurrentLayout
() => Promise<Layout>

Description

Returns the last restored global layout

Returns

Promise<Layout>

methodhibernate
(name: string, options: HibernationOptions) => Promise<void>

Description

Hibernates a layout.

Available since version 4.8 and Glue42 3.9

Parameters

Name
Type
Required
Description

name

string

yes

The name of the layout

options

HibernationOptions

no

Options for hibernating a layout.

Returns

Promise<void>

methodresume
(name: string, context: any, options: ResumeOptions) => Promise<void>

Description

Resumes a layout.

Available since version 4.8 and Glue42 3.9

Parameters

Name
Type
Required
Description

name

string

yes

The name of the layout.

context

any

no

The context of the layout

options

ResumeOptions

no

Returns

Promise<void>

methodupdateAppContextInCurrent
(context: object) => Promise<void>

Description

Updates the context saved for your application in the currently loaded layout

Parameters

Name
Type
Required
Description

context

object

yes

the new context

Returns

Promise<void>

methodupdateDefaultContext
(context: object) => Promise<void>

Description

Updates the context that will be saved as a default context for the current window.

Available since version Glue42 3.10

Parameters

Name
Type
Required
Description

context

object

yes

New context that will be saved as a default window context.

Returns

Promise<void>

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

Description

Notifies when a new layout is added.

Parameters

Name
Type
Required
Description

callback

(layout: Layout) => void

yes

Callback function to handle the event. Receives the layout as a parameter and returns an unsubscribe function.

Returns

() => void

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

Description

Notifies when a layout is removed.

Parameters

Name
Type
Required
Description

callback

(layout: Layout) => void

yes

Callback function to handle the event. Receives the layout as a parameter and returns an unsubscribe function.

Returns

() => void

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

Description

Notifies when a layout is changed.

Parameters

Name
Type
Required
Description

callback

(layout: Layout) => void

yes

Callback function to handle the event. Receives the layout as a parameter and returns an unsubscribe function.

Returns

() => void

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

Description

Notifies when a layout is renamed.

Parameters

Name
Type
Required
Description

callback

(layout: Layout) => void

yes

Callback function to handle the event. Receives the layout as a parameter and returns an unsubscribe function.

Returns

() => void

methodonSaveRequested
(callback: (info?: SaveRequestContext) => SaveRequestResponse) => () => void

Description

Subscribes for layout save requests.

Parameters

Name
Type
Required
Description

callback

(info?: SaveRequestContext) => SaveRequestResponse

yes

The callback passed as an argument will be invoked when a layout save is requested. You have the option to save data (context) which will be restored when the layout is restored. Returns an unsubscribe function.

Returns

() => void

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

Description

Notifies when a global layout is restored

Parameters

Name
Type
Required
Description

callback

(Layout: Layout) => void

yes

Returns

UnsubscribeFunction

methodsetDefaultGlobal
(name: string) => Promise<void>

Description

Sets a new default global layout

Parameters

Name
Type
Required
Description

name

string

yes

Returns

Promise<void>

methodclearDefaultGlobal
() => Promise<void>

Description

Clears the default global layout

Returns

Promise<void>

methodgetDefaultGlobal
() => Promise<Layout>

Description

Returns the default global layout (might be undefined)

Returns

Promise<Layout>

object

Description

Describes a layout and its state.

Properties

string

Name of the layout. The name is unique per layout type.

LayoutType

Type of the layout.

LayoutComponent[]

Array of component objects describing the applications that are saved in the layout.

any

Context object passed when the layout was saved.

any

Metadata passed when the layout was saved.

string

Version of the layout

object

Description

Layouts library configuration object.

Properties

Mode

Layouts mode.

boolean

If true, the context of the current window will be saved when the window is closed.

Default: false

Available since version 3.10

object

Description

Saved component (single window application or activity) with its state (bounds, context).

Properties

"window"

ComponentType

Type of the component - can be application or activity.

any

Object describing the application bounds, name, context, etc.

object

Description

Object describing the layout that you want to save.

Properties

string

Name of the layout.

LayoutType

Type of the layout.

Default: "Global"

any

Context (application specific data) to be saved with the layout. Used to transfer data to the applications when restoring a layout.

any

Metadata to be saved with the layout.

boolean

Only if the layout type is Global. If true (default), the layout will not include hidden apps.

boolean

Only if the layout type is Global. Ignores the current instance when saving a layout. False by default.

string

Only if the layout type is Activity. Will save the layout of the activity with the provided ID. If not passed, will use the activity that the calling application participates in. If the current application is not in an activity, an error will be thrown.

object

Description

Options object for restoring layouts.

Properties

string

Name of the layout to restore.

string

Type of the layout to restore.

Default: "Global"

boolean

If true, will close all visible running instances before restoring the layout. Exceptions are the current application and the Application Manager application. The default is true for Global layouts and false for Activity layouts.

object

Context object that will be passed to the restored apps. It will be merged with the saved context object.

boolean

Only if the type is Activity. If true (default), will try to reuse existing windows when restoring the layout.

string

Only if the type is Activity. If set, the activity will be restored and joined to the specified activity. If not set, a new activity instance will be created from the saved layout.

boolean

Only if the type is Activity. If true (default), will set the activity context upon restore.

boolean

Only if the type is Activity and activityId is set. If true, will restore the activity owner window.

string[]

Only if the type is Activity and activityId is set. With this you can specify that certain window types should not be restored.

RestoreSplashOptions

Restore options for the splash screen.

number

Restore timeout option.

object

Description

Options object for hibernating layouts.

Properties

object

Context object that will be passed to the restored apps. It will be merged with the saved context object.

any

Metadata to be saved with the layout.

object

Properties

boolean

Whether to stop any already running apps before resuming the layout.

object

Description

Options for the restore splash screen.

Properties

text:
string

Text for the splash screen.

string

Text color.

string

Background color.

string

Animation color.

object

Description

Object returned as a result to a save layout request.

Properties

object

Context object specific to the application.

object

The window can return activity context if it is an owner window of the activity. On restore, this context will be merged with the activity context passed when restoring the layout.

object

Properties

unknown

string

LayoutType

enumeration

Description

Library initialization mode:

  • slim - in this mode the application will be able to store custom data when a layout is saved and will not track layout events. It will not be able to manage layouts - create, delete, rename.
  • full - in this mode the application will be able to store custom data when a layout is saved and will track layout events. It will be able to manage layouts - create, delete, rename.
  • fullWaitSnapshot - same as full, only the library will notify that it is ready when it receives the snapshot of the layouts. In full mode, ready() is called when the library has successfully subscribed to a stream (a little earlier).
  • "slim"
  • "full"
  • "fullWaitSnapshot"

enumeration

Description

Supported layout types are Global and Activity. Global Layout saves all running applications and their state. By default, ignores hidden windows. Activity Layout saves applications running in an activity, the activity state and the individual windows states. By default, saves the activity of the current application but can be configured to save any activity. Activity layouts can be restored as new activity instances or joined to any running activity.

  • "Global"
  • "Activity"
  • "ApplicationDefault"
  • "Swimlane"
  • "Workspace"

enumeration

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"

enumeration

Description

Type of the layout component - activity or application.

  • "activity"
  • "application"