# API

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

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

## Properties

- **`layouts`** (`WorkspaceLayoutsAPI`, required)
  An API which gives full read, write and delete access to the workspaces layouts.
- **`version`** (`string`, required)
  The io.Connect Workspaces API version.

## Methods

### createEmptyFrame

```ts
(definition?: EmptyFrameDefinition) => Promise<IOConnectWorkspaces.Frame>
```

**Parameters**

- **`definition`** (`EmptyFrameDefinition`, optional)
  Optional definition of the frame

**Returns**: `Promise<IOConnectWorkspaces.Frame>`

### createWorkspace

Opens a new workspace based on the provided definition.

```ts
(definition: WorkspaceDefinition, saveConfig?: WorkspaceCreateConfig) => Promise<Workspace>
```

**Parameters**

- **`definition`** (`WorkspaceDefinition`, required)
  An object describing the shape and options of the workspace.
- **`saveConfig`** (`WorkspaceCreateConfig`, optional)
  An object used to set various create options.

**Returns**: `Promise<Workspace>`

### getAllFrames

Returns all frames which satisfy the provided predicate. If no predicate is provided, will return all frames.

```ts
(predicate?: (frame: Frame) => boolean) => Promise<Frame[]>
```

**Parameters**

- **`predicate`** (`(frame: Frame) => boolean`, optional)
  A filtering function (predicate) called for each open frame.

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

### getAllWorkspaces

Returns all workspaces which satisfy the provided predicate. If no predicate is provided, will return all workspaces.

```ts
(predicate?: (workspace: Workspace) => boolean) => Promise<Workspace[]>
```

**Parameters**

- **`predicate`** (`(workspace: Workspace) => boolean`, optional)
  A filtering function (predicate) called for each open workspace.

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

### getAllWorkspacesSummaries

Returns an collection of objects, where each object contains basic information about an open workspace.
This function was designed for easy and quick listing of existing workspaces without adding the complexity of transmitting the entire structure of each workspace.

```ts
() => Promise<WorkspaceSummary[]>
```

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

### getBox

Returns the instance of the first box, which satisfies the provided predicate.
This function will search recursively in all open workspaces.

```ts
(predicate: (box: WorkspaceBox) => boolean) => Promise<WorkspaceBox>
```

**Parameters**

- **`predicate`** (`(box: WorkspaceBox) => boolean`, required)
  A filtering function (predicate) called for each box in each open workspace.

**Returns**: `Promise<WorkspaceBox>`

### getBuilder

Gets either a workspace or a box builder depending on the provided type inside the config object.
This builder is used to dynamically construct a workspace runtime.

```ts
(config: BuilderConfig) => WorkspaceBuilder | BoxBuilder
```

**Parameters**

- **`config`** (`BuilderConfig`, required)
  An object describing the type of the requested builder, alongside other settings.

**Returns**: `WorkspaceBuilder | BoxBuilder`

### getFrame

Returns the first frame instance which satisfies the provided predicate or undefined, if non do.

```ts
(predicate: (frame: Frame) => boolean) => Promise<Frame>
```

**Parameters**

- **`predicate`** (`(frame: Frame) => boolean`, required)
  A filtering function (predicate) called for each open frame.

**Returns**: `Promise<Frame>`

### getMyFrame

Returns the frame instance of the calling window. Throws an error if the calling window is not part of a workspace.

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

**Returns**: `Promise<Frame>`

### getMyWorkspace

Returns the instance of the workspace where the calling window is located.
Throws an error if the calling window is not not part of any workspace.

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

**Returns**: `Promise<Workspace>`

### getWindow

Returns the workspace window instance of the first window, which is part of a workspace and satisfies the provided predicate.
This function will search recursively in all open workspaces.

```ts
(predicate: (workspaceWindow: WorkspaceWindow) => boolean) => Promise<WorkspaceWindow>
```

**Parameters**

- **`predicate`** (`(workspaceWindow: WorkspaceWindow) => boolean`, required)
  A filtering function (predicate) called for each window in each open workspace.

**Returns**: `Promise<WorkspaceWindow>`

### getWorkspace

Returns the first workspace instance which satisfies the provided predicate or undefined, if non do.

```ts
(predicate: (workspace: Workspace) => boolean) => Promise<Workspace>
```

**Parameters**

- **`predicate`** (`(workspace: Workspace) => boolean`, required)
  A filtering function (predicate) called for each open workspace.

**Returns**: `Promise<Workspace>`

### getWorkspaceById

Returns an instance of the workspace with the passed id. The performance is better than getWorkspace when querying for a workspace by id.

```ts
(workspaceId: string) => Promise<Workspace>
```

**Parameters**

- **`workspaceId`** (`string`, required)
  The id of the desired workspace

**Returns**: `Promise<Workspace>`

### inWorkspace

Checks whether or not the calling window is currently present inside of a workspace

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

**Returns**: `Promise<boolean>`

### onFrameClosed

Notifies when a new frame was closed and returns an unsubscribe function.

```ts
(callback: (closed: FrameClosedData) => void) => Promise<Unsubscribe>
```

**Parameters**

- **`callback`** (`(closed: FrameClosedData) => void`, required)
  Callback function to handle the event. Receives an object containing the id of the closed frame as a parameter.

**Returns**: `Promise<Unsubscribe>`

### onFrameOpened

Notifies when a new frame was opened and returns an unsubscribe function.

```ts
(callback: (frame: Frame) => void) => Promise<Unsubscribe>
```

**Parameters**

- **`callback`** (`(frame: Frame) => void`, required)
  Callback function to handle the event. Receives the added frame as a parameter.

**Returns**: `Promise<Unsubscribe>`

### onWindowAdded

Notifies when a new window was added to any workspace in any frame and returns an unsubscribe function.
An added window means that the window has a place in a workspace (it is a valid workspace element), but does not guarantee that the contents of the window are loaded.

```ts
(callback: (workspaceWindow: WorkspaceWindow) => void) => Promise<Unsubscribe>
```

**Parameters**

- **`callback`** (`(workspaceWindow: WorkspaceWindow) => void`, required)
  Callback function to handle the event. Receives the added window as a parameter.

**Returns**: `Promise<Unsubscribe>`

### onWindowLoaded

Notifies when a window's content was loaded in any workspace in any frame and returns an unsubscribe function.
A loaded window is a window, which was added to a workspace, it's contents were loaded and it is present in the windows collection.

```ts
(callback: (workspaceWindow: WorkspaceWindow) => void) => Promise<Unsubscribe>
```

**Parameters**

- **`callback`** (`(workspaceWindow: WorkspaceWindow) => void`, required)
  Callback function to handle the event. Receives the loaded window as a parameter.

**Returns**: `Promise<Unsubscribe>`

### onWindowMaximized

Notifies when a window was maximized in any workspace in any frame and returns an unsubscribe function.
A maximized window means that the window has been maximized either by an API call or from the maximize button by the user.

```ts
(callback: (workspaceWindow: IOConnectWorkspaces.WorkspaceWindow) => void) => Promise<IOConnectWorkspaces.Unsubscribe>
```

**Parameters**

- **`callback`** (`(workspaceWindow: IOConnectWorkspaces.WorkspaceWindow) => void`, required)
  Callback function to handle the event. Receives the maximized window as a parameter.

**Returns**: `Promise<IOConnectWorkspaces.Unsubscribe>`

### onWindowRemoved

Notifies when a window was removed from any workspace and any frame and returns an unsubscribe function.

```ts
(callback: (removed: { windowId?: string; workspaceId: string; frameId: string }) => void) => Promise<Unsubscribe>
```

**Parameters**

- **`callback`** (`(removed: { windowId?: string; workspaceId: string; frameId: string }) => void`, required)
  Callback function to handle the event. Receives an object containing the ids of the removed window, and the respective workspace and frame as a parameter.

**Returns**: `Promise<Unsubscribe>`

### onWindowRestored

Notifies when a window was restored from a maximized state in any workspace in any frame and returns an unsubscribe function.
A restored window means that the window has been restored from a maximized state either by an API call or from the restore button by the user.

```ts
(callback: (workspaceWindow: IOConnectWorkspaces.WorkspaceWindow) => void) => Promise<IOConnectWorkspaces.Unsubscribe>
```

**Parameters**

- **`callback`** (`(workspaceWindow: IOConnectWorkspaces.WorkspaceWindow) => void`, required)
  Callback function to handle the event. Receives the restored window as a parameter.

**Returns**: `Promise<IOConnectWorkspaces.Unsubscribe>`

### onWindowSelected

Notifies when a window was selected in any frame and returns an unsubscribe function.

```ts
(callback: (workspaceWindow: IOConnectWorkspaces.WorkspaceWindow) => void) => Promise<IOConnectWorkspaces.Unsubscribe>
```

**Parameters**

- **`callback`** (`(workspaceWindow: IOConnectWorkspaces.WorkspaceWindow) => void`, required)
  Callback function to handle the event. Receives the selected window as a parameter.

**Returns**: `Promise<IOConnectWorkspaces.Unsubscribe>`

### onWindowTabReordered

Notifies when the tab of a Workspace window participating in any Workspace in any Workspaces App has been reordered. Returns an unsubscribe function.

*Since: io.Connect Browser 4.4*

```ts
(callback: (workspaceWindow: IOConnectWorkspaces.WorkspaceWindow) => void) => Promise<IOConnectWorkspaces.Unsubscribe>
```

**Parameters**

- **`callback`** (`(workspaceWindow: IOConnectWorkspaces.WorkspaceWindow) => void`, required)
  Callback function for handling the event. Receives as an argument the `WorkspaceWindow` object describing the Workspace window whose tab has been reordered.
  *Available only in **io.Connect Browser**.*

**Returns**: `Promise<IOConnectWorkspaces.Unsubscribe>`

### onWorkspaceClosed

Notifies when a workspace present in any of the opened frames was closed and returns an unsubscribe function.

```ts
(callback: (closed: WorkspaceClosedData) => void) => Promise<Unsubscribe>
```

**Parameters**

- **`callback`** (`(closed: WorkspaceClosedData) => void`, required)
  Callback function to handle the event. Receives an object with the closed workspace id and frame id as a parameter.

**Returns**: `Promise<Unsubscribe>`

### onWorkspaceHibernated

Notifies when a Workspace is hibernated.
This event will be fired for any Workspace hibernated in any currently running instance of a Workspaces App.
Returns an unsubscribe function.

```ts
(callback: (workspace: IOConnectWorkspaces.Workspace) => void) => Promise<IOConnectWorkspaces.Unsubscribe>
```

**Parameters**

- **`callback`** (`(workspace: IOConnectWorkspaces.Workspace) => void`, required)
  Callback function for handling the event. Receives as an argument the `Workspace` object describing the hibernated Workspace.

**Returns**: `Promise<IOConnectWorkspaces.Unsubscribe>`

### onWorkspaceOpened

Notifies when a new workspace was opened in any of the opened frames and returns an unsubscribe function.

```ts
(callback: (workspace: Workspace) => void) => Promise<Unsubscribe>
```

**Parameters**

- **`callback`** (`(workspace: Workspace) => void`, required)
  Callback function to handle the event. Receives the added workspace as a parameter.

**Returns**: `Promise<Unsubscribe>`

### onWorkspaceResumed

Notifies when a Workspace is resumed after being hibernated.
This event will be fired for any Workspace resumed in any currently running instance of a Workspaces App.
Returns an unsubscribe function.

```ts
(callback: (workspace: IOConnectWorkspaces.Workspace) => void) => Promise<IOConnectWorkspaces.Unsubscribe>
```

**Parameters**

- **`callback`** (`(workspace: IOConnectWorkspaces.Workspace) => void`, required)
  Callback function for handling the event. Receives as an argument the `Workspace` object describing the resumed Workspace.

**Returns**: `Promise<IOConnectWorkspaces.Unsubscribe>`

### onWorkspaceTabReordered

Notifies when the tab of any Workspace in any Workspaces App has been reordered. Returns an unsubscribe function.

*Since: io.Connect Browser 4.4*

```ts
(callback: (workspace: IOConnectWorkspaces.Workspace) => void) => Promise<IOConnectWorkspaces.Unsubscribe>
```

**Parameters**

- **`callback`** (`(workspace: IOConnectWorkspaces.Workspace) => void`, required)
  Callback function for handling the event. Receives as an argument the `Workspace` object describing the Workspace whose tab has been reordered.
  *Available only in **io.Connect Browser**.*

**Returns**: `Promise<IOConnectWorkspaces.Unsubscribe>`

### restoreWorkspace

Opens a new workspace by restoring a previously saved workspace layout.

```ts
(name: string, options?: RestoreWorkspaceConfig) => Promise<Workspace>
```

**Parameters**

- **`name`** (`string`, required)
  The name of a saved workspace layout, which will be restored.
- **`options`** (`RestoreWorkspaceConfig`, optional)
  An optional object containing various workspace restore options.

**Returns**: `Promise<Workspace>`

### waitForFrame

Wait for a frame with the specified id to be loaded.
It's needed when using the workspaces-api from a custom workspaces frame and you have the frameId,
but the frame object is not populated in the API yet (e.g. the frame is in the pool)

```ts
(id: string) => Promise<Frame>
```

**Parameters**

- **`id`** (`string`, required)
  the id of the frame that should be waited

**Returns**: `Promise<Frame>`

## Related types

- [BoxBuilder](https://docs.interop.io/desktop/reference/javascript/workspaces/boxbuilder/index.md)
- [BuilderConfig](https://docs.interop.io/desktop/reference/javascript/workspaces/builderconfig/index.md)
- [EmptyFrameDefinition](https://docs.interop.io/desktop/reference/javascript/workspaces/emptyframedefinition/index.md)
- [Frame](https://docs.interop.io/desktop/reference/javascript/workspaces/frame/index.md)
- [FrameClosedData](https://docs.interop.io/desktop/reference/javascript/workspaces/framecloseddata/index.md)
- [RestoreWorkspaceConfig](https://docs.interop.io/desktop/reference/javascript/workspaces/restoreworkspaceconfig/index.md)
- [Unsubscribe](https://docs.interop.io/desktop/reference/javascript/workspaces/unsubscribe/index.md)
- [Workspace](https://docs.interop.io/desktop/reference/javascript/workspaces/workspace/index.md)
- [WorkspaceBox](https://docs.interop.io/desktop/reference/javascript/workspaces/workspacebox/index.md)
- [WorkspaceBuilder](https://docs.interop.io/desktop/reference/javascript/workspaces/workspacebuilder/index.md)
- [WorkspaceClosedData](https://docs.interop.io/desktop/reference/javascript/workspaces/workspacecloseddata/index.md)
- [WorkspaceCreateConfig](https://docs.interop.io/desktop/reference/javascript/workspaces/workspacecreateconfig/index.md)
- [WorkspaceDefinition](https://docs.interop.io/desktop/reference/javascript/workspaces/workspacedefinition/index.md)
- [WorkspaceLayoutsAPI](https://docs.interop.io/desktop/reference/javascript/workspaces/workspacelayoutsapi/index.md)
- [WorkspaceSummary](https://docs.interop.io/desktop/reference/javascript/workspaces/workspacesummary/index.md)
- [WorkspaceWindow](https://docs.interop.io/desktop/reference/javascript/workspaces/workspacewindow/index.md)