Events

Subscribe to events and use the EventBus

Klyx provides an EventBus architecture for decoupled communication between plugins and the host application. Events are typed, support priority ordering, flow-based collection, and sticky events.

Accessing the EventBus

The EventBus is accessible through PluginContext:

// Inside a suspend function within a plugin:
val bus: EventBus = currentPluginContext().eventBus

// Or using the KlyxPlugin extension property:
val bus: EventBus = pluginContext.eventBus

Subscribing to events

Use the subscribe method with the event type and a handler lambda:

// Typed subscribe (reified)
bus.subscribe<FileOpenedEvent> { event ->
    // Handle file opened
}

Subscription options

// With priority (higher = delivered first)
bus.subscribe<SomeEvent>(priority = Priority.High) { event ->
    // ...
}

// With a filter
bus.subscribe<SomeEvent> { event ->
    event.query == "kotlin"
}

// With error handling
bus.subscribe<SomeEvent>(
    onError = { throwable, event ->
        // Handle error
    }
) { event ->
    // ...
}

// With a specific dispatcher
bus.subscribe<SomeEvent>(dispatcher = Dispatchers.IO) { event ->
    // ...
}

Subscription return value

subscribe returns an EventSubscription handle with a cancel() method:

val subscription: EventSubscription = bus.subscribe<MyEvent> { event ->
    // ...
}

// Later:
subscription.cancel()

Collecting as a Flow

Events can also be observed as a cold Flow:

// Typed asFlow (reified)
bus.asFlow<FileOpenedEvent>().collect { event ->
    // ...
}

// Or use the flowOf alias
bus.flowOf<FileOpenedEvent>().collect { event ->
    // ...
}

Waiting for a single event

// Wait for the next matching event
val event: FileOpenedEvent = bus.awaitFirst<FileOpenedEvent> {
    it.query == "kotlin"
}

Event priority

All subscriptions have a Priority level. Higher priority subscribers receive events first:

Priority	Description
Priority.Highest	Delivered before all other priorities
Priority.High	Delivered before normal priority
Priority.Normal	Default priority
Priority.Low	Delivered after normal priority
Priority.Lowest	Delivered after all other priorities

Sticky events

Sticky events are retained by the bus and immediately delivered to new subscribers. Sticky events are configured when creating the bus via EventBusConfigBuilder.

val bus = eventBus(viewModelScope) {
    enableStickyEvents = true
}

Managing sticky events

// Remove the sticky event for a type
bus.clearStickyEvent(SomeEvent::class)

// Remove all sticky events
bus.clearAllStickyEvents()

Common event types

Event	Description
FileOpenedEvent	A file was opened in the editor
NewSessionEvent	A new terminal session was created
SessionTerminateEvent	A terminal session was terminated
TerminalNotificationTapEvent	A terminal notification was tapped

FileOpenedEvent

data class FileOpenedEvent(
    val uri: Uri,
    val fileName: String,
    val tabId: String,
    val projectUri: Uri? = null
)

EventBus methods

Method	Description
publish(event)	Publish an event to all subscribers
tryPublish(event)	Attempt to publish without suspending
subscribe(type, handler)	Subscribe to events of a specific type
asFlow(type)	Get a Flow of events for a type
awaitFirst(type, filter)	Wait for the next matching event
subscriberCount(type)	Get the number of active subscribers
clearStickyEvent(type)	Remove the sticky event for a type
clearAllStickyEvents()	Remove all sticky events
reset()	Clear all subscriptions and sticky events
close()	Shut down the bus

Lifecycle

Event subscriptions remain active until explicitly cancelled or the bus is closed. For lifecycle-aware usage, tie subscriptions to a coroutine scope:

// Using subscribeIn (auto-cancels when scope completes)
bus.subscribeIn(lifecycleScope) { event: FileOpenedEvent ->
    // ...
}

// Using collectIn (auto-cancels when scope completes)
bus.asFlow<FileOpenedEvent>()
    .collectIn(lifecycleScope) { event ->
        // ...
    }

Publishing events

Plugins can publish their own events:

bus.publish(MyCustomEvent(data = "hello"))

// Or use the operator overload
bus += MyCustomEvent(data = "hello")

// Publish multiple events
bus.publishAll(event1, event2, event3)

Example

Subscribe to file open events and react to them:

override suspend fun onStart() {
    val bus = currentPluginContext().eventBus

    bus.subscribe<FileOpenedEvent> { event ->
        logger.d("File opened: ${event.fileName}")
    }

    // Collect as flow for UI
    bus.asFlow<FileOpenedEvent>()
        .mapNotNull { it.fileName }
        .distinctUntilChanged()
        .collect { fileName ->
            // Update UI
        }
}