# API

**Kind**: interface | **Module**: [Layouts](https://docs.interop.io/desktop/reference/javascript/layouts/index.md) | **Access**: `io.layouts`

**Source**: https://docs.interop.io/desktop/reference/javascript/layouts/api/index.html

Layouts API.

## Methods

### clearDefaultGlobal

Removes the default Global Layout.

```ts
() => Promise<void>
```

**Returns**: `Promise<void>`

### export

Retrieves all available Layouts.

```ts
(layoutType?: LayoutType) => Promise<Layout[]>
```

**Parameters**

- **`layoutType`** (`LayoutType`, optional)
  Type of the Layouts to retrieve.

**Returns**: `Promise<Layout[]>`

### forceRefresh

Forces a refresh of the connection to io.Manager or any other REST Layout stores, updating the list of available Layouts.

```ts
() => Promise<void>
```

**Returns**: `Promise<void>`

### get

Retrieves a Layout.

```ts
(name: string, type: LayoutType) => Promise<Layout | undefined>
```

**Parameters**

- **`name`** (`string`, required)
  Name of the Layout to retrieve.
- **`type`** (`LayoutType`, required)
  Type of the Layout to retrieve.

**Returns**: `Promise<Layout | undefined>`

### getAll

Retrieves a lightweight, summarized version of all Layouts of the provided type.

```ts
(type: LayoutType) => Promise<LayoutSummary[]>
```

**Parameters**

- **`type`** (`LayoutType`, required)
  Type of the Layouts whose summaries to retrieve.

**Returns**: `Promise<LayoutSummary[]>`

### getCurrentLayout

Retrieves the last restored Global Layout.

```ts
() => Promise<Layout | undefined>
```

**Returns**: `Promise<Layout | undefined>`

### getDefaultGlobal

Retrieves the default Global Layout, if any.

```ts
() => Promise<Layout | undefined>
```

**Returns**: `Promise<Layout | undefined>`

### getLayoutContents

Retrieves the contents of a Global Layout or a Workspace Layout depending on the specified options.
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.

*Since: @interopio/desktop 6.21.0*

```ts
(options: GetContentsOptions) => Promise<LayoutContents>
```

**Parameters**

- **`options`** (`GetContentsOptions`, required)
  Options for retrieving the Layout contents.

**Returns**: `Promise<LayoutContents>`

### getRestoredLayoutsInfo

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.

*Since: io.Connect Desktop 9.4, @interopio/desktop 6.6.0*

```ts
() => Promise<GetRestoredLayoutsInfoResult | undefined>
```

**Returns**: `Promise<GetRestoredLayoutsInfoResult | undefined>`

### hibernate

Hibernates a Layout.

```ts
(name: string, options?: IOConnectDesktop.Layouts.HibernationOptions) => Promise<HibernateResult>
```

**Parameters**

- **`name`** (`string`, required)
  Name of the Layout to hibernate.
- **`options`** (`IOConnectDesktop.Layouts.HibernationOptions`, optional)
  Options for hibernating a Layout.

**Returns**: `Promise<HibernateResult>`

### import

Imports one or more Layouts.

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

**Parameters**

- **`layouts`** (`Layout[]`, required)
  Array of Layouts to import.
- **`mode`** (`ImportMode`, optional)
  Mode for importing the Layouts.

**Returns**: `Promise<ImportLayoutResult>`

### list

Retrieves a list of all Layouts.

```ts
() => Layout[]
```

**Returns**: `Layout[]`

### onAdded

Notifies when a new Layout is added.

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

**Parameters**

- **`callback`** (`(layout: Layout) => void`, required)
  Callback function for handling the event.

**Returns**: `UnsubscribeFunction`

### onChanged

Notifies when a Layout is changed.

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

**Parameters**

- **`callback`** (`(layout: Layout) => void`, required)
  Callback function for handling the event.

**Returns**: `UnsubscribeFunction`

### onDefaultGlobalChanged

Notifies when a new default Global Layout has been selected or when the current one has been cleared.

*Since: io.Connect Desktop 9.9, @interopio/desktop 6.14.0*

```ts
(callback: (layout?: { name: string }) => void) => UnsubscribeFunction
```

**Parameters**

- **`callback`** (`(layout?: { name: string }) => void`, required)
  Callback function for handling the event. Receives as an argument an object with a `name` property
  holding the name of the newly selected default Global Layout. If the default Global Layout has been cleared, the argument will be `undefined`.

**Returns**: `UnsubscribeFunction`

### onLayoutModified

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.

```ts
(callback: (info: LayoutModifiedEvent) => SaveRequestResponse) => UnsubscribeFunction
```

**Parameters**

- **`callback`** (`(info: LayoutModifiedEvent) => SaveRequestResponse`, required)
  Callback function for handling the event.

**Returns**: `UnsubscribeFunction`

### onRemoved

Notifies when a Layout is removed.

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

**Parameters**

- **`callback`** (`(layout: Layout) => void`, required)
  Callback function for handling the event.

**Returns**: `UnsubscribeFunction`

### onRenamed

Notifies when a Layout is renamed.

```ts
(callback: (layout: Layout, previous: { name: string }) => void) => UnsubscribeFunction
```

**Parameters**

- **`callback`** (`(layout: Layout, previous: { name: string }) => void`, required)
  Callback function for handling the event.
  Receives as a first argument the `Layout` object describing the renamed Layout.
  Receives as a second optional argument an object with a `name` property holding the previous Layout name (if any).

**Returns**: `UnsubscribeFunction`

### onRestored

Notifies when a Layout is restored.

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

**Parameters**

- **`callback`** (`(Layout: Layout) => void`, required)
  Callback function for handling the event.

**Returns**: `UnsubscribeFunction`

### onSaveRequested

Notifies when a Layout save is requested.

```ts
(callback: (info?: SaveRequestContext) => SaveRequestResponse) => UnsubscribeFunction
```

**Parameters**

- **`callback`** (`(info?: SaveRequestContext) => SaveRequestResponse`, required)
  Callback function for handling the event.

**Returns**: `UnsubscribeFunction`

### remove

Removes a Layout

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

**Parameters**

- **`type`** (`string`, required)
  Type of the Layout to remove.
- **`name`** (`string`, required)
  Name of the Layout to remove.

**Returns**: `Promise<void>`

### rename

Renames a Layout.

```ts
(layout: Layout, newName: string) => Promise<LayoutResult>
```

**Parameters**

- **`layout`** (`Layout`, required)
  Existing Layout to rename.
- **`newName`** (`string`, required)
  New name for the Layout.

**Returns**: `Promise<LayoutResult>`

### reset

Resets a Layout.

*Since: io.Connect Desktop 9.4, @interopio/desktop 6.6.0*

```ts
(options: ResetLayoutOptions) => Promise<RestoreResumeResult>
```

**Parameters**

- **`options`** (`ResetLayoutOptions`, required)
  Options for resetting a Layout.

**Returns**: `Promise<RestoreResumeResult>`

### restore

Restores a Layout.

```ts
(options: RestoreOptions) => Promise<RestoreResumeResult>
```

**Parameters**

- **`options`** (`RestoreOptions`, required)
  Options for restoring a Layout.

**Returns**: `Promise<RestoreResumeResult>`

### resume

Resumes a Layout.

```ts
(name: string, context?: any, options?: IOConnectDesktop.Layouts.ResumeOptions) => Promise<RestoreResumeResult>
```

**Parameters**

- **`name`** (`string`, required)
  Name of the Layout to resume.
- **`context`** (`any`, optional)
  Context for the Layout.
- **`options`** (`IOConnectDesktop.Layouts.ResumeOptions`, optional)
  Options for resuming a Layout.

**Returns**: `Promise<RestoreResumeResult>`

### save

Saves a new Layout.

```ts
(layout: NewLayoutOptions) => Promise<Layout>
```

**Parameters**

- **`layout`** (`NewLayoutOptions`, required)
  Options for saving a Layout.

**Returns**: `Promise<Layout>`

### setDefaultGlobal

Sets a new default Global Layout.

```ts
(name: string) => Promise<void>
```

**Parameters**

- **`name`** (`string`, required)
  Name of the Layout to set as the new default Global Layout.

**Returns**: `Promise<void>`

### updateAppContextInCurrent

Updates the context saved for your app in the currently loaded Layout.

```ts
(context: object) => Promise<void>
```

**Parameters**

- **`context`** (`object`, required)
  New context for the app.

**Returns**: `Promise<void>`

### updateDefaultContext

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

```ts
(context: object) => Promise<LayoutResult>
```

**Parameters**

- **`context`** (`object`, required)
  New context that will be saved as a default window context.

**Returns**: `Promise<LayoutResult>`

### updateMetadata

Updates the metadata of a Layout.

```ts
(layout: Layout) => Promise<void>
```

**Parameters**

- **`layout`** (`Layout`, required)
  Existing Layout to update.

**Returns**: `Promise<void>`

## Related types

- [GetContentsOptions](https://docs.interop.io/desktop/reference/javascript/layouts/getcontentsoptions/index.md)
- [GetRestoredLayoutsInfoResult](https://docs.interop.io/desktop/reference/javascript/layouts/getrestoredlayoutsinforesult/index.md)
- [HibernateResult](https://docs.interop.io/desktop/reference/javascript/layouts/hibernateresult/index.md)
- [HibernationOptions](https://docs.interop.io/desktop/reference/javascript/layouts/hibernationoptions/index.md)
- [ImportLayoutResult](https://docs.interop.io/desktop/reference/javascript/layouts/importlayoutresult/index.md)
- [ImportMode](https://docs.interop.io/desktop/reference/javascript/layouts/importmode/index.md)
- [Layout](https://docs.interop.io/desktop/reference/javascript/layouts/layout/index.md)
- [LayoutContents](https://docs.interop.io/desktop/reference/javascript/layouts/layoutcontents/index.md)
- [LayoutModifiedEvent](https://docs.interop.io/desktop/reference/javascript/layouts/layoutmodifiedevent/index.md)
- [LayoutResult](https://docs.interop.io/desktop/reference/javascript/layouts/layoutresult/index.md)
- [LayoutSummary](https://docs.interop.io/desktop/reference/javascript/layouts/layoutsummary/index.md)
- [LayoutType](https://docs.interop.io/desktop/reference/javascript/layouts/layouttype/index.md)
- [NewLayoutOptions](https://docs.interop.io/desktop/reference/javascript/layouts/newlayoutoptions/index.md)
- [ResetLayoutOptions](https://docs.interop.io/desktop/reference/javascript/layouts/resetlayoutoptions/index.md)
- [RestoreOptions](https://docs.interop.io/desktop/reference/javascript/layouts/restoreoptions/index.md)
- [RestoreResumeResult](https://docs.interop.io/desktop/reference/javascript/layouts/restoreresumeresult/index.md)
- [ResumeOptions](https://docs.interop.io/desktop/reference/javascript/layouts/resumeoptions/index.md)
- [SaveRequestContext](https://docs.interop.io/desktop/reference/javascript/layouts/saverequestcontext/index.md)
- [SaveRequestResponse](https://docs.interop.io/desktop/reference/javascript/layouts/saverequestresponse/index.md)
- [UnsubscribeFunction](https://docs.interop.io/desktop/reference/javascript/search/unsubscribefunction/index.md)