Struct SurfaceMut 

pub struct SurfaceMut<'a, R: Renderer> { /* private fields */ }

One surface borrowed together with its shell: the handle a platform delivers a window’s events through and reads a window’s frame from.

AppShell::surface hands one out per root. Every method of AppShell that names no root acts on the primary surface through the same code, so a single-window platform never sees this type.

Implementations

impl<R: Renderer> SurfaceMut<'_, R>

where R::Error: Debug,

pub fn inspector_state(&self) -> &InspectorState

This surface’s developer UI and projected application elements.

impl<R> SurfaceMut<'_, R>

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

pub fn debug_info_report(&mut self) -> String

The layout tree and headless scene of this surface, for a log.

pub fn log_debug_info(&mut self) -> String

Logs Self::debug_info_report and answers it.

impl<R> SurfaceMut<'_, R>

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

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

Sets the device source (touch/mouse/stylus) of the pointer sample that the platform is about to dispatch. Call this before set_cursor / pointer_pressed / pointer_released so the resulting PointerEvents carry the source so consumers can preserve device-specific gesture details without changing shared pointer UI.

pub fn pointer_source(&self) -> PointerSource

The device source of the most recent pointer sample.

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

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

Like set_cursor, but carries the platform input timestamp (milliseconds, platform-specific time base) of the sample.

Platforms that deliver input batched/frame-aligned (Android) must use this so gesture velocity is computed from real event times instead of delivery times.

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

Set the cursor using a timestamp already resolved into both clock domains.

pub fn accessibility_activate( &mut self, node_id: NodeId, canvas_key: Option<u64>, ) -> bool

Activates the identified control using its current semantics and geometry.

Hidden, disabled, removed and modal-background controls reject activation. canvas_key identifies a drawn child of node_id. The action bypasses overlapping controls and developer overlays without changing pointer capture.

pub fn pointer_pressed(&mut self) -> bool

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

Like pointer_pressed, but carries the platform input timestamp (milliseconds) of the press sample.

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

Dispatch primary-button down with an already resolved event timestamp.

pub fn pointer_released(&mut self) -> bool

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

Releases the pointer at the position carried by the platform’s release sample (Android ACTION_UP, web pointerup/touchend).

The cursor is moved to (x, y) WITHOUT dispatching a Move event, then the Up event is dispatched at that position. Platforms whose release events carry their own coordinates must use this instead of set_cursor* + pointer_released*: lift-off samples routinely roll back a few dp against the travel direction as the finger peels off, and feeding that jitter into gesture velocity trackers as a final Move sample can flip the sign of the computed fling velocity (flings that suddenly go the opposite way). Jetpack Compose likewise never feeds the up sample into velocity tracking.

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

Like pointer_released_at_position, but carries the platform input timestamp (milliseconds) of the release sample.

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

Release at a position with an already resolved event timestamp.

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

Like pointer_released, but carries the platform input timestamp (milliseconds) of the release sample.

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

Dispatch primary-button up with an already resolved event timestamp.

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

Dispatches an event for a secondary pointer (pointer_id != 0).

Multi-touch gestures act on the element the first finger grabbed, so secondary pointers are routed to the hit path captured by the primary pointer’s Down. They carry no hover/click semantics and are ignored when no primary gesture is in progress.

Returns true when the event was dispatched to at least one target.

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

Move counterpart of secondary_pointer_pressed.

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

Release counterpart of secondary_pointer_pressed.

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

Dispatches a discrete zoom step (desktop ctrl+wheel, browser pinch) to the pointer handlers under the cursor.

zoom_factor is multiplicative: > 1.0 zooms in, < 1.0 zooms out. Returns true if a handler consumed the event.

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

Dispatches one mouse-wheel / trackpad sample through the whole wheel policy, and returns true when something consumed it.

This is the single entry point every host with a wheel calls, after placing the cursor. A wheel sample is not just a scroll — it is whichever of four things the modifiers and the tree make it, in this order:

1. Zoom when ctrl is held. That is the desktop convention and the way browsers deliver a trackpad pinch, so both arrive here as the same gesture.
2. Rotary, offered to rotary_scrolled before anything else can take it, so the Wear OS crown stack is developable on a machine with a wheel. Nothing consumes rotary unless the app opts in via Modifier::on_rotary_scroll_event or set_on_rotary_scroll, so ordinary scrolling is unaffected.
3. Horizontal scroll when alt is held on a wheel that only reports a vertical axis.
4. Scroll, to the hovered scrollable.

Hosts must not re-implement this order. Doing so is how the browser ended up scrolling backwards and never delivering rotary at all: the policy lived in the desktop event loop, and the second host that grew a wheel reimplemented the parts of it that were obvious from the outside.

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

Dispatches a mouse wheel / trackpad scroll event to hovered pointer handlers.

Returns true if a handler consumed the event.

This is the last step of the wheel policy, not its entry point: hosts call wheel_scrolled, which reaches here once zoom and rotary have declined the sample.

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

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

Installs the window-level rotary (Wear OS crown / rotating bezel) handler — the low-level escape hatch.

The handler runs only after the routed modifier chain has declined the event (see rotary_scrolled), so an app that draws everything into a single canvas receives every rotary delta without registering a focus target or a modifier. Returning true reports the event as consumed to the platform.

Passing a new handler replaces the previous one.

pub fn clear_on_rotary_scroll(&mut self)

Removes the window-level rotary handler, if one is installed.

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

Dispatches a rotary scroll expressed in raw detents (Android AXIS_SCROLL), converting to pixels with the configured scroll factor.

Applies Compose’s sign convention: a positive detent value (crown turned up/away) produces a negative vertical_scroll_pixels.

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

Dispatches a rotary scroll event (Wear OS crown, Galaxy Watch bezel, or a desktop mouse wheel standing in for one during development).

Routing mirrors Compose’s RotaryInputModifierNode contract:

1. Resolve the target chain. When a focus target is registered (cranpose_ui::focus_dispatch::active_focus_target) and still exists in the current scene, its capture path is used, so rotary goes to the focused node exactly as on Wear OS. Cranpose does not yet wire focus automatically, so in practice this falls back to the chain under the current cursor position.
2. Capture pass, root to leaf, invoking on_pre_rotary_scroll_event handlers.
3. Bubble pass, leaf to root, invoking on_rotary_scroll_event handlers.
4. If still unconsumed, the window-level handler installed by set_on_rotary_scroll.

The first handler returning true consumes the event and stops every remaining step. Returns true when the event was consumed.

pub fn cancel_gesture(&mut self)

Cancels any active gesture, dispatching Cancel events to cached targets. Call this when:

• Window loses focus
• Mouse leaves window while button pressed
• Any other gesture abort scenario

pub fn cancel_gesture_unless_pressed(&mut self)

Ends the gesture only when the pointer leaving really ended it.

A held button belongs to the surface that received the press until the release: a window drawn over the cursor, or a drag carried past an edge, both leave the press where it started and deliver the release there too. Cancelling on either would drop a gesture the user has not finished, so a pressed pointer is left alone and only an idle one cancels.

pub fn dismiss_top_modal(&mut self) -> bool

Asks the innermost open dialog or popup to close, the way the platform back gesture does. Answers whether one was open to take the request.

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

Publishes the focus order layout left behind and moves focus one step. Answers whether focus moved.

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

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

Handles paste event from platform clipboard. Returns true if the paste was consumed by a focused text field. O(1) operation using stored handler.

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

Handles copy request from platform. Returns the selected text from focused text field, or None. O(1) operation using stored handler.

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

Handles cut request from platform. Returns the cut text from focused text field, or None. O(1) operation using stored handler.

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

Handles IME preedit (composition) events. Called when the input method is composing text (e.g., typing CJK characters).

• text: The current preedit text (empty to clear composition state)
• cursor: Optional cursor position within the preedit text (start, end)

Returns true if a text field consumed the event.

pub fn on_ime_finish_composing(&mut self) -> bool

Finishes the active IME composition, keeping the composed text as committed text (Android finishComposingText semantics). Returns true if a text field consumed the event.

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

Marks existing text in the focused field as the composing region without changing it (Android setComposingRegion semantics). Offsets are UTF-8 bytes. Returns true if a text field consumed the event.

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

Moves the focused field’s selection/caret to [start_bytes, end_bytes) without editing text (Android InputConnection.setSelection; the path Gboard’s spacebar-swipe uses to scrub the cursor). Offsets are UTF-8 bytes. Returns true if a text field consumed the event.

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

Returns a snapshot of the focused text field’s editable state for platform IMEs (text, selection and composition in UTF-8 bytes), or None when no text field is focused.

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

Window-space caret geometry of the focused field for coordinate-based platform text input (iOS trackpad cursor + tap-to-position), or None when no text field is focused.

pub fn clear_text_field_focus(&mut self)

Clears text-field focus (used by platform IME actions such as Android’s Done). The focus-loss notification hides the soft keyboard.

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

Handles IME delete-surrounding events. Returns true if a text field consumed the event.

impl<'a, R> SurfaceMut<'a, R>

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

pub fn shell(&mut self) -> &mut AppShell<R>

The whole app, for what a window’s event needs beyond its surface: the clipboard, the dev options, a debug report.

pub fn id(&self) -> RootId

Which root this surface draws.

pub fn root(&self) -> Option<NodeId>

The node this surface draws from, when it has one.

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

The renderer that draws this surface.

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

The scene this surface last built.

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

Sets the logical size this surface lays out and draws into.

The primary surface’s viewport is the composition root’s constraints. A window surface’s viewport is what its renderer draws into; the window root lays out to the size its descriptor reports, which the platform keeps equal to this. The next update lays out and renders; AppShell::set_viewport additionally runs that frame at once.

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

Tells the shell where the window drawing this surface sits on the screen, in logical pixels, so pointer events can carry a screen_position. A platform sets it when the window moves and before it delivers a pointer sample; None says the platform does not know.

pub fn screen_origin(&self) -> Option<Point>

Where the window drawing this surface sits on the screen, as the platform last said.

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

The logical size this surface draws into.

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

Sets the physical size of this surface’s framebuffer.

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

The physical size of this surface’s framebuffer.

pub fn mark_dirty(&mut self)

Marks this surface as needing a redraw.

pub fn needs_redraw(&self) -> bool

Whether this surface owes the display a frame: stale pixels, or a renderer that has not warmed its swapchain yet. See AppShell::needs_redraw.

pub fn has_active_pointer_gesture(&self) -> bool

Whether a primary-button gesture that started on this surface is still in progress.

pub fn last_update_result(&self) -> FrameUpdateResult

What the update and frame produced for this surface the last time the app updated.

pub fn frame_owed(&self) -> bool

Whether an update since the platform last presented this surface changed its pixels. An update runs for the whole app, so the update a platform ran for one window may have drawn another; this is how the other window learns it has a frame to show.

pub fn take_frame_owed(&mut self) -> bool

Self::frame_owed, cleared: the platform is about to present.

pub fn frame_schedule(&self) -> FrameSchedule

The frame this surface asks its platform for, recorded for Self::frame_scheduler_snapshot.

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

where D: PlatformFrameDriver + ?Sized,

Computes this surface’s frame schedule and applies it to driver.

pub fn frame_scheduler_snapshot(&self) -> FrameSchedule

The schedule this surface last recorded.

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

Sets how the platform should vote the display’s frame rate for the window showing this surface. See AppShell::set_frame_rate_preference.

pub fn frame_rate_preference(&self) -> FrameRatePreference

This surface’s display frame-rate preference.

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

Where this surface’s dev overlay draws the control for mode, in logical pixels. See AppShell::dev_overlay_control_center.

pub fn with_layout_tree<T>( &mut self, block: impl FnOnce(Option<&LayoutTree>) -> T, ) -> T

Runs block with this surface’s layout snapshot, built on demand.

pub fn with_semantics_tree<T>( &mut self, block: impl FnOnce(Option<&SemanticsTree>) -> T, ) -> T

Runs block with this surface’s semantics snapshot, built on demand; None while semantics are disabled.

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

The pointer icon the platform has not applied to this surface’s window yet. See AppShell::take_pointer_icon_change.

pub fn refresh_pointer_icon(&self)

Offers this surface’s pointer icon to the platform again. See AppShell::refresh_pointer_icon.

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

Installs the platform text input for the window showing this surface. Keyboard requests reach the handler of the surface the platform last called active, and a hide reaches the handler that showed. See AppShell::set_platform_text_input.

pub fn activate(&mut self)

Makes this the surface the platform considers focused: the one the soft keyboard belongs to. Pointer presses do this on their own.