Struct Runtime 

pub struct Runtime { /* private fields */ }

Retained application execution, input dispatch and frame coordination.

Implementations

impl Runtime

pub fn new(root: Widget) -> Result<Self, TreeError>

pub fn id(&self) -> u64

Stable identity of this runtime’s driver domain, for outlet ownership diagnostics: pairs with the outlet id to name both sides of a driver conflict.

pub fn spawner(&self) -> RuntimeSpawner

Starts work owned by this retained root. Component code should prefer the build context’s spawn API so completion lifetime follows its owner.

pub fn dispatcher(&self) -> UiDispatcher

Sends a Send callback from any worker thread to the UI owner. The callback is never run concurrently with retained-tree mutation.

pub fn tokio_handle(&self) -> TokioHandle

Returns the application’s Tokio handle for advanced libraries. Direct Tokio tasks have Tokio/application lifetime and are not component-owned.

pub fn set_wake_handler(&mut self, wake: Arc<dyn RuntimeWake>)

pub const fn window_id(&self) -> Option<WindowId>

Returns the owning normalized window when this runtime is managed by a multi-window application. Standalone runtimes remain windowless.

pub fn request_frame(&mut self)

Marks only this retained root for a future presentation.

pub fn take_text_input_commands(&mut self) -> Vec<TextInputCommand>

Drains native text-input commands produced since the last platform event-loop turn. A desktop runner applies these to Winit; mobile hosts can translate the same data to their platform text services.

pub fn open_window( &mut self, options: WindowOptions, root: Widget, ) -> Result<WindowHandle, WindowError>

Opens a second retained root through the owning application. This can be called from a build or a UI completion; native creation is queued for the desktop event-loop callback.

pub fn window_opener(&self) -> Option<WindowOpener>

Returns a retained UI capability that callbacks may use to open a window after this build has returned.

pub fn window_handle(&self) -> Option<WindowHandle>

Returns a command handle for this retained root’s owning native window.

pub fn window_task_scope(&self) -> TaskScope

Returns the scope cancelled as soon as this window closes. Child component scopes inherit from it automatically.

pub fn spawn_blocking<T>( &self, work: impl FnOnce() -> T + Send + 'static, complete: impl FnOnce(Result<T, TaskFailure>, &mut Runtime) + 'static, ) -> TaskHandle

where T: Send + 'static,

Starts bounded blocking work. Its completion callback runs later on the UI thread, so it may safely update a local Signal or schedule a build.

pub fn spawn<F, T>(&self, future: F) -> Task<T>

where F: Future<Output = T> + Send + 'static, T: Send + 'static,

Starts Tokio work cancelled with this window. Use a BuildContext for work whose completion must be tied to a mounted declarative owner.

pub fn spawn_into<F, T>( &self, future: F, complete: impl FnOnce(Result<T, TaskFailure>, &mut Runtime) + 'static, ) -> TaskHandle

where F: Future<Output = T> + Send + 'static, T: Send + 'static,

Starts window-scoped Tokio work with a UI-thread completion.

pub fn process_runtime_work_at(&mut self, _now: Instant)

Processes a bounded batch of UI-relevant Tokio completion messages and dispatch callbacks. Native runners call this only from their user-event path; it never polls Tokio or implies a redraw.

pub fn process_runtime_work(&mut self)

pub fn runtime_diagnostics(&self) -> RuntimeDiagnostics

pub fn debug_dump(&self) -> String

Compact ownership-facing state for framework diagnostics. Tokio’s own tracing ecosystem remains the source of executor-level telemetry.

pub fn environment(&self) -> RuntimeEnvironment

pub const fn lifecycle(&self) -> ApplicationLifecycle

pub const fn environment_generation(&self) -> u64

pub fn set_environment(&mut self, environment: RuntimeEnvironment) -> bool

Replaces normalized runtime values from a platform event. Rebuild is requested only when the declarative root read a changed value.

pub fn transition_lifecycle(&mut self, lifecycle: ApplicationLifecycle) -> bool

pub fn observe_lifecycle( &mut self, observer: impl Fn(LifecycleTransition) + 'static, )

pub fn observe_runtime_error( &mut self, observer: impl Fn(RuntimeErrorReport) + 'static, )

pub fn shutdown(&mut self)

Cancels runtime-owned work and prevents later queued callbacks from touching retained state. Native runners should call this before their renderer/window teardown.

pub fn tree(&self) -> &WidgetTree

pub fn tree_mut(&mut self) -> &mut WidgetTree

pub fn content_sensitivity(&self) -> ContentSensitivity

Returns the effective capture-protection policy contributed by the mounted retained tree. The window/application boundary is responsible for forwarding changes to its native adapter.

pub fn transient_surfaces(&self) -> Vec<TransientSurfaceSnapshot>

Visible transient portals after the latest layout. Desktop adapters use this retained snapshot to bind popup presentation to the owning window without coupling controls to a native event loop.

pub fn set_native_transient_bounds(&mut self, bounds: Option<Rect>) -> bool

Updates the parent-local logical rectangle that confirmed native transient hosts may use for collision placement.

pub fn set_native_transient_presentations( &mut self, ids: impl IntoIterator<Item = TransientSurfaceId>, ) -> bool

Updates the set of retained transients whose native hosts have completed negotiation. A presentation change requests a frame so placement, semantics, hit testing, and rendering switch coordinate spaces together.

pub fn dismiss_transients(&mut self, reason: TransientDismissReason) -> bool

Applies a framework-level transient dismissal cause without changing native focus ownership. Controllers receive the callback and the normal retained rebuild path removes their popup subtree.

pub fn set_animation_time_scale(&mut self, scale: f32)

Sets the animation-only time scale for this retained root. Runtime messages, Tokio tasks and profiler wall-clock measurements remain on the platform monotonic clock.

pub fn focused_element(&self) -> Option<ElementId>

pub fn dispatch_semantic_action( &mut self, node: SemanticNodeId, action: SemanticAction, ) -> bool

Dispatches an owned semantic action through the same control state used by pointer and keyboard input. Native adapters queue these requests; they never borrow mutable element storage. Eligibility reuses the existing owners: explicit semantic callbacks always execute; built-in Activate additionally requires the advertisement predicate (enabled button with a bound callback), matching the pointer and keyboard paths, which never see a disabled button past their own enabled gate. SetText requires an editable field while SetSelection requires only a controller — selection stays available in read-only and disabled fields on every input path. Focus accepts only targets the tree’s own focusability owner admits (can_request_focus: enabled controls, selectable text, or a focus node, unobstructed by exclude_focus or a hidden IndexedStack slot), with an already-focused valid target still reporting success; set_focus remains the single focus owner for all paths.

pub fn focus_diagnostics(&self) -> FocusDiagnostics

pub const fn editing_diagnostics(&self) -> EditingDiagnostics

pub fn set_clipboard(&mut self, clipboard: Box<dyn Clipboard>)

pub fn clipboard_capabilities(&self) -> ClipboardCapabilities

Returns the capabilities of the clipboard backend currently installed for this retained window.

pub fn read_clipboard( &mut self, request: TransferReadRequest, ) -> Result<DataTransfer, ClipboardError>

Reads rich clipboard data without collapsing it to plain text.

pub fn write_clipboard( &mut self, transfer: DataTransfer, ) -> Result<ClipboardWriteReport, ClipboardError>

Writes one rich clipboard transfer. The report distinguishes formats written atomically by the backend from representations it skipped.

pub fn set_clipboard_text(&mut self, text: impl Into<String>)

pub fn handle_external_drag( &mut self, event: ExternalDragEvent, ) -> ExternalDragResponse

Routes platform-owned transfer data through external drop targets. This path is intentionally independent of the local typed gesture arena.

pub fn handle_platform_event( &mut self, event: PlatformEvent, ) -> Option<EventTarget>

Processes a normalized platform event without exposing native window or event-loop types to the runtime API.

pub fn update_window_metrics(&mut self, metrics: WindowMetrics) -> bool

Applies the authoritative logical/physical conversion supplied by the platform metrics owner. Existing environment values such as locale are preserved while size and scale change together.

pub fn register_builder( &mut self, id: ElementId, builder: impl FnMut() -> Widget + 'static, ) -> Result<(), TreeError>

pub fn schedule_update( &mut self, id: ElementId, widget: Widget, ) -> Result<(), TreeError>

pub fn frame_requested(&self) -> bool

pub fn handle_input(&mut self, event: InputEvent) -> Option<EventTarget>

pub fn set_diagnostic_trigger(&self, trigger: impl Into<String>)

Associates subsequent frame work with a higher-level command such as a semantic simulation click. The trigger survives the input callback so deferred build/layout failures retain their original cause.

pub fn effective_mouse_cursor(&self) -> MouseCursor

Cursor selected by the current retained hover route. Defer is resolved to the ordinary platform cursor before crossing the native boundary.

pub fn handle_text_input_action(&mut self, action: TextInputAction) -> bool

Handles the action chosen by a native software keyboard. Desktop Winit backends reach the same code path through Enter, while mobile hosts can preserve the IME’s explicit Done/Next/Search intent.

pub fn run_frame( &mut self, constraints: Constraints, ) -> Result<(DisplayList, FrameStats), TreeError>

pub fn run_frame_at( &mut self, constraints: Constraints, now: Instant, ) -> Result<(DisplayList, FrameStats), TreeError>

Deterministic frame entry point used by animation tests and embedders with an existing monotonic clock.

pub fn diagnostics(&self) -> Diagnostics