Event API

Declared by <huxerui/event.h>.

Interaction and input values

• InteractionState: enabled, hovered, pressed, focused, and focus-visible state.
• InteractionEvent::Type: Press, Release, or Cancel; InteractionEvent::Source: Pointer or Keyboard.
• InteractionEvent: type, source, matching press_id, and optional node-local pointer position.
• PointerEventType: Down, Up, Move, or Cancel; PointerDeviceKind: Mouse, Touch, or Pen.
• PointerEvent: type, pointer ID, window-local position, device kind, changed/pressed buttons, and modifiers.
• ScrollInputEvent: window-local wheel/trackpad position, both delta axes, and modifiers.
• Key: portable key identity, including navigation keys such as Tab, Enter, and ArrowLeft, letters, digits, function keys, keypad keys, and left/right modifier keys.
• KeyEventType: Down or Up; KeyModifiers carries Shift, Control, Alt, and Meta flags.
• KeyEvent: type, key, text, modifiers, and repeat state.
• BackPhase: Begin, Update, Cancel, or Commit; BackEvent carries phase and progress.

Event<Result(Arguments...)>

A key derives from a complete function signature, such as Event<void(int)> for notification or Event<bool(const KeyEvent&)> for a synchronous decision. Its type is the identity. Result-bearing emission returns an optional result when a handler is connected.

Built-in event groups

• ViewEvents: Click, Pointer, PointerIntercept, Hover, ScrollInput, FocusChanged, KeyDown, KeyUp, KeyIntercept, ContextMenuRequested, and BackRequested.
• ToggleEvents::Changed(bool).
• SliderEvents::Changed(float).
• SegmentedButtonEvents::Changed(std::size_t).
• TabsEvents::Changed(std::size_t).
• NavigationEvents::Changed(std::size_t).
• DrawerEvents::OpenChanged(bool).
• TextFieldEvents::Changed(const TextEditingValue&) and Submitted().

Binding and emission

View::On<Key>(handler) binds a callable compatible with Key::Signature to that view declaration. UseEvents() returns a copyable EventEmitter; emitter.Emit<Key>(arguments...) sends a component-owned event through the current scope. EventEmitter::IsConnected() reports whether that scope still owns the event channel.

Binding, lifetime, and coordinates

Handlers are copied into the transient View declaration and reconciled with its mounted node. They run on the Runtime UI thread and remain installed only while that node or scope is mounted. OnClick is the built-in activation event and also installs default indication; use On<Key> for another typed semantic event.

ViewEvents::Pointer and ScrollInput positions are window-local logical coordinates; scroll deltas are logical content-offset changes. HoverEvent provides both node-local position and window_position. Gesture payloads document their own coordinate spaces. Platform adapters convert platform pixels, screen coordinates, key identity, and modifiers before dispatch. EventEmitter is appropriate for a reusable scoped component’s own output; it is not a process-wide event bus. Handler erasure and dispatch storage live in huxerui::detail and are not extension contracts.

Raw input and policy

ViewEvents::Pointer reports one complete Down/Move/Up-or-Cancel lifecycle without capturing or bubbling. PointerIntercept can take exclusive ownership by returning true; use a gesture modifier for ordinary recognition. Hover has independent enter/move/leave delivery, including disabled nodes, and does not join pointer ownership.

KeyIntercept visits the active focus-scope path before component defaults and stops at the first true result. KeyDown/KeyUp receive otherwise unhandled keys after component handling; return true only when consuming the operation. The Key enum includes letters, digits, function keys, keypad keys, and side-specific modifiers as well as navigation keys. Do not treat KeyEvent::text as a replacement for IME editing.

ScrollInput receives both wheel/trackpad axes before default nested scrolling; true consumes both axes, false keeps the default transaction. ContextMenuRequested receives a window-local Point suitable for MenuHandle::ShowAt. Use it rather than assuming a context menu always starts from a right mouse button.

Notification versus synchronous decision

Use Event<void(T)> when reporting a proposed value or completed action. Use a result-bearing Event only when the emitter must make an immediate decision from the handler’s return value. A result-bearing emission returns an optional result; “no connected handler” is distinct from a handler returning false.

An asynchronous check cannot be returned from a synchronous bool event. Consume or defer the original application action according to its contract, launch the work through TaskScope, and publish a later explicit state/action. Do not block the UI thread waiting for a worker callback to fill an event return slot.

Capture State and scoped EventEmitter handles by value. They are handles, not deep copies of application data. Payload references are borrowed for the callback; copy data if a later task needs it. For cross-language platform events, supply the key’s stable Name and use the platform bridge contract; ordinary component event identity is the C++ key type.

Interaction sequence identity

InteractionState is the current enabled/hovered/pressed/focused/focus-visible snapshot. InteractionEvent’s press_id pairs Press with its Release or Cancel; it distinguishes sequences, not selected state or a persistent pointer identifier. Cancel must end pressed feedback without triggering the normal activation action. Use Indication for these visuals rather than maintaining separate State booleans in every button.

Pointer capture and gesture recognition are different from observing raw input. Prefer the built-in Click path for an action and gesture modifiers for taps, drags, or transforms. This keeps disabled state, cancellation, keyboard activation, and semantics consistent.

Component operation boundaries

SliderEvents::Started(float), Changed(float), Committed(float) and Canceled() distinguish adjustment lifetime from value proposals. Cancel does not roll back owner State, and unmount need not emit a terminal event.

PagerEvents::Settled(std::size_t) observes the final displayed index after motion/rebound/layout, including programmatic changes and repeated indices, but not initial mount. SelectEvents::ExpandedChanged(bool) reports successful open/start-of-close, with close before selection Changed. These events share ordinary typed dispatch; fluent OnStarted/OnCommitted/OnCanceled, OnSettled and OnExpandedChanged are convenience methods.

See Slider, Pager, and Select for owner behavior.