Struct AppShell 

pub struct AppShell<R>
where
    R: Renderer,
{ /* private fields */ }

The application: one runtime, one composition, and a surface per window it shows.

Methods that name no root act on the primary surface, so a platform with one window uses the shell as it always has. A platform showing more windows reaches the others through AppShell::surface, after giving each window root a renderer with AppShell::add_window_surface.

Implementations

impl<R> AppShell<R>

where R: Renderer, R::Error: Debug,

pub fn debug_info_report(&mut self) -> String

pub fn log_debug_info(&mut self) -> String

pub fn layout_tree(&mut self) -> Option<&LayoutTree>

Get the current layout tree (for robot/testing)

pub fn semantics_active(&self) -> bool

Whether a semantics snapshot could contain anything at all. Reading the flag costs nothing, unlike collecting the layout-bounds map only to find semantics tracking disabled.

pub fn semantics_snapshot_revision(&mut self) -> u64

Monotonic revision of the accessibility-relevant state. It moves when a layout pass invalidated the cached snapshots, when semantics tracking is toggled, and when any node marked its semantics dirty since the last look. A bridge that stored the revision it last projected can skip the whole snapshot-and-compare while this still reads the same — which on an animation-only frame is every frame.

pub fn semantics_tree(&mut self) -> Option<&SemanticsTree>

Get the current semantics tree (for robot/testing)

pub fn root_layout_size(&mut self) -> Option<(f32, f32)>

pub fn node_layout_bounds( &mut self, target: NodeId, ) -> Option<(f32, f32, f32, f32)>

impl<R> AppShell<R>

where R: Renderer, R::Error: Debug,

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

pub fn set_frame_rate_preference(&mut self, preference: FrameRatePreference)

Sets how the platform should vote the display’s frame rate for this app. The default, FrameRatePreference::Auto, mirrors Compose: the panel’s fastest rate while frames are being produced, no preference when the scene is still.

pub fn frame_rate_preference(&self) -> FrameRatePreference

The app’s current display frame-rate preference. Read by platform backends each frame; the vote itself is applied by the backend that owns the native window.

impl<R> AppShell<R>

where R: Renderer, R::Error: Debug,

pub fn set_modifiers(&mut self, modifiers: Modifiers)

Sets the keyboard modifiers held right now, so the platform’s live modifier state (winit’s ModifiersChanged, a DOM event’s shiftKey/ctrlKey/altKey/metaKey) reaches every PointerEvent the shell dispatches from here on – the same state the wheel path already carries via WheelScroll::with_modifiers. A platform that never calls this leaves pointer events reporting None (see PointerEvent::modifiers) rather than a silently wrong “nothing held”.

pub fn modifiers(&self) -> Option<Modifiers>

The keyboard modifiers most recently set via set_modifiers, or None if the platform has never reported them.

pub fn rotary_scroll_factor(&self) -> f32

Pixels per rotary detent used by rotary_scrolled_by_detents.

pub fn set_rotary_scroll_factor(&mut self, factor: f32)

Sets the pixels-per-detent factor for rotary input.

On Wear OS this must be ViewConfiguration.getScaledVerticalScrollFactor() for pixel-exact parity with Compose. The host activity can read it over JNI once at startup and push it here; when it does not, the shell falls back to DEFAULT_ROTARY_SCROLL_FACTOR_DP scaled by display density.

Non-finite or non-positive values are ignored.

pub fn notify_app_paused(&mut self)

Notifies the framework that the host app was paused/backgrounded.

Withdraws any outstanding soft-keyboard request (and hides the keyboard) so the “keyboard shown” state does not survive across the pause and get restored on resume with no focused field. Platform runtimes call this from their pause lifecycle event.

pub fn notify_app_resumed(&mut self) -> bool

Notifies the framework that the host app resumed/foregrounded.

Never auto-shows the soft keyboard, even for a still-focused field: a warm resume keeps the caret but must not resurrect the keyboard (the user taps the field to bring it back). Always returns false so the platform runtime force-hides the OS-restored keyboard. Platform runtimes call this from their resume lifecycle event.

pub fn set_primary_selection(&mut self, text: &str)

pub fn get_primary_selection(&mut self) -> Option<String>

pub fn sync_selection_to_primary(&mut self)

Syncs the current text field selection to PRIMARY (Linux X11). Call this when selection changes in a text field.

pub fn set_pointer_source(&mut self, source: PointerSource)

Primary-surface form of SurfaceMut::set_pointer_source.

pub fn pointer_source(&self) -> PointerSource

Primary-surface form of SurfaceMut::pointer_source.

pub fn set_cursor(&mut self, x: f32, y: f32) -> bool

Primary-surface form of SurfaceMut::set_cursor.

pub fn set_cursor_at_time( &mut self, x: f32, y: f32, time_ms: Option<i64>, ) -> bool

Primary-surface form of SurfaceMut::set_cursor_at_time.

pub fn set_cursor_at_event_time( &mut self, x: f32, y: f32, event_time: PointerEventTime, ) -> bool

Primary-surface form of SurfaceMut::set_cursor_at_event_time.

pub fn pointer_pressed(&mut self) -> bool

Primary-surface form of SurfaceMut::pointer_pressed.

pub fn pointer_pressed_at_time(&mut self, time_ms: Option<i64>) -> bool

Primary-surface form of SurfaceMut::pointer_pressed_at_time.

pub fn pointer_pressed_at_event_time( &mut self, event_time: PointerEventTime, ) -> bool

Primary-surface form of SurfaceMut::pointer_pressed_at_event_time.

pub fn pointer_released(&mut self) -> bool

Primary-surface form of SurfaceMut::pointer_released.

pub fn pointer_released_at_position(&mut self, x: f32, y: f32) -> bool

Primary-surface form of SurfaceMut::pointer_released_at_position.

pub fn pointer_released_at_position_time( &mut self, x: f32, y: f32, time_ms: Option<i64>, ) -> bool

Primary-surface form of SurfaceMut::pointer_released_at_position_time.

pub fn pointer_released_at_position_event_time( &mut self, x: f32, y: f32, event_time: PointerEventTime, ) -> bool

Primary-surface form of SurfaceMut::pointer_released_at_position_event_time.

pub fn pointer_released_at_time(&mut self, time_ms: Option<i64>) -> bool

Primary-surface form of SurfaceMut::pointer_released_at_time.

pub fn pointer_released_at_event_time( &mut self, event_time: PointerEventTime, ) -> bool

Primary-surface form of SurfaceMut::pointer_released_at_event_time.

pub fn secondary_pointer_pressed( &mut self, pointer_id: u64, x: f32, y: f32, time_ms: Option<i64>, ) -> bool

Primary-surface form of SurfaceMut::secondary_pointer_pressed.

pub fn secondary_pointer_moved( &mut self, pointer_id: u64, x: f32, y: f32, time_ms: Option<i64>, ) -> bool

Primary-surface form of SurfaceMut::secondary_pointer_moved.

pub fn secondary_pointer_released( &mut self, pointer_id: u64, x: f32, y: f32, time_ms: Option<i64>, ) -> bool

Primary-surface form of SurfaceMut::secondary_pointer_released.

pub fn pointer_zoomed(&mut self, zoom_factor: f32) -> bool

Primary-surface form of SurfaceMut::pointer_zoomed.

pub fn wheel_scrolled(&mut self, wheel: WheelScroll) -> bool

Primary-surface form of SurfaceMut::wheel_scrolled.

pub fn pointer_scrolled(&mut self, delta_x: f32, delta_y: f32) -> bool

Primary-surface form of SurfaceMut::pointer_scrolled.

pub fn set_on_rotary_scroll<F>(&mut self, handler: F)

where F: Fn(RotaryScrollEvent) -> bool + 'static,

Primary-surface form of SurfaceMut::set_on_rotary_scroll.

pub fn clear_on_rotary_scroll(&mut self)

Primary-surface form of SurfaceMut::clear_on_rotary_scroll.

pub fn rotary_scrolled_by_detents( &mut self, detents: f32, uptime_millis: u64, ) -> bool

Primary-surface form of SurfaceMut::rotary_scrolled_by_detents.

pub fn rotary_scrolled(&mut self, event: RotaryScrollEvent) -> bool

Primary-surface form of SurfaceMut::rotary_scrolled.

pub fn cancel_gesture(&mut self)

Primary-surface form of SurfaceMut::cancel_gesture.

pub fn cancel_gesture_unless_pressed(&mut self)

Primary-surface form of SurfaceMut::cancel_gesture_unless_pressed.

pub fn refresh_pointer_icon(&self)

Offers the primary window’s current pointer icon to the platform again, for the moments a windowing system has drawn its own default over it.

pub fn take_pointer_icon_change(&self) -> Option<PointerIcon>

The pointer icon the platform has not applied to the primary window yet, or None when the icon has not changed since the last call.

Platform backends call this after handing the shell a batch of input and set the returned icon on the window they own. Platforms with no pointing device never call it.

pub fn set_platform_text_input( &mut self, handler: Rc<dyn PlatformTextInputHandler>, )

Installs the platform soft-keyboard handler for the primary window.

The handler is invoked when a text field gains focus (show_keyboard) or when text-field focus is cleared or goes stale (hide_keyboard). Platform runtimes with an on-screen keyboard (Android, iOS) call this once after creating the shell.

pub fn dismiss_top_modal(&mut self) -> bool

Primary-surface form of SurfaceMut::dismiss_top_modal.

pub fn move_focus_in_context(&mut self, direction: FocusDirection) -> bool

Primary-surface form of SurfaceMut::move_focus_in_context.

pub fn on_key_event(&mut self, event: &KeyEvent) -> bool

Primary-surface form of SurfaceMut::on_key_event.

pub fn on_paste(&mut self, text: &str) -> bool

Primary-surface form of SurfaceMut::on_paste.

pub fn on_copy(&mut self) -> Option<String>

Primary-surface form of SurfaceMut::on_copy.

pub fn on_cut(&mut self) -> Option<String>

Primary-surface form of SurfaceMut::on_cut.

pub fn on_ime_preedit( &mut self, text: &str, cursor: Option<(usize, usize)>, ) -> bool

Primary-surface form of SurfaceMut::on_ime_preedit.

pub fn on_ime_finish_composing(&mut self) -> bool

Primary-surface form of SurfaceMut::on_ime_finish_composing.

pub fn on_ime_set_composing_region( &mut self, start_bytes: usize, end_bytes: usize, ) -> bool

Primary-surface form of SurfaceMut::on_ime_set_composing_region.

pub fn on_ime_set_selection( &mut self, start_bytes: usize, end_bytes: usize, ) -> bool

Primary-surface form of SurfaceMut::on_ime_set_selection.

pub fn ime_editor_state(&mut self) -> Option<ImeEditorState>

Primary-surface form of SurfaceMut::ime_editor_state.

pub fn ime_caret_geometry(&mut self) -> Option<ImeCaretGeometry>

Primary-surface form of SurfaceMut::ime_caret_geometry.

pub fn clear_text_field_focus(&mut self)

Primary-surface form of SurfaceMut::clear_text_field_focus.

pub fn on_ime_delete_surrounding( &mut self, before_bytes: usize, after_bytes: usize, ) -> bool

Primary-surface form of SurfaceMut::on_ime_delete_surrounding.

impl<R> AppShell<R>

where R: Renderer, R::Error: Debug,

pub fn new(renderer: R, root_key: Key, content: impl FnMut() + 'static) -> Self

pub fn new_with_size( renderer: R, root_key: Key, content: impl FnMut() + 'static, buffer_size: (u32, u32), viewport: (f32, f32), ) -> Self

pub fn new_with_size_and_density( renderer: R, root_key: Key, content: impl FnMut() + 'static, buffer_size: (u32, u32), viewport: (f32, f32), density: f32, ) -> Self

pub fn app_context(&self) -> &Rc<AppContext>

The shell’s AppContext. Platform backends use it to register per-context services (such as the OS clipboard) that need UIKit/JNI access the shell itself does not have: enter the context and call the relevant set_platform_* installer.

pub fn surface(&mut self, root: RootId) -> Option<SurfaceMut<'_, R>>

The surface drawing root, or None when no surface was added for it. The primary surface always exists.

pub fn primary(&mut self) -> SurfaceMut<'_, R>

The surface drawing the composition root.

pub fn root_holding_the_press(&mut self) -> Option<RootId>

The root whose surface now draws the node that took the primary press, or None while no press is being held.

A press is taken by a node, not by a rectangle. When the application moves that node into a window of its own — a tab pulled out of a strip, a pane pulled off a stack — the press belongs to that window from then on, and a platform can hand it over on the strength of this rather than on where the pointer happens to be.

pub fn add_window_surface( &mut self, window: u64, renderer: R, buffer_size: (u32, u32), viewport: (f32, f32), ) -> Option<R>

Gives the window root registered under window a surface of its own, drawn by renderer into a framebuffer of buffer_size physical pixels and viewport logical pixels. The surface follows the window root node while it stays in the tree, and draws nothing while it is out. Returns the renderer of the surface this one replaces, if the window already had one.

The renderer joins an app whose services the primary renderer already installed; nothing is attached to the app context again.

pub fn remove_window_surface(&mut self, window: u64) -> Option<R>

Takes the surface of window away, handing back its renderer.

pub fn surface_ids(&self) -> Vec<RootId>

Every surface’s root, the primary first.

pub fn window_roots(&self) -> Vec<WindowRootEntry>

The window roots attached in the composition right now. A platform reads this after an update to open a window for each new entry and close the windows whose entries left.

pub fn window_roots_revision(&self) -> u64

Changes whenever a window root attaches, detaches or is updated; a platform that stored the last value it acted on skips Self::window_roots while it reads the same.

pub fn primary_has_content(&mut self) -> bool

Whether the primary root lays out anything of its own: a node with area outside every window root. A platform hides the primary window while this is false, because every visible node is then in a window of its own.

pub fn primary_content_size(&mut self) -> Option<Size>

The extent of what the primary root lays out: the far right and bottom edges of its nodes with area, measured from the root’s origin and leaving out every window root’s subtree. None while it lays out nothing. A platform whose primary window wraps its content sizes the window to this after every update.

pub fn set_active_root(&mut self, root: RootId)

Names the surface the platform considers focused, which is where the soft keyboard belongs. Pointer presses activate their surface on their own; a platform calls this for focus it grants otherwise.

pub fn active_root(&self) -> RootId

The surface the platform considers focused.

pub fn set_dev_options(&mut self, options: DevOptions)

Set development options for debugging and performance monitoring.

The FPS counter and other overlays are rendered directly by the renderer (not via composition) to avoid affecting performance measurements.

pub fn dev_options(&self) -> &DevOptions

Get a reference to the current dev options.

pub fn frame_pacing_mode(&self) -> FramePacingMode

pub fn current_fps(&self) -> f32

pub fn fps_stats(&self) -> FpsStats

pub fn reset_fps_stats(&mut self)

pub fn record_presented_frame( &mut self, frame_started_at: Instant, frame_finished_at: Instant, )

pub fn set_frame_pacing_mode(&mut self, mode: FramePacingMode)

pub fn dev_overlay_control_center( &self, mode: FramePacingMode, ) -> Option<(f32, f32)>

Where the dev overlay draws the control for mode, in logical pixels.

The overlay is drawn by the renderer rather than composed, so it has no semantics for a test to search. Without this a test that wants to press a pacing control has to hard-code a coordinate and silently starts passing against empty space the moment the overlay’s text changes.

pub fn set_viewport(&mut self, width: f32, height: f32)

Sets the primary surface’s viewport and lays out and renders at once.

pub fn viewport_size(&self) -> (f32, f32)

pub fn set_screen_origin(&mut self, origin: Option<Point>)

Tells the shell where the primary window sits on the screen. See SurfaceMut::set_screen_origin.

pub fn set_buffer_size(&mut self, width: u32, height: u32)

pub fn buffer_size(&self) -> (u32, u32)

pub fn scene(&self) -> &R::Scene

pub fn renderer(&mut self) -> &mut R

pub fn set_frame_waker(&mut self, waker: impl Fn() + Send + Sync + 'static)

pub fn clear_frame_waker(&mut self)

pub fn should_render(&self) -> bool

pub fn needs_update(&self) -> bool

pub fn has_pending_ui(&self) -> bool

Returns true when the runtime holds work for the UI thread: posted tasks, continuations from worker threads, or async tasks ready to poll.

This is the part of needs_update that another thread is waiting on, told apart from the part that only wants the screen redrawn. A platform backend running with no surface uses it to compose for work and stay asleep for animation.

pub fn needs_redraw(&self) -> bool

Returns true if the primary surface owes the display a frame: stale pixels, or a renderer that has not warmed its swapchain yet.

An app that merely holds an open next_frame() await - a game loop, a polling effect - keeps Self::needs_update true forever without changing a single pixel. Such an app must still be ticked every frame, but the frame it produces is byte-identical to the last one, and presenting it costs a full swapchain rotation and pins the panel at its maximum refresh rate. Callers pair this with FrameUpdateResult::visual_changed from the update they just ran, which reports the work that update actually did. Note: Cursor blink is now timer-based and uses WaitUntil scheduling, not continuous redraw.

pub fn mark_dirty(&mut self)

Marks the primary surface as dirty, indicating a redraw is needed.

pub fn request_root_render(&mut self)

pub fn set_density(&mut self, density: f32)

pub fn set_font_scale(&mut self, font_scale: f32)

Reports the system font scale the platform is showing text at.

Hosts call this at startup and on every configuration change. Sizes in Sp follow it, sizes in Dp do not, which is what lets an app grow its text with the user’s setting while its layout stays where it was.

This takes the setting as a plain multiplier. A host whose platform converts Sp through a table of its own — Android 14 and up does — calls AppShell::set_font_scale_curve with what the platform answered instead, because the multiplication is not what that platform does.

pub fn set_font_scale_curve(&mut self, curve: FontScaleCurve)

Reports the system font scale together with the conversion behind it.

See cranpose_ui::font_scale: above a threshold setting Android resolves a size in Sp through a piecewise-linear table rather than by multiplying, so a host that can read that table hands it over here and every Sp in the app resolves the way the platform’s own text does.

pub fn has_active_animations(&self) -> bool

Returns true if there are active animations or pending recompositions.

pub fn has_transient_frame_callbacks(&self) -> bool

pub fn has_active_pointer_gesture(&self) -> bool

pub fn frame_owed(&self) -> bool

Primary-surface form of SurfaceMut::frame_owed.

pub fn take_frame_owed(&mut self) -> bool

Primary-surface form of SurfaceMut::take_frame_owed.

pub fn next_event_time(&self) -> Option<Instant>

Returns the next scheduled event time for cursor blink. Use this for ControlFlow::WaitUntil scheduling.

pub fn frame_schedule(&self) -> FrameSchedule

pub fn schedule_platform_frame<D>(&self, driver: &D) -> FrameSchedule

where D: PlatformFrameDriver + ?Sized,

pub fn frame_scheduler_snapshot(&self) -> FrameSchedule

pub fn realtime_pointer_event_time( &self, platform_time_ms: Option<i64>, ) -> PointerEventTime

Timestamp a live input sample against the current animation clock.

pub fn exact_pointer_event_time( &self, platform_time_ms: Option<i64>, ) -> PointerEventTime

Timestamp deterministic input at the most recently processed frame.

pub fn update_after_frame_interval( &mut self, frame_interval: Duration, ) -> FrameUpdateResult

pub fn update_after_exact_interval( &mut self, frame_interval: Duration, ) -> FrameUpdateResult

Advance the frame clock by EXACTLY frame_interval past the last frame — no wall anchoring — and run one update there. Robot keyframe captures ride this to sample animations deterministically: while the advanced clock is ahead of wall time, interleaved wall-clocked updates clamp to it (dt 0) instead of fast-forwarding animations.

pub fn update_at_frame_time_nanos( &mut self, frame_time: u64, ) -> FrameUpdateResult

pub fn update(&mut self) -> FrameUpdateResult

Trait Implementations

impl<R> Drop for AppShell<R>

where R: Renderer,

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.