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. Navigation is handled through the Navigator service.

ScreenRegistry

Register screens during onLoad() and unregister them in onUnload(). Registration uses Kotlin context receivers — you do not pass the plugin instance explicitly.

Register a screen

private val screens: ScreenRegistry by plugin()

// Inside a KlyxPlugin method:
screens.register(
    Screen(
        id = ScreenId("myext.main"),
        content = { MainScreen() }
    )
)

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

"com.myext.screenname"

Unregister a screen

screens.unregister(ScreenId("myext.main"))

Set screen content

Replace an existing screen’s composable without unregistering:

screens[ScreenId("myext.main")] = { UpdatedMainScreen() }

Get screen content

Retrieve a registered screen’s composable:

val content: Content? = screens[ScreenId("myext.main")]

Check ownership

val ownerPluginId: String? = screens.ownerOf(ScreenId("myext.main"))

Transient screens

setTransient registers short-lived content that shadows any previously registered screen for the same id. unregisterTransient removes it and restores the previous registration. The host auto-unregisters transient screens when their navigation entry is popped, so you normally don’t need to clean them up manually — see openScreen.

screens.setTransient(ScreenId("myext.preview")) { PreviewScreen(uri) }

// Optional; the host also removes it when the screen is popped:
screens.unregisterTransient(ScreenId("myext.preview"))

Use register for screens that should persist for the plugin’s lifetime, and setTransient for one-shot screens opened on demand.

Navigation

Use the Navigator service to navigate between destinations.

private val navigator: Navigator by plugin()

Navigate to a destination

navigator.navigateTo(NavDestination.Home)
navigator.navigateTo(NavDestination.Settings)
navigator.navigateTo(NavDestination.Terminal)
navigator.navigateTo(NavDestination.Custom(ScreenId("myext.main")))

You can also use the convenience extension:

navigator.navigateTo(ScreenId("myext.main"))

Open a screen with inline content

Open a screen directly from a composable, without pre-registering it. Because the content is a closure, it can capture any data the screen needs — a file, a URI, a result object — giving custom screens the same payload support that custom editor tabs have:

navigator.openScreen(ScreenId("myext.html.preview")) {
    HtmlPreviewScreen(uri = fileUri)
}

The screen is registered as a transient screen: the host auto-unregisters it when its navigation entry is popped, so no cleanup is required. openScreen also returns a ScreenRegistration if you want to remove it earlier:

val registration = navigator.openScreen(ScreenId("myext.preview")) { PreviewScreen(uri) }
// ...
registration.unregister()

This works from any plugin code — toolbar actions, settings, lifecycle methods. File runners use the same API via their FileRunnerContext.

Navigate back

navigator.navigateBack()

NavDestination

A sealed class representing destinations within the app.

Destination	Description
NavDestination.Home	The main Klyx home screen
NavDestination.Settings	The application settings screen
NavDestination.Terminal	The integrated terminal screen
NavDestination.Custom(ScreenId)	A screen registered by a plugin

SpecialScreens

Pre-built ScreenId constants for core destinations:

SpecialScreens.Home       // ScreenId("<klyx-home>")
SpecialScreens.Settings   // ScreenId("<klyx-settings>")
SpecialScreens.Terminal   // ScreenId("<klyx-terminal>")

API reference

ScreenId

Element	Type	Description
ScreenId(id)	value class	Wraps a unique screen identifier string

Screen

Property	Type	Description
id	ScreenId	Unique identifier for the screen
content	@Composable () -> Unit	The Compose UI content

ScreenRegistration

Method	Description
unregister()	Removes the screen from the registry

ScreenRegistry

Method	Returns	Description
register(screen)	ScreenRegistration	Register a screen (requires KlyxPlugin context)
unregister(id)		Unregister a screen by ID
set(id, content)		Update screen content via operator (removes any transient screen)
setTransient(id, content)		Register short-lived content, shadowing any previous registration
unregisterTransient(id)		Remove a transient screen, restoring the previous registration
get(id)	Content?	Get screen content via operator (transient takes precedence)
ownerOf(id)	String?	Get the owning plugin ID

Navigator

Method	Returns	Description
navigateTo(destination)		Navigate to a destination
navigateBack()		Go back to the previous screen
openScreen(screenId, content)	ScreenRegistration	Register the composable for the id and navigate to it; auto-unregistered when the screen is popped

LocalTabs

A CompositionLocal providing access to the Tabs service for managing workspace tabs.

Example

Register multiple screens during onLoad():

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. Toolbar actions navigate to these screens:

toolbar.register(ToolbarAction(
    id = "demo.show_main",
    label = "Sample Plugin",
    onClick = { navigator.navigateTo(ScreenId("demo.main")) }
) {})