# API

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

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

Layouts API.

## Methods

### clearDefaultGlobal

Removes the default Global Layout.

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

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

### export

Returns a collection of all available `Layout` objects of the provided type.

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

**Parameters**

- **`layoutType`** (`LayoutType`, required)

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

### get

Fetches a saved Layout if a Layout with the provided name and type exists.

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

**Parameters**

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

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

### getAll

Returns a lightweight description of all Layouts of the provided type, without the extensive objects describing the Layout components.

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

**Parameters**

- **`type`** (`LayoutType`, required)
  Type of the Layouts to fetch.

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

### getCurrentLayout

Retrieves the current Global Layout. This is either the last restored Global Layout, or the last saved Global Layout that has been set as the current Global Layout.

*Since: io.Connect Browser 4.0*

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

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

### getDefaultGlobal

Retrieves the default Global Layout, if any.

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

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

### getGlobalTypeState

Checks whether Global Layouts are activated in the **io.Connect Browser** environment.

```ts
() => Promise<{ activated: boolean }>
```

**Returns**: `Promise<{ activated: boolean }>`

### 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: io.Connect Browser 4.5*

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

**Parameters**

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

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

### getMultiScreenPermissionState

Retrieves the browser Multi-Screen Window Placement permission state for the **io.Connect Browser** environment.

```ts
() => Promise<{ state: "prompt" | "granted" | "denied" }>
```

**Returns**: `Promise<{ state: "prompt" | "granted" | "denied" }>`

### import

Imports a collection of `Layout` objects.

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

**Parameters**

- **`layouts`** (`Layout[]`, required)
  An array of `Layout` objects to be imported.
- **`mode`** (`ImportMode`, optional)
  If `"replace"` (default), all existing Layouts will be removed. If `"merge"`, the Layouts will be added to the existing ones.

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

### onAdded

Notifies when a new Layout is added.

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

**Parameters**

- **`callback`** (`(layout: Layout) => void`, required)
  Callback function to handle the event. Receives the `Layout` object as an argument and returns an unsubscribe function.

**Returns**: `() => void`

### onChanged

Notifies when a Layout is modified.

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

**Parameters**

- **`callback`** (`(layout: Layout) => void`, required)
  Callback function to handle the event. Receives the `Layout` object as an argument and returns an unsubscribe function.

**Returns**: `() => void`

### onDefaultGlobalChanged

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

*Since: io.Connect Browser 4.0*

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

**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**: `() => void`

### onRemoved

Notifies when a Layout is removed.

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

**Parameters**

- **`callback`** (`(layout: Layout) => void`, required)
  Callback function to handle the event. Receives the `Layout` object as an argument and returns an unsubscribe function.

**Returns**: `() => void`

### onRenamed

Notifies when a Layout is renamed. Returns an unsubscribe function.

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

**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 argument an object with a `name` property holding the previous Layout name.

**Returns**: `() => void`

### onRestored

Notifies when a Layout is restored.

*Since: io.Connect Browser 4.0*

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

**Parameters**

- **`callback`** (`(layout: Layout) => void`, required)
  Callback function for handling the event. Receives as an argument the `Layout` object that was restored.

**Returns**: `() => void`

### onSaveRequested

Notifies when a Layout save operation is requested. Returns an unsubscribe function.

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

**Parameters**

- **`callback`** (`(info?: SaveRequestContext) => SaveRequestResponse`, required)
  Callback function for handling the event. The callback must return a `SaveRequestResponse` object containing
  context to be saved for the current window when the Layout is saved.
  When the Layout is saved and the `ignoreContexts` property of the `NewLayoutOptions` object is set to `true`, the returned context will be ignored.

**Returns**: `() => void`

### remove

Removes a Layout.

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

**Parameters**

- **`type`** (`LayoutType`, 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>`

### requestMultiScreenPermission

Opens the browser permission prompt requesting Multi-Screen Window Placement permission from the user for the **io.Connect Browser** environment.
This can only be requested from the Main app (Web Platform) due to the transient activation restrictions of the browsers.

```ts
() => Promise<{ permissionGranted: boolean }>
```

**Returns**: `Promise<{ permissionGranted: boolean }>`

### restore

Restores a Layout.

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

**Parameters**

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

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

### 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 Global Layout to set as default.

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

### 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/browser/reference/javascript/layouts/getcontentsoptions/index.md)
- [ImportMode](https://docs.interop.io/browser/reference/javascript/layouts/importmode/index.md)
- [Layout](https://docs.interop.io/browser/reference/javascript/layouts/layout/index.md)
- [LayoutContents](https://docs.interop.io/browser/reference/javascript/layouts/layoutcontents/index.md)
- [LayoutResult](https://docs.interop.io/browser/reference/javascript/layouts/layoutresult/index.md)
- [LayoutSummary](https://docs.interop.io/browser/reference/javascript/layouts/layoutsummary/index.md)
- [LayoutType](https://docs.interop.io/browser/reference/javascript/layouts/layouttype/index.md)
- [NewLayoutOptions](https://docs.interop.io/browser/reference/javascript/layouts/newlayoutoptions/index.md)
- [RestoreOptions](https://docs.interop.io/browser/reference/javascript/layouts/restoreoptions/index.md)
- [SaveRequestContext](https://docs.interop.io/browser/reference/javascript/layouts/saverequestcontext/index.md)
- [SaveRequestResponse](https://docs.interop.io/browser/reference/javascript/layouts/saverequestresponse/index.md)