# API

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

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

Window Management API.

## Properties

- **`groups`** (`GroupsAPI`, required)
  API for managing window groups.

## Methods

### autoArrange

Arranges the io.Connect Windows automatically in a grid on the specified display using the entire working area of the display.
If called a second time, and the user hasn't broken manually the window arrangement, the windows will be restored to their previous state.

*Since: io.Connect Desktop 9.1, @interopio/desktop 6.1.0*

```ts
(displayId?: number) => Promise<void>
```

**Parameters**

- **`displayId`** (`number`, optional)
  ID of the display on which to arrange the windows.

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

### configure

Configures global io.Connect Windows settings.

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

**Parameters**

- **`options`** (`WindowsConfiguration`, required)
  Configuration options.

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

### createFlydown

Creates a flydown window.

```ts
(targetWindowId: string, config: FlydownOptions) => Promise<Flydown>
```

**Parameters**

- **`targetWindowId`** (`string`, required)
  ID of the window for which to create the flydown.
- **`config`** (`FlydownOptions`, required)
  Options for creating a flydown window.

**Returns**: `Promise<Flydown>`

### createPopup

Creates a window to be used as a popup window. The created window will be frameless and hidden.

*Since: io.Connect Desktop 10.0, @interopio/desktop 6.16.0*

```ts
(options: CreatePopupOptions) => Promise<CreatePopupResult>
```

**Parameters**

- **`options`** (`CreatePopupOptions`, required)
  Options for creating a popup window.

**Returns**: `Promise<CreatePopupResult>`

### find

Finds a window by name.

```ts
(name: string, success?: (window: IOConnectWindow) => void, error?: (error: string) => void) => IOConnectWindow | undefined
```

**Parameters**

- **`name`** (`string`, required)
  Unique window name.
- **`success`** (`(window: IOConnectWindow) => void`, optional)
  Callback function for handling the successfully returned result.
- **`error`** (`(error: string) => void`, optional)
  Callback function for handling errors.

**Returns**: `IOConnectWindow | undefined`

### findById

Finds a window by ID.

```ts
(id: string, success?: (window: IOConnectWindow) => void, error?: (error: string) => void) => IOConnectWindow | undefined
```

**Parameters**

- **`id`** (`string`, required)
  Window ID.
- **`success`** (`(window: IOConnectWindow) => void`, optional)
  Callback function for handling the successfully returned result.
- **`error`** (`(error: string) => void`, optional)
  Callback function for handling errors.

**Returns**: `IOConnectWindow | undefined`

### list

Lists all windows.

```ts
(success?: (windows: IOConnectWindow[]) => void) => IOConnectWindow[]
```

**Parameters**

- **`success`** (`(windows: IOConnectWindow[]) => void`, optional)
  Callback function for handling the successfully returned result.

**Returns**: `IOConnectWindow[]`

### my

Retrieves the current window.

```ts
() => IOConnectWindow | undefined
```

**Returns**: `IOConnectWindow | undefined`

### onArrangementChanged

Notifies when io.Connect Windows are arranged automatically or restored to their previous state using the `autoArrange()` method.
The event will fire also when the user manually breaks the automatic window arrangement.

*Since: io.Connect Desktop 9.1, @interopio/desktop 6.1.0*

```ts
(callback: (data: { areWindowsArranged: boolean; displayId: number; }) => void) => UnsubscribeFunction
```

**Parameters**

- **`callback`** (`(data: { areWindowsArranged: boolean; displayId: number; }) => void`, required)
  Callback function for handling the event. Receives an object with `areWindowsArranged` and `displayId` properties.
  The `areWindowsArranged` flag will be set to `true` if the `autoArrange()` method is called initially for arranging the windows.
  When the method is called a second time for restoring the windows to their previous state, or the user manually breaks the window arrangement, the flag will be `false`.

**Returns**: `UnsubscribeFunction`

### onTabAttached

Notifies when a tab window is attached to a tab group.

```ts
(callback: (tabWindow: IOConnectWindow, newTabGroupId: string, tabHeaderVisible: boolean) => void) => UnsubscribeFunction
```

**Parameters**

- **`callback`** (`(tabWindow: IOConnectWindow, newTabGroupId: string, tabHeaderVisible: boolean) => void`, required)
  Callback function for handling the event.

**Returns**: `UnsubscribeFunction`

### onTabDetached

Notifies when a tab window is detached from a tab group.

```ts
(callback: (window: IOConnectWindow, tabGroupId: string, oldTabGroupId: string) => void) => UnsubscribeFunction
```

**Parameters**

- **`callback`** (`(window: IOConnectWindow, tabGroupId: string, oldTabGroupId: string) => void`, required)
  Callback function for handling the event.

**Returns**: `UnsubscribeFunction`

### onWindowAdded

Notifies when a new window is opened.

```ts
(callback: (window: IOConnectWindow) => void) => UnsubscribeFunction
```

**Parameters**

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

**Returns**: `UnsubscribeFunction`

### onWindowFrameColorChanged

Notifies when the window frame color is changed.

```ts
(callback: (window: IOConnectWindow) => void) => UnsubscribeFunction
```

**Parameters**

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

**Returns**: `UnsubscribeFunction`

### onWindowGotFocus

Notifies when a window receives focus.

```ts
(callback: (window: IOConnectWindow) => void) => UnsubscribeFunction
```

**Parameters**

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

**Returns**: `UnsubscribeFunction`

### onWindowLostFocus

Notifies when a window loses focus.

```ts
(callback: (window: IOConnectWindow) => void) => UnsubscribeFunction
```

**Parameters**

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

**Returns**: `UnsubscribeFunction`

### onWindowRemoved

Notifies when a window is closed.

```ts
(callback: (window: IOConnectWindow) => void) => UnsubscribeFunction
```

**Parameters**

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

**Returns**: `UnsubscribeFunction`

### open

Opens a new io.Connect Window.

```ts
(name: string, url: string, options?: WindowCreateOptions, success?: (window: IOConnectWindow) => void, error?: (error: string) => void) => Promise<IOConnectWindow>
```

**Parameters**

- **`name`** (`string`, required)
  Unique window name.
- **`url`** (`string`, required)
  URL to be loaded in the new window.
- **`options`** (`WindowCreateOptions`, optional)
  Options for creating a new window.
- **`success`** (`(window: IOConnectWindow) => void`, optional)
  Callback function for handling the successfully returned result.
- **`error`** (`(error: string) => void`, optional)
  Callback function for handling errors.

**Returns**: `Promise<IOConnectWindow>`

### ready

Notifies when the Window Management library has been fully initialized.

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

**Returns**: `Promise<any>`

### showPopup

Shows a popup window.
As of **io.Connect Desktop** 10.0, the popup window must be a frameless window.

```ts
(targetWindowId: string, config: PopupOptions) => Promise<void>
```

**Parameters**

- **`targetWindowId`** (`string`, required)
  ID of the window for which to show the popup.
- **`config`** (`PopupOptions`, required)
  Options for showing a popup window.

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

## Related types

- [CreatePopupOptions](https://docs.interop.io/desktop/reference/javascript/windows/createpopupoptions/index.md)
- [CreatePopupResult](https://docs.interop.io/desktop/reference/javascript/windows/createpopupresult/index.md)
- [Flydown](https://docs.interop.io/desktop/reference/javascript/windows/flydown/index.md)
- [FlydownOptions](https://docs.interop.io/desktop/reference/javascript/windows/flydownoptions/index.md)
- [GroupsAPI](https://docs.interop.io/desktop/reference/javascript/windows/groupsapi/index.md)
- [IOConnectWindow](https://docs.interop.io/desktop/reference/javascript/windows/ioconnectwindow/index.md)
- [PopupOptions](https://docs.interop.io/desktop/reference/javascript/windows/popupoptions/index.md)
- [UnsubscribeFunction](https://docs.interop.io/desktop/reference/javascript/search/unsubscribefunction/index.md)
- [WindowCreateOptions](https://docs.interop.io/desktop/reference/javascript/windows/windowcreateoptions/index.md)
- [WindowsConfiguration](https://docs.interop.io/desktop/reference/javascript/windows/windowsconfiguration/index.md)