> ## Documentation Index
> Fetch the complete documentation index at: https://klyx.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Screens & Navigation

> Register composable screens and navigate between them

Extensions can register custom screens that appear in Klyx's navigation system. Screens are Jetpack Compose composables identified by a `ScreenId`.

## ScreenRegistry

Register screens during `onLoad()` and unregister them in `onUnload()`.

### Register a screen

```kotlin theme={null}
screens.register(
    this,
    Screen(
        id = ScreenId("myext.main"),
        content = { MainScreen() }
    )
)
```

The `ScreenId` is a value class wrapping a string. By convention, use reverse-domain notation:

```text theme={null}
"com.myext.screenname"
```

### Unregister a screen

```kotlin theme={null}
screens.unregister(ScreenId("myext.main"))
```

### Set screen content

Replace an existing screen's composable without unregistering:

```kotlin theme={null}
screens.set(ScreenId("myext.main")) {
    UpdatedMainScreen()
}
```

### Get screen content

Retrieve a registered screen's composable:

```kotlin theme={null}
val content: (@Composable () -> Unit)? = screens.get(ScreenId("myext.main"))
```

## Navigation

Use the `Navigator` service to navigate between destinations.

```kotlin theme={null}
private val navigator: Navigator by plugin()
```

### Navigate to a destination

```kotlin theme={null}
navigator.navigateTo(NavDestination.Home)
navigator.navigateTo(NavDestination.Settings)
navigator.navigateTo(NavDestination.Terminal)
navigator.navigateTo(NavDestination.Custom(ScreenId("myext.main")))
```

### Navigate back

```kotlin theme={null}
navigator.navigateBack()
```

## Example from SamplePlugin

The [SamplePlugin](https://github.com/klyx-dev/SamplePlugin) registers seven screens during `onLoad()`:

```kotlin theme={null}
screens[ScreenId("demo.main")] = { MainDemoScreen(...) }
screens[ScreenId("demo.process")] = { ProcessDemoScreen(fileSystem) }
screens[ScreenId("demo.filesystem")] = { FileSystemDemoScreen(fileSystem) }
screens[ScreenId("demo.editor")] = { EditorDemoScreen(fileSystem) }
screens[ScreenId("demo.services")] = { ServiceDemoScreen() }
screens[ScreenId("demo.terminal")] = { TerminalDemoScreen() }
screens[ScreenId("demo.events")] = { EventDemoScreen() }
screens[ScreenId("demo.utilities")] = { UtilityDemoScreen() }
```

Each screen is a Composable function that receives the services it needs as parameters. The toolbar actions navigate to these screens:

```kotlin theme={null}
onClick = { navigator.navigateTo(NavDestination.Custom(ScreenId("demo.main"))) }
```

## API reference

### ScreenRegistry

| Function                   | Returns              | Description           |
| -------------------------- | -------------------- | --------------------- |
| `register(plugin, Screen)` | `ScreenRegistration` | Register a screen     |
| `unregister(ScreenId)`     |                      | Unregister a screen   |
| `set(ScreenId, content)`   |                      | Update screen content |
| `get(ScreenId)`            | `Content?`           | Get screen content    |

### Navigator

| Function                     | Description                |
| ---------------------------- | -------------------------- |
| `navigateTo(NavDestination)` | Navigate to a destination  |
| `navigateBack()`             | Go back to previous screen |

### NavDestination

| Option                            | Description                   |
| --------------------------------- | ----------------------------- |
| `NavDestination.Home`             | Klyx home screen              |
| `NavDestination.Settings`         | Settings screen               |
| `NavDestination.Terminal`         | Terminal screen               |
| `NavDestination.Custom(ScreenId)` | A registered extension screen |