plushie/subscription

Subscription types for ongoing event sources.

Return subscriptions from the subscribe callback. The runtime diffs the list each cycle using key/1: subscriptions with the same key are considered identical and kept alive; new keys trigger a subscribe message to the renderer, and removed keys trigger an unsubscribe.

Timer subscriptions have a tag that appears in the TimerTick event, giving each timer a stable identity.

Renderer subscriptions use a tag for internal management only; this tag never appears in delivered events. Their identity is derived from (kind, window_id).

Subscriptions can be scoped to a specific window using set_window or for_window. Window-scoped subscriptions only receive events from the given window; unscoped subscriptions receive events from all windows.

Types

RendererSubKind

</>

Event source kinds for renderer subscriptions.

pub type RendererSubKind {
  KeyPress
  KeyRelease
  ModifiersChanged
  WindowClose
  WindowEvent
  WindowOpen
  WindowResize
  WindowFocus
  WindowUnfocus
  WindowMove
  PointerMove
  PointerButton
  PointerScroll
  PointerTouch
  Ime
  ThemeChange
  AnimationFrame
  FileDrop
  AllEvents
}

Constructors

```
KeyPress
```
```
KeyRelease
```
```
ModifiersChanged
```
```
WindowClose
```
```
WindowEvent
```
```
WindowOpen
```
```
WindowResize
```
```
WindowFocus
```
```
WindowUnfocus
```
```
WindowMove
```
```
PointerMove
```
```
PointerButton
```
```
PointerScroll
```
```
PointerTouch
```
```
Ime
```
```
ThemeChange
```
```
AnimationFrame
```
```
FileDrop
```
```
AllEvents
```
Catch-all: receives all renderer events.

Subscription

</>

pub type Subscription {
  Every(interval_ms: Int, tag: String)
  Renderer(
    kind: RendererSubKind,
    max_rate: option.Option(Int),
    window_id: option.Option(String),
  )
}

Constructors

```
Every(interval_ms: Int, tag: String)
```
Timer that fires every interval_ms milliseconds. Delivers a TimerTick event with the given tag to update.

Renderer(
  kind: RendererSubKind,
  max_rate: option.Option(Int),
  window_id: option.Option(String),
)

A renderer event subscription. The renderer filters and delivers matching events to the runtime.

SubscriptionKey

</>

Unique identity for subscription diffing.

pub type SubscriptionKey {
  TimerKey(interval_ms: Int, tag: String)
  RendererKey(kind: String, window_id: option.Option(String))
}

Constructors

```
TimerKey(interval_ms: Int, tag: String)
```
```
RendererKey(kind: String, window_id: option.Option(String))
```
Renderer sub identity is (kind, window_id). Two renderer subs of the same kind and window scope are the same subscription.

Values

every

</>

pub fn every(interval_ms: Int, tag: String) -> Subscription

Timer that fires every interval_ms milliseconds. Delivers a TimerTick event with the given tag to update.

for_window

</>

pub fn for_window(
  window_id: String,
  subscriptions: List(Subscription),
) -> List(Subscription)

Scope a list of subscriptions to a specific window. Convenience for applying set_window to each subscription.

subscription.for_window("editor", [
  subscription.on_key_press(),
  subscription.on_pointer_move() |> subscription.set_max_rate(60),
])

get_max_rate

</>

pub fn get_max_rate(sub: Subscription) -> option.Option(Int)

Get the max_rate from any subscription. Returns None for timer subscriptions and renderer subs without a rate.

get_window_id

</>

pub fn get_window_id(sub: Subscription) -> option.Option(String)

Get the window_id scope from a subscription. Returns None for timer subscriptions and unscoped renderer subs.

key

</>

pub fn key(sub: Subscription) -> SubscriptionKey

Compute the unique key for a subscription (used for diffing).

on_animation_frame

</>

pub fn on_animation_frame() -> Subscription

Subscribe to animation frame events (vsync ticks).

on_event

</>

pub fn on_event() -> Subscription

Subscribe to all renderer events (catch-all).

on_file_drop

</>

pub fn on_file_drop() -> Subscription

Subscribe to file drop events. Also delivers file hovered and hover-left events.

on_ime

</>

pub fn on_ime() -> Subscription

Subscribe to IME (Input Method Editor) events for international text input.

on_key_press

</>

pub fn on_key_press() -> Subscription

Subscribe to key press events.

on_key_release

</>

pub fn on_key_release() -> Subscription

Subscribe to key release events.

on_modifiers_changed

</>

pub fn on_modifiers_changed() -> Subscription

Subscribe to keyboard modifier state changes (shift, ctrl, alt, etc.).

on_pointer_button

</>

pub fn on_pointer_button() -> Subscription

Subscribe to pointer button press and release events (mouse or touch).

on_pointer_move

</>

pub fn on_pointer_move() -> Subscription

Subscribe to pointer movement events (mouse or touch). Also delivers enter and exit events for cursor enter/leave.

on_pointer_scroll

</>

pub fn on_pointer_scroll() -> Subscription

Subscribe to pointer scroll events.

on_pointer_touch

</>

pub fn on_pointer_touch() -> Subscription

Subscribe to touch events (pressed, moved, lifted, lost).

on_theme_change

</>

pub fn on_theme_change() -> Subscription

Subscribe to system theme changes (light/dark mode).

on_window_close

</>

pub fn on_window_close() -> Subscription

Subscribe to window close request events.

on_window_event

</>

pub fn on_window_event() -> Subscription

Subscribe to all window events (resize, move, focus, etc.). If both this and a specific subscription (e.g. on_window_resize) are active, matching events are delivered twice.

on_window_focus

</>

pub fn on_window_focus() -> Subscription

Subscribe to window focus gained events.

on_window_move

</>

pub fn on_window_move() -> Subscription

Subscribe to window move events.

on_window_open

</>

pub fn on_window_open() -> Subscription

Subscribe to window open events.

on_window_resize

</>

pub fn on_window_resize() -> Subscription

Subscribe to window resize events.

on_window_unfocus

</>

pub fn on_window_unfocus() -> Subscription

Subscribe to window focus lost events.

set_max_rate

</>

pub fn set_max_rate(sub: Subscription, rate: Int) -> Subscription

Set the max_rate on a renderer subscription. The renderer coalesces events beyond this rate (events per second). Has no effect on timer subscriptions.

A rate of zero means “track only, never emit”: the renderer tracks the event source but suppresses delivery entirely.

set_window

</>

pub fn set_window(
  sub: Subscription,
  window_id: String,
) -> Subscription

Scope a subscription to a specific window. The renderer only delivers events from the given window. Without a window scope, events from all windows are delivered.

timer_tag

</>

pub fn timer_tag(sub: Subscription) -> String

Get the tag from a timer subscription. Returns the tag that appears in TimerTick events.

wire_kind

</>

pub fn wire_kind(sub: Subscription) -> String

Wire format kind string for a subscription.

wire_tag

</>

pub fn wire_tag(sub: Subscription) -> String

Derive the wire tag sent to the renderer. The tag is the stable identity for this subscription entry in the renderer’s storage. Window-scoped subscriptions include the window_id so they don’t collide with global subscriptions of the same kind.