# Events

Positron architecture relies heavily on events to manage communication between the Node.js main process, the native render process, and individual windows.

### App Events

These events are global to the application life cycle and are emitted either via internal application logic or forwarded directly from the native binary process over the WebSocket IPC channel.

#### Example

{% code lineNumbers="true" %}

```javascript
const { app } = require("positron.js")

app.events.on("event", data => {
console.log(data)
})
```

{% endcode %}

#### Events

| Event Name            | Triggered When...                                                                                 | Data Emitted (`msg.data`)                                    |
| --------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| `before-quit`         | `app.quit()` is explicitly called by the application before the process exits.                    | `undefined`                                                  |
| `capture-page-result` | Result from `capturePage()`                                                                       | Image in bas64                                               |
| *Custom IPC Events*   | Any unhandled, incoming WebSocket message event that doesn't match a default internal event case. | Depends on the message schema sent from the native renderer. |

### Window Events

The `Window` class extends Node’s `EventEmitter`. Each window instance emits specific lifecycle and state-change events. 

#### Example

{% code lineNumbers="true" %}

```javascript
mainWindow.on('ready', () => {
mainWindow.on('navigated', (targetPath) => {
  console.log(`Window navigated to: ${targetPath}`);
});
});
```

{% endcode %}

#### Lifecycle Events

| Event Name | Triggered When...                                                                      | Arguments passed to callback |
| ---------- | -------------------------------------------------------------------------------------- | ---------------------------- |
| `ready`    | The active WebSocket connection is open and ready to transmit commands to this window. | None                         |
| `created`  | `window.create()` is executed and the `createWindow` command is sent down the wire.    | None                         |
| `close`    | `window.close()` is called, setting the window's creation state back to false.         | None                         |

#### Navigation & Content Events

| Event Name          | Triggered When...                                                                                       | Arguments passed to callback                    |
| ------------------- | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
| `url-loaded`        | `window.loadURL(url)` is called to point the window to a web address.                                   | `url` *(String)*                                |
| `file-loaded`       | `window.loadFile(path)` is called to point the window to a local file path.                             | `path` *(String)*                               |
| `navigated`         | A wrapper event triggered whenever **either** `loadURL` or `loadFile` is executed.                      | `url` or `path` *(String)*                      |
| `navigated-forward` | `window.goForward()` is called to move forward in the browsing history.                                 | None                                            |
| `navigated-back`    | `window.goBack()` is called to move backward in the browsing history.                                   | None                                            |
| `user-script-added` | A custom script injection is registered via `addUserScript()` or loaded from `addUserScriptFromFile()`. | `{ content: String, filePath: String \| null }` |
| `reloaded`          | `window.reload()` is called to refresh the current page.                                                | None                                            |

#### Window State & UI Events

| Event Name               | Triggered When...                                                                               | Arguments passed to callback        |
| ------------------------ | ----------------------------------------------------------------------------------------------- | ----------------------------------- |
| `title-updated`          | `window.setTitle(title)` is called to update the native window header text.                     | `title` *(String)*                  |
| `menu-updated`           | `window.setMenu()` or `window.resetMenu()` changes the layout configuration of the window menu. | `menuTemplate` *(Object)* or `null` |
| `alert`                  | `window.alert(message)` triggers a native dialog alert command.                                 | `message` *(String)*                |
| `resized`                | `window.resize(width, height)` changes the window canvas dimensions.                            | `{ width: String, height: String }` |
| `devtools-opened`        | `window.openDevTools()` is invoked.                                                             | None                                |
| `fullscreen-toggled`     | `window.toggleFullscreen()` switches between windowed and fullscreen states.                    | None                                |
| `fullscreen-entered`     | `window.goFullscreen()` sets the window explicitly to full-screen.                              | None                                |
| `fullscreen-exited`      | `window.exitFullscreen()` leaves full-screen mode.                                              | None                                |
| `hidden`                 | `window.hide()` makes the window completely invisible.                                          | None                                |
| `shown`                  | `window.show()` unhides the window back onto the UI layer.                                      | None                                |
| `focused`                | `window.focus()` forces focus or brings the native window to the foreground.                    | None                                |
| `capture-page-requested` | `window.capturePage()` is called to capture a visual snapshot of the renderer.                  | None                                |

#### IPC Messaging Events

| Event Name     | Triggered When...                                                                                                    | Arguments passed to callback          |
| -------------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
| `command-sent` | Any backend layout command (like title updates, resizing, navigation) successfully sends down the WebSocket channel. | `{ command: String, args: String[] }` |
| `ipc-sent`     | `window.sendIpc(command, args)` explicitly pushes custom IPC payloads down to the renderer.                          | `{ command: String, args: Array }`    |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://positronjs.gitbook.io/v1/ipc/events.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.