Struct Application 

pub struct Application { /* private fields */ }

Owns application services, one Tokio runtime, and multiple retained roots. A root’s environment, input/focus, semantics, compositor, frame work, and cancellation scope are window-local; assets, Signals, and Tokio are shared.

Implementations

impl Application

pub fn new( build: impl FnMut(&mut BuildContext) -> Widget + 'static, ) -> Result<Self, TreeError>

Creates an application from a retained root builder.

The builder runs during construction and may run again whenever state or environment values read by the builder change. Keep the builder free of external side effects such as network requests, file writes, or analytics; put those operations in event callbacks or tasks.

pub fn new_with_options( options: WindowOptions, build: impl FnMut(&mut BuildContext) -> Widget + 'static, ) -> Result<Self, WindowError>

Builds the initial retained root with portable native-window options.

pub fn new_with_restoration( options: WindowOptions, restoration: RestorationConfig, build: impl FnMut(&mut BuildContext) -> Widget + 'static, ) -> Result<Self, WindowError>

Creates an application whose explicitly selected values can survive a restart. Restoration loads synchronously before the initial root build; a corrupt, incompatible, or unmigratable snapshot is reported through diagnostics and simply exposes application defaults instead.

pub fn new_restorable( restoration_id: WindowRestorationId, kind: impl Into<String>, options: WindowOptions, restoration: RestorationConfig, build: impl FnMut(&mut BuildContext) -> Widget + 'static, ) -> Result<Self, WindowError>

Creates a restoration-enabled application whose primary native window also has a stable application identity. Use this instead of Self::new_with_restoration when its logical size/fullscreen state should be reconstructed across launches.

pub fn from_runtime( runtime: Runtime, on_action: impl FnMut(ActionId) + 'static, ) -> Self

Adopts an existing standalone runtime without remounting its tree or replacing its task scheduler. The action callback observes legacy action IDs on the UI thread; native event handling uses the application host. Existing reactive builders, focus and queued task completions are retained.

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

Adds an independent retained root. Native creation is deferred until a desktop adapter reaches an active Winit event-loop callback.

pub fn open_window_with( &mut self, options: WindowOptions, build: impl FnMut(&mut BuildContext) -> Widget + 'static, ) -> Result<WindowHandle, WindowError>

Adds an independent declarative root with its own window environment and cancellation scope.

pub fn open_restorable_window_with( &mut self, restoration_id: WindowRestorationId, kind: impl Into<String>, options: WindowOptions, build: impl FnMut(&mut BuildContext) -> Widget + 'static, ) -> Result<WindowHandle, WindowError>

Opens an auxiliary window with a stable restoration ID. A normal user close removes this descriptor and its window-scoped values from the next session; application shutdown preserves currently active restorable windows.

pub fn register_restorable_window_factory( &mut self, kind: impl Into<String>, options: WindowOptions, factory: impl Fn(&mut BuildContext) -> Widget + 'static, ) -> Result<(), WindowError>

Registers an in-memory factory for one stable auxiliary window kind. Builders remain ordinary closures and are never stored in a snapshot.

pub fn restore_restorable_windows(&mut self) -> Result<usize, WindowError>

Restores all persisted auxiliary windows whose stable factories have been registered. Call this after registration and before entering the native runner; it therefore cannot flash a default auxiliary UI before restore. Unknown kinds, unparseable ids, and duplicate descriptors are skipped safely and counted in diagnostics; only a genuine window-open failure aborts the remaining restores.

pub const fn primary_window(&self) -> WindowId

pub fn active_window_ids(&self) -> Vec<WindowId>

pub fn window_handle(&self, window_id: WindowId) -> Option<WindowHandle>

Returns a thread-safe command handle for one live Incular window.

pub fn platform_capabilities(&self) -> PlatformCapabilities

Returns the latest backend capability snapshot for application-level services. Before a native backend attaches, fields are Unknown.

pub fn activations(&self) -> ApplicationActivationService

Returns the application-scoped activation stream. Native open-file, deep-link, reopen, secondary-launch, and global-shortcut events all use this one ordered delivery path rather than a window input queue.

pub fn global_shortcuts(&self) -> GlobalShortcutService

Returns the application-scoped native global shortcut service.

pub fn application_shell(&self) -> ApplicationShellService

Returns the application-owned native shell service. Tray/status items, notifications, and taskbar/Dock state are independent of retained widget lifetime and may therefore be created before or after windows.

pub fn set_launch_activation(&mut self, activation: LaunchActivation)

Replaces the launch payload that the desktop runner publishes for this process. This is useful for custom launchers which already classified document or URL arguments and want to preserve those semantics.

pub fn set_single_instance_policy( &mut self, policy: Option<SingleInstancePolicy>, )

Enables or disables optional single-instance forwarding. Incular never enforces this policy unless the application explicitly supplies one.

pub fn single_instance_policy(&self) -> Option<&SingleInstancePolicy>

pub fn bridge_activation_routes( &self, provider: Rc<dyn RouteInformationProvider>, map: impl Fn(&str) -> Option<RouteInformation> + 'static, ) -> ActivationRouteBridge

Connects URL activations to an existing Router platform-route provider.

The application supplies URL-to-route interpretation. This keeps deep link parsing in the route layer and prevents desktop adapters from acquiring application navigation policy.

pub fn displays(&self) -> Vec<DisplaySnapshot>

pub fn display(&self, id: DisplayId) -> Option<DisplaySnapshot>

pub fn primary_display(&self) -> Option<DisplaySnapshot>

pub fn current_display(&self, window_id: WindowId) -> Option<DisplaySnapshot>

pub fn set_platform_capabilities(&mut self, capabilities: PlatformCapabilities)

Publishes one backend/session capability snapshot and applies it to all currently live windows. Custom embedders may call this before entering their native event loop.

pub fn window_capabilities( &self, window_id: WindowId, ) -> Option<PlatformCapabilities>

Returns the capability snapshot associated with one live window.

pub fn set_window_capabilities( &mut self, window_id: WindowId, capabilities: PlatformCapabilities, ) -> bool

Overrides capabilities for one live window when native support depends on that concrete surface/session rather than the application backend.

pub fn set_transient_presentations( &mut self, window_id: WindowId, presentations: Vec<TransientPresentationResolution>, ) -> bool

Publishes the native adapter’s resolved presentation for the visible semantic transients in one retained window. Custom embedders should replace the complete snapshot after each host-negotiation pass.

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

Publishes the desktop bounds a confirmed native transient may use for collision placement. Bounds are parent-view-local logical geometry.

pub fn devtools_windows(&self) -> Vec<WindowSummary>

Development-only, read-only view of application windows. Keeping this extraction here means platform runners never need to reach into the retained-window registry.

pub fn devtools_widget_tree( &self, window: DevWindowId, ) -> Result<Vec<TreeDelta>, ErrorCode>

Extracts one window’s retained widget tree for DevTools. The method performs no layout, paint, or allocation proportional to the entire application beyond the explicit bounded protocol snapshot.

pub fn devtools_node_details( &self, id: DevWidgetId, ) -> Result<NodeDetails, ErrorCode>

Returns curated details for a live DevTools element id, rejecting stale ids before touching the retained tree.

pub fn devtools_edit_property( &mut self, id: DevWidgetId, name: &str, value: &DebugValue, ) -> bool

Applies a supported temporary property override to one live retained node. Generational IDs make stale edits fail closed.

pub fn devtools_revert_property( &mut self, id: DevWidgetId, name: &str, original: &DebugValue, ) -> bool

Restores one overridden property and forgets the override, so a later application rebuild no longer re-applies it.

pub fn devtools_node_bounds(&self, id: DevWidgetId) -> Option<[f32; 4]>

Reads the exact world-space bounds for the selected-widget overlay.

pub fn devtools_node_overlay_geometry( &self, id: DevWidgetId, ) -> Option<DevOverlayGeometry>

Read-only retained geometry for selected-node debug adornments.

pub fn devtools_window_layout_bounds( &self, window: WindowId, limit: usize, ) -> Vec<[f32; 4]>

Bounded exact retained layout rectangles for one target window. The platform adapter consumes these in its compositor-only overlay pass; no widget, layout or semantics state changes as a consequence.

pub fn devtools_window_semantics_bounds( &self, window: WindowId, limit: usize, ) -> Vec<[f32; 4]>

pub fn devtools_window_hit_regions( &self, window: WindowId, limit: usize, ) -> Vec<[f32; 4]>

pub fn devtools_window_scroll_viewports( &self, window: WindowId, limit: usize, ) -> Vec<[f32; 4]>

pub fn devtools_window_layer_bounds( &self, window: WindowId, limit: usize, ) -> Vec<[f32; 4]>

pub fn devtools_window_phase_nodes( &self, window: WindowId, limit: usize, ) -> Vec<DevPhaseNode>

Bounded existing per-node work counters for target-side phase flashes.

pub fn devtools_begin_deep_trace( &mut self, window: WindowId, max_events: usize, ) -> bool

Enables one bounded per-node Deep trace for the next frame of this window. Normal/Performance profiler modes never call this, so the hot path has only compile-time-gated instrumentation checks.

pub fn devtools_take_deep_trace( &mut self, window: WindowId, frame: u64, ) -> Option<DeepFrameTrace>

Takes the completed per-node trace without cloning its event buffer.

pub fn devtools_subtree_layout_bounds( &self, id: DevWidgetId, limit: usize, ) -> Option<(WindowId, Vec<[f32; 4]>)>

Exact retained subtree bounds for the selected DevTools node, together with its owning native window. Stale IDs return no result.

pub fn devtools_hit_test( &self, window: WindowId, point: Offset, ) -> Option<(DevWidgetId, [f32; 4])>

Hit-tests a retained root for Select Widget mode without dispatching the pointer to application widgets.

pub fn devtools_resource_counts(&self) -> ResourceCounts

Framework-owned memory/resource inventory. This is deliberately a count of retained Incular objects, not a misleading attempt to inspect Rust’s allocator or another crate’s heap.

pub fn devtools_signals(&self) -> Vec<SignalSummary>

Returns only signals which explicitly opted into DevTools visibility. Values are already reduced to bounded summaries at write time.

pub fn devtools_signal_subscribers( &self, signal: DevSignalId, ) -> Vec<SignalSubscriber>

Resolves actual live reactive dependencies for a DevTools-visible signal. The registry stores only weak signal state and Element ids; this method resolves those ids against the matching live window tree, so unmounted elements are never retained or reported.

pub fn devtools_edit_signal( &self, signal: DevSignalId, value: &EditableValue, ) -> bool

Applies an explicitly opted-in typed DevTools edit on the UI thread. The conversion and the normal Signal::set invalidation both live in the signal registration; unsupported types are rejected.

pub fn contains_window(&self, window_id: WindowId) -> bool

pub fn transient_surfaces( &self, window_id: WindowId, ) -> Vec<TransientSurfaceSnapshot>

Visible transient surfaces belonging to window_id after its latest retained layout. Geometry is window-local logical space and therefore remains anchored when the native parent moves; the platform adapter is responsible only for mapping that geometry into desktop coordinates.

pub fn set_last_window_policy(&mut self, policy: LastWindowPolicy)

pub const fn last_window_policy(&self) -> LastWindowPolicy

pub fn on_close_request( &mut self, callback: impl FnMut(WindowId) -> bool + 'static, )

Installs the application policy used for a native close request. The callback returns true to accept closing and false to keep the window alive (for example, an unsaved-work dialog flow).

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

pub fn simulation(&self) -> Simulation

Returns a cloneable, in-process controller for the primary window. Simulation commands are serviced by the native event loop and never synthesize OS-level mouse or keyboard input.

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

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

Starts application-scoped Tokio work. It is not cancelled when any individual window closes.

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 dispatch(&self, callback: impl FnOnce(&mut Runtime) + Send + 'static)

Queues a UI callback for the primary window. For work targeting another root, capture that root’s BuildContext dispatcher instead.

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,

pub fn tokio_handle(&self) -> TokioHandle

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

Drains at most one bounded Tokio UI turn, routing each completion to the window scope that created it. Closed/reused IDs discard stale work.

pub fn process_runtime_work(&mut self)

pub fn handle_external_drag_event( &mut self, window_id: WindowId, event: ExternalDragEvent, ) -> ExternalDragResponse

Routes external platform transfer data to one retained window and returns the operation requested by the currently hit-tested target. Native adapters with richer drag protocols can feed this response back to the source; adapters such as Winit file-drop may simply ignore it.

pub fn handle_window_event(&mut self, event: WindowEvent)

Routes a normalized event to exactly one retained root.

pub fn handle_application_lifecycle(&mut self, lifecycle: PlatformLifecycle)

Applies one genuine application-level lifecycle transition to every retained window root. Window focus remains a separate per-window lifecycle channel and never synthesizes these application states.

pub fn record_platform_operation_error( &mut self, window_id: WindowId, error: PlatformOperationError, ) -> bool

Records a backend failure for a user-driven operation that does not have an explicit result consumer (for example a WindowDragRegion).

pub fn set_window_environment( &mut self, window_id: WindowId, environment: RuntimeEnvironment, ) -> bool

pub fn set_window_clipboard( &mut self, window_id: WindowId, clipboard: Box<dyn Clipboard>, )

Installs a platform clipboard for one window’s input/editing bridge. The clipboard service itself may be application-wide; the runtime keeps the mutable adapter at the window input boundary.

pub fn take_window_text_input_commands( &mut self, window_id: WindowId, ) -> Vec<TextInputCommand>

Drains text-input commands for one native window. The caller applies them on that window’s platform/UI thread.

pub fn frame_requested(&self, window_id: WindowId) -> bool

pub fn note_frame_requested(&mut self, window_id: WindowId)

pub fn note_runtime_wake(&mut self)

Records one UI-relevant runtime wake (async completion or message). Wakes that mutate no visible state must not produce redraws; the idle contract test relies on these counters staying independent.

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

pub fn sync_accessibility( &mut self, window_id: WindowId, projection: &mut AccessKitProjection, ) -> Option<NativeAccessibilityUpdate>

Projects this window’s retained semantics through its window-local AccessKit bridge. Native adapters call this on the UI/event-loop thread only after AccessKit activation; a changed semantic revision produces a full or incremental tree update while ordinary paint/compositor frames produce no work.

pub fn sync_semantics_projection( &mut self, window_id: WindowId, projection: &mut MobileAccessibilityProjection, ) -> Option<MobileAccessibilityUpdate>

Projects this window’s retained semantics into stable-ID node updates for hosts that present them without AccessKit, such as a browser page. Bounds stay in logical pixels.

pub fn dispatch_accessibility_action( &mut self, window_id: WindowId, request: SemanticActionRequest, ) -> bool

Receives an already validated native semantic request for exactly one window. It uses the ordinary retained runtime action dispatcher, so native callbacks never mutate widget/controller state directly.

pub fn set_semantics_enabled(&mut self, window_id: WindowId, enabled: bool)

Turns one window’s per-frame semantics pass on or off. Native hosts enable it when an assistive technology requests the tree; enabling schedules a frame so the first native update is complete.

pub fn set_accessibility_diagnostics( &mut self, window_id: WindowId, diagnostics: AccessibilityDiagnostics, )

Updates one window’s value-free bridge diagnostics after a lifecycle or action event that did not emit a tree update.

pub fn set_profiler_mode(&mut self, mode: ProfilerMode)

Selects how much profiling state is retained. Normal keeps only counters and the latest frame; higher modes retain bounded history.

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

Applies the DevTools animation speed to every live window. This is a retained animation-clock setting, not a scheduler or Tokio setting.

pub fn reassemble(&mut self)

Rebuilds every retained builder in every live window on the next frame. Element identity, focus, scroll offsets and signal values are kept; only widget descriptions and the callbacks they carry are replaced. Use this after application code was swapped underneath a running tree.

pub unsafe fn apply_hot_patch( &mut self, patch: HotPatch, ) -> Result<(), HotPatchError>

Loads a hot patch and reassembles every window. A patch that fails to load leaves the running code untouched.

Safety

The patch must have been built against the executable image of this exact process; see HotPatch::apply.

pub const fn profiler_mode(&self) -> ProfilerMode

pub fn set_refresh_rate_hz(&mut self, hz: Option<f32>)

Derives frame budgets from an actual refresh rate (Hz). None clears.

pub fn note_render_metrics( &mut self, window_id: WindowId, render: RenderFrameMetrics, gpu: Option<GpuSample>, )

Merges renderer-reported metrics into one window’s latest record and feeds the application profiler history with a complete frame sample.

pub const fn performance_hub(&self) -> &PerformanceHub

Shared handle to the observable performance snapshot. Overlay builders read PerformanceHub::version so only they rebuild on publish.

pub fn install_performance_overlay( &mut self, window_id: WindowId, ) -> Result<(), TreeError>

Installs the debug performance overlay into window_id.

The application tree must contain a widget keyed with PERFORMANCE_OVERLAY_KEY; that placeholder element is replaced by a repaint-contained overlay whose builder re-runs only when the hub publishes, so measured widget work is unaffected. Requires a profiler mode of ProfilerMode::Diagnostic or higher to observe data.

pub fn profiler_history(&self) -> &FrameHistory

pub fn performance_snapshot(&self) -> PerformanceSnapshot

Builds a complete read-only performance view. This allocates and is intended for diagnostics tooling, the debug overlay, and JSON export — never for the per-frame hot path.

pub const fn profiler_budget(&self) -> &BudgetStatistics

pub fn note_presented(&mut self, window_id: WindowId, presented: bool)

pub fn request_close(&mut self, window_id: WindowId) -> bool

pub fn close_window(&mut self, window_id: WindowId) -> bool

pub fn take_native_file_dialog_requests( &mut self, ) -> Vec<NativeFileDialogRequest>

Takes native file-dialog work ready to start. At most one request per parent window is active; later requests for that window remain FIFO in the runtime until completion or cancellation.

pub fn complete_file_dialog( &mut self, completion: NativeFileDialogCompletion, ) -> FileDialogCompletionStatus

Completes one active file dialog and promotes the next request for the same parent. Backends must invoke this only on the application UI/event loop thread; native dialog objects never cross this boundary.

pub fn complete_native_operation( &mut self, completion: NativeOperationCompletion, ) -> NativeOperationCompletionStatus

Completes one result-bearing native operation. Backends call this only after applying the operation on the owning native/UI thread.

pub fn take_native_window_commands(&mut self) -> Vec<NativeWindowCommand>

Takes all UI-thread native operations. Adapters must call this only from their event-loop callback; creation is consequently valid for Winit 0.30’s active-loop restriction.

pub const fn should_exit(&self) -> bool

pub fn window_diagnostics( &self, window_id: WindowId, ) -> Option<WindowDiagnostics>

pub fn diagnostics(&self) -> ApplicationDiagnostics

pub fn restoration_diagnostics(&self) -> Option<RestorationDiagnostics>

Returns value-free health and persistence-coalescing data when the application opted into restoration.

pub fn restoration_path(&self) -> Option<PathBuf>

Returns the configured snapshot path for developer tooling. In-memory and custom stores intentionally have no filesystem location.

pub fn reset_restoration(&mut self) -> bool

Removes every opt-in persisted value and every restorable-window descriptor. The deletion is coalesced through the normal Tokio-backed persistence pipeline; call Self::flush_restoration before an immediate process handoff if required.

pub fn flush_restoration(&mut self) -> bool

Bypasses the normal 250ms debounce but still writes on Tokio’s blocking pool. This is useful for an explicit user action or lifecycle flush.

pub fn debug_dump(&self) -> String

pub fn shutdown(&mut self)

pub fn into_runtime(self) -> Runtime

Compatibility escape hatch for existing single-window embedders and tests. Extra windows are cancelled; desktop run retains all windows. Pending restoration state is flushed with the same bounded wait as shutdown so the extracted runtime does not silently drop it.

impl Application

pub fn devtools_runtime_diagnostics( &self, window: DevWindowId, ) -> Result<RuntimeDiagnosticsWire, ErrorCode>

Cumulative widget, text, semantics and compositor counters for one window.

pub fn devtools_semantics_tree( &self, window: DevWindowId, ) -> Result<(Vec<SemanticsNodeWire>, bool), ErrorCode>

Bounded semantics tree snapshot; the flag reports truncation.

pub fn devtools_layer_tree( &self, window: DevWindowId, ) -> Result<(Vec<LayerNodeWire>, bool), ErrorCode>

Bounded compositor layer snapshot; the flag reports truncation.

pub fn devtools_work_counts( &self, window: DevWindowId, limit: usize, ) -> Result<Vec<WorkCountEntry>, ErrorCode>

Per-element work counters ranked by build count, at most limit (itself capped at 200).

impl Application

pub fn process_simulation_requests(&mut self)

Services queued in-process simulation requests on the application UI thread. Native adapters call this from their event-loop wake path.

pub fn simulation_capture_pending(&self, window_id: WindowId) -> bool

pub fn take_gpu_resource_queries(&mut self) -> Vec<WindowId>

Returns the live windows with pending GPU-resource queries so the native adapter can fulfill them from current state without presenting. Live waiters stay queued until Self::complete_gpu_resource_query drains them; waiters for windows that no longer exist fail immediately instead of hanging the querier. Window close and application shutdown settle pending waiters through the shared close/shutdown cleanup, never through this method.

pub fn complete_gpu_resource_query( &mut self, window_id: WindowId, summary: GpuResourceSummary, )

Completes pending GPU-resource waiters after the native adapter has snapshotted current residency. Never renders.

pub fn simulation_frame_pending(&self, window_id: WindowId) -> bool

Reports whether a simulator is waiting for the next presented frame.

pub fn complete_simulation_frame( &mut self, window_id: WindowId, presented: bool, capture: Option<Result<Screenshot, String>>, )

Completes simulator waiters after the native renderer has presented a frame. capture is supplied only when a renderer serviced a pending capture request.

pub fn fail_simulation_frame( &mut self, window_id: WindowId, message: impl Into<String>, )

Fails simulator requests when a native frame cannot be produced.

Trait Implementations

impl Drop for Application

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.