Struct BuildContext 

pub struct BuildContext { /* private fields */ }

Framework-controlled build scope for declarative roots. It intentionally exposes no element IDs or scheduler handles. Signals use the runtime’s scoped collector while a builder executes; reads outside a build simply return the current value and create no dependency.

Implementations

impl BuildContext

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

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

Spawns Tokio work owned by this declarative owner. Its output must be Send; use Self::spawn_into to update UI-local state on completion.

pub fn spawn_in<F, T>(&self, scope: &TaskScope, future: F) -> Task<T>

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

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 owner-scoped Tokio work and handles the owned result on the UI thread. The callback may safely capture an Incular Signal.

pub fn dispatch(&self, callback: impl FnOnce(&mut Runtime) + Send + 'static)

Queues a Send callback for the UI owner without granting any Tokio worker mutable access to the widget/runtime tree.

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,

pub fn task_scope(&self) -> TaskScope

pub fn watch_focus_scope(&self, scope: &FocusScopeNode)

Makes the current retained builder depend on a focus scope.

A scope is an application-owned handle rather than a signal, so this explicit watch registers a weak, owner-lifetime subscription in the runtime’s ordinary reactive queue. The initial root build records the scope and installs the subscription once its element identity exists.

pub fn restoration_scope(&self) -> Option<RestorationScope>

Returns the stable restoration scope for this build when the owning application explicitly enabled restoration. Ordinary applications have no restoration scope and therefore no persistence side effects.

pub fn restoration(&self) -> Option<RestorationHandle>

Returns a callback-safe capability for reset, flush, and diagnostics when restoration is enabled. It contains no widget tree or native filesystem handle.

pub fn restorable<T>( &self, key: RestorationKey, default: T, ) -> Option<Restorable<T>>

where T: Clone + PartialEq + Serialize + DeserializeOwned + 'static,

Creates an opt-in reactive value under this build’s restoration scope. key must be stable across reordering and rebuilds; use a separate child scope for dynamic collections rather than an element position.

pub fn restored_signal<T>( &self, key: RestorationKey, default: T, ) -> Option<Restorable<T>>

where T: Clone + PartialEq + Serialize + DeserializeOwned + 'static,

Alias matching the common cx.restored_signal("count", 0) pattern. The returned Restorable wraps a normal reactive signal; write via its set/update methods so a mutation is captured for persistence.

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

Queues another retained root for native creation. Its state, focus, semantics, environment, compositor, and task scope are independent of this context’s window; shared Signals may still be captured by the supplied root and will subscribe each root independently.

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 the native window owning this build. Standalone/headless runtimes without an application window return None.

pub fn file_dialogs(&self) -> Option<FileDialogService>

Returns the native file-dialog service owned by the current window. Standalone/headless runtimes without an application window return None.

pub fn global_shortcuts(&self) -> Option<GlobalShortcutService>

Returns the application-scoped native global-shortcut service. Unlike focused Shortcuts, registrations remain active while the application is in the background and are identified independently of any window.

pub fn application_shell(&self) -> Option<ApplicationShellService>

Returns application-scoped tray/status, notification, and taskbar/Dock services. The service contains no native handles and is callback-safe.

pub fn tokio_handle(&self) -> TokioHandle

Returns the Tokio handle for advanced integrations. Tasks spawned directly through it are not owner-scoped; prefer Self::spawn or Self::spawn_into for UI work.

pub fn environment(&self) -> RuntimeEnvironment

Reads all environment fields. Prefer the typed accessors below when a build uses only one value, so unrelated changes do not rebuild it.

pub fn viewport(&self) -> Size

pub fn scale_factor(&self) -> f64

pub fn text_scale(&self) -> f32

pub fn safe_insets(&self) -> EdgeInsets

pub fn view_insets(&self) -> EdgeInsets

pub fn view_padding(&self) -> EdgeInsets

Persistent system-obstruction margin, independent of transient occlusion. Maintained SafeArea bottom edges read this alongside the safe margin.

pub fn safe_area(&self, safe_area: SafeArea) -> Widget

Resolves SafeArea from the authoritative logical insets while recording only the dependencies it reads: the safe margin always, plus the persistent view padding when the descriptor maintains its bottom edge. This applies the same policy as retained construction; transient occlusion never participates.

pub fn brightness(&self) -> Brightness

pub fn locales(&self) -> Vec<Locale>

pub fn resolve_locale(&self, supported: &[Locale]) -> Option<Locale>

Resolves a supported application locale while recording a locale-only dependency, so platform locale changes rebuild only consumers of it.

pub fn text_direction(&self) -> TextDirection

pub fn window_focused(&self) -> bool

pub fn reduced_motion(&self) -> bool

pub fn high_contrast(&self) -> bool

pub fn input_capabilities(&self) -> InputCapabilities

pub fn window_occluded(&self) -> bool