Controls, Input, and Focus
Use semantic controls for activation and keep server targeting connected to the accepted client tree.
An ordinary control needs more than a callback for one device event. It must account for activation, cancellation, pressed state, focus, and inherited configuration throughout the interaction. Hera Kit's built-in controls combine those responsibilities so applications can express the action they need without reimplementing the event lifecycle.
Semantic Controls
Choose a control according to the data it edits. A button(label, action) presents a view label and invokes a synchronous action with InputContext, while a toggle(label, binding) directly edits a Binding<bool>. For text editing, text_field(binding) works with an EditBuffer and retains the focus, caret, selection, and viewport state needed by the field.
The controls inherit appearance through ControlStyleKey and disabled behavior through .disabled(true), allowing a subtree to share those settings. Their activation also accounts for keyboard input and cancellation, which would be lost if an application replaced the control with only a raw pointer-up callback.
Accepted Callback Dispatch
The toolkit keeps callbacks with its accepted tree. A candidate's new callbacks become active after its scene is accepted; a rejected replacement leaves the previous accepted handlers in place.
The accepted callback also retains the environment scope in which it was published. Bindings captured by that callback still access live model state, whereas captured ordinary values remain snapshots from its evaluation. This lets accepted interactions keep consistent providers while continuing to edit the current model.
Coordinate Provenance
Event dispatch must also preserve the geometry behind the server's target selection. When target-local coordinates are available, they are associated with a retained commit, which Kit checks against its confirmed scene before using them. A custom host needs the same ordering and provenance checks to avoid applying an event to unrelated candidate geometry.
A view's local coordinates should not be guessed from a newer layout when the display still shows an older accepted frame.
Focus Responsibilities
Keyboard input involves two focus decisions: the server chooses the owning surface, and the toolkit chooses a control within that surface. A surface losing focus can require local cancellation or interaction updates, but its view model remains alive for later use.
FocusTarget is available for advanced integration. Built-in controls already retain the focus storage they need; application code should not duplicate that state merely to use a text field.
Read button, text_field, and input internals for details.
Source Reference
The following files in the Hera checkout define the behavior described on this page.
crates/kit/src/view/controls.rscrates/kit/src/input/activation.rscrates/kit/src/input/focus.rscrates/kit/src/input/lineage.rs