events

type Event ¶

type Event struct {
	Kind Kind
	// ElementRef is a best-effort qualified reference to the affected
	// element, when the backend can map the raw native event onto a live
	// Manager snapshot ref. It is frequently empty: events are a wake-up
	// signal, not a source of truth -- WaitFor always re-evaluates the
	// actual condition against the backend rather than trusting this
	// field, so an empty ElementRef never blocks correctness.
	ElementRef core.ElementRef
	// AppID/WindowID identify the owning application/window when the
	// backend can cheaply provide them.
	AppID    string
	WindowID string
	// Timestamp is when this package observed the event (not necessarily
	// when the backend/OS generated it).
	Timestamp time.Time
	// Details carries whatever raw, backend-specific information is
	// useful for diagnostics (e.g. the native signal member name, the CDP
	// node id). Not part of the stable cross-backend contract.
	Details map[string]any
}

Event is one backend-reported UI change.

type EventBus ¶

type EventBus struct {
	// contains filtered or unexported fields
}

EventBus fans a single upstream event source (typically one long-lived, backend-specific listener -- a D-Bus signal match, a CDP ListenTarget handler, ...) out to any number of independent waiters, each with its own buffered channel so one slow consumer never blocks another or the publisher.

func NewEventBus() *EventBus

func (b *EventBus) Close()

func (b *EventBus) Len() int

func (b *EventBus) Publish(ev Event)

func (b *EventBus) Subscribe(buffer int) (<-chan Event, func())

type Kind ¶

type Kind string

Kind enumerates the accessibility event categories a Subscriber can report. This is a deliberately small, backend-agnostic vocabulary; a backend maps its native event/signal names onto these.

const (
	// KindCreated signals a new element appeared (e.g. AT-SPI
	// ChildrenChanged:add, CDP DOM.childNodeInserted).
	KindCreated Kind = "created"
	// KindDestroyed signals an element disappeared/was removed.
	KindDestroyed Kind = "destroyed"
	// KindPropertyChanged signals a generic attribute/state change that
	// isn't more specifically a focus or value change.
	KindPropertyChanged Kind = "propertychanged"
	// KindFocusChanged signals keyboard focus moved.
	KindFocusChanged Kind = "focuschanged"
	// KindValueChanged signals an element's value/text content changed.
	KindValueChanged Kind = "valuechanged"
)

type Subscriber ¶

type Subscriber interface {
	Subscribe(ctx context.Context, scope core.Scope) (<-chan Event, func(), error)
}

Subscriber is implemented by a core.Backend that can push live UI events for a scope instead of being polled. It is intentionally a separate, optional interface (like core.Backend's own PhysicalInput/screen split) so a backend that cannot genuinely support it simply does not implement it -- callers detect support via a type assertion (backend.(events.Subscriber)) and fall back to polling, never a runtime panic or a faked capability.

Subscribe returns a channel of events (closed when the subscription ends, e.g. the backend connection drops) and an idempotent unsubscribe func. Implementations must never block the caller of Subscribe itself on waiting for an actual event; event delivery afterwards is best-effort/buffered (a slow consumer may miss events -- WaitFor always re-checks the real condition, so a missed event only costs a slightly later re-check).