Trait Toolkit 

pub trait Toolkit: Sized + 'static {
    type Handle: Clone + 'static;

    // Required methods
    fn realize(
        &mut self,
        kind: PieceKind,
        props: &dyn Any,
        id: NodeId,
    ) -> Self::Handle;
    fn update(
        &mut self,
        h: &Self::Handle,
        kind: PieceKind,
        patch: &dyn Any,
        anim: Option<&AnimSpec>,
    );
    fn release(&mut self, h: Self::Handle);
    fn insert(
        &mut self,
        parent: &Self::Handle,
        child: &Self::Handle,
        index: usize,
    );
    fn remove(&mut self, parent: &Self::Handle, child: &Self::Handle);
    fn move_child(
        &mut self,
        parent: &Self::Handle,
        child: &Self::Handle,
        to: usize,
    );
    fn measure(
        &mut self,
        h: &Self::Handle,
        kind: PieceKind,
        p: Proposal,
    ) -> Size;
    fn set_frame(
        &mut self,
        h: &Self::Handle,
        frame: Rect,
        anim: Option<&AnimSpec>,
    );
    fn set_input_traits(
        &mut self,
        h: &Self::Handle,
        traits: &InputTraits,
    ) -> Option<Self::Handle>;
    fn set_event_sink(&mut self, sink: EventSink);

    // Provided methods
    fn request_frame(
        &mut self,
        _host: &Self::Handle,
        _cb: FrameCallback,
    ) -> CancelFrame { ... }
    fn capability(&self, _cap: Cap) -> Support { ... }
    fn release_piece(&mut self, _kind: PieceKind, _h: &Self::Handle) { ... }
    fn first_baseline(
        &mut self,
        _h: &Self::Handle,
        _kind: PieceKind,
        _size: Size,
    ) -> Option<f64> { ... }
    fn set_opacity(
        &mut self,
        _h: &Self::Handle,
        _opacity: f64,
        _anim: Option<&AnimSpec>,
    ) { ... }
    fn set_transform(
        &mut self,
        _h: &Self::Handle,
        _t: Transform,
        _size: Size,
        _anim: Option<&AnimSpec>,
    ) { ... }
    fn set_selectable(
        &mut self,
        _h: &Self::Handle,
        _selectable: bool,
    ) -> Option<Self::Handle> { ... }
    fn set_cursor(&mut self, _h: &Self::Handle, _cursor: Cursor) { ... }
    fn set_scroll_content(&mut self, _h: &Self::Handle, _content: Size) { ... }
    fn scroll_bar_inset(&mut self, _h: &Self::Handle, _vertical: bool) -> f64 { ... }
    fn list_row_metrics(&mut self, _h: &Self::Handle) -> RowMetrics { ... }
    fn scroll_to(&mut self, _h: &Self::Handle, _target: Rect, _animated: bool) { ... }
    fn scroll_offset(&mut self, _h: &Self::Handle) -> Point { ... }
    fn enable_gesture(
        &mut self,
        _h: &Self::Handle,
        _node: NodeId,
        _kind: GestureKind,
    ) { ... }
    fn focus(&mut self, _h: &Self::Handle, _node: NodeId, _focused: bool) { ... }
    fn set_focusable(
        &mut self,
        _h: &Self::Handle,
        _node: NodeId,
        _focusable: bool,
    ) { ... }
    fn attach_list(&mut self, _host: &Self::Handle, _source: ListSource) { ... }
    fn attach_tree(&mut self, _host: &Self::Handle, _source: TreeSource) { ... }
    fn set_route(&mut self, _route: &str) { ... }
    fn set_undo_state(&mut self, _state: &UndoState) { ... }
    fn set_edit_state(&mut self, _state: &EditState) { ... }
    fn modifiers(&mut self) -> Modifiers { ... }
    fn set_drag_source(&mut self, _h: &Self::Handle, _source: Source) { ... }
    fn set_drop_target(&mut self, _h: &Self::Handle, _target: Target) { ... }
    fn set_context_menu_fn(
        &mut self,
        _h: &Self::Handle,
        _node: NodeId,
        _f: ContextMenuFn,
    ) { ... }
    fn set_app_menu(&mut self, _items: &[MenuItem]) { ... }
    fn set_context_menu(
        &mut self,
        _h: &Self::Handle,
        _node: NodeId,
        _items: &[MenuItem],
    ) { ... }
    fn edit_toolbar(&mut self, _h: &Self::Handle, _ops: &[ToolbarOp]) -> bool { ... }
    fn update_toolbar(&mut self, _h: &Self::Handle, _patch: &ToolbarPatch) { ... }
    fn supports_lifecycle(&self, phase: Lifecycle) -> bool { ... }
    fn set_a11y(&mut self, _h: &Self::Handle, _a11y: &A11yProps) { ... }
    fn announce(&mut self, _text: &str, _urgent: bool) { ... }
    fn read_native(&self, _h: &Self::Handle) -> NativeSnapshot { ... }
    fn replay(&mut self, _h: &Self::Handle, _ops: &[DrawOp], _size: Size) { ... }
    fn font_families(&mut self) -> Vec<FontFamilyInfo> { ... }
    fn measure_text(
        &mut self,
        _text: &str,
        _size: f64,
        _font: &CanvasFont,
    ) -> Option<TextMetrics> { ... }
    fn decode_image(&mut self, _req: u64, _id: BitmapId, _bytes: &[u8]) { ... }
    fn image_info(&mut self, _id: BitmapId) -> Option<BitmapInfo> { ... }
    fn image_properties(&mut self, _id: BitmapId) -> Option<ImageProperties> { ... }
    fn encode_image(&mut self, _req: u64, _id: BitmapId, _spec: &EncodeSpec) { ... }
    fn encode_formats(&mut self) -> Vec<ImageFormat> { ... }
    fn release_image(&mut self, _id: BitmapId) { ... }
    fn render_bitmap(
        &mut self,
        _req: u64,
        _id: BitmapId,
        _ops: &[DrawOp],
        _size: Size,
        _scale: f64,
    ) { ... }
    fn render_pdf(&mut self, _req: u64, _pages: &[PdfPage], _info: &PdfInfo) { ... }
    fn snapshot_window(&mut self) -> Result<Vec<u8>, String> { ... }
    fn snapshot_origin(&mut self, _root: &Self::Handle) -> Option<Point> { ... }
    fn prepare_snapshot(
        &mut self,
        _host: Option<&Self::Handle>,
        _revision: u32,
    ) -> Result<Readiness, String> { ... }
    fn snapshot_window_chrome(&mut self) -> Result<Vec<u8>, String> { ... }
    fn toggle_sidebar(&mut self, _host: &Self::Handle) -> bool { ... }
    fn native_back(&mut self) -> bool { ... }
    fn ui_idle(&mut self) -> bool { ... }
    fn present(&mut self, _req: u64, _spec: &PresentSpec) { ... }
    fn dismiss(&mut self, _req: u64) { ... }
    fn open_url(&mut self, _url: &str) { ... }
    fn share_support(&self) -> Support { ... }
    fn share_url(&mut self, _url: &str, _title: &str) -> bool { ... }
    fn application_handlers(
        &mut self,
        _query: &HandlerQuery,
    ) -> Result<ApplicationHandlers, ApplicationError> { ... }
    fn open_url_with_application(
        &mut self,
        _url: &str,
        _application: &str,
        completion: OpenApplicationCompletion,
    ) { ... }
    fn defer_system_gestures(&mut self, _edges: Edges) { ... }
    fn set_status_bar_hidden(&mut self, _hidden: bool) { ... }
    fn dark_mode(&mut self) -> bool { ... }
    fn reduce_motion(&mut self) -> bool { ... }
    fn set_appearance(&mut self, _dark: Option<bool>) { ... }
    fn set_app_badge(&mut self, _badge: &AppBadge) { ... }
    fn on_suspend(&mut self) { ... }
    fn on_resume(&mut self) { ... }
    fn on_memory_warning(&mut self) { ... }
    fn adopt(&mut self, _raw: RawHandle) -> Self::Handle { ... }
    fn open_window(
        &mut self,
        _id: NodeId,
        _options: &WindowOptions,
        _kind: WindowKind,
    ) -> WindowOpenReply<Self::Handle> { ... }
    fn close_window(&mut self, _host: &Self::Handle) { ... }
    fn quit_app(&mut self) { ... }
    fn focus_window(&mut self, _host: &Self::Handle) { ... }
    fn set_window_title(&mut self, _host: &Self::Handle, _title: &str) { ... }
    fn fit_window(&mut self, _host: &Self::Handle, _size: Size) { ... }
    fn snapshot_window_of(
        &mut self,
        _host: &Self::Handle,
    ) -> Result<Vec<u8>, String> { ... }
    fn apply_window(&mut self, _host: &Self::Handle, _change: &WindowChange) { ... }
    fn native_window_tabs(&self) -> bool { ... }
    fn native_document_tabs(&self) -> bool { ... }
    fn group_windows(&mut self, _hosts: &[Self::Handle]) { ... }
    fn window_tab_order(&self, _host: &Self::Handle) -> Vec<NodeId> { ... }
    fn set_dock_menu(&mut self, _items: &[MenuItem]) { ... }
    fn set_drag_region(&mut self, _h: &Self::Handle, _drag: bool) { ... }
    fn set_status_items(&mut self, _items: &[StatusItemSpec]) { ... }
    fn set_app_progress(&mut self, _progress: AppProgress) { ... }
    fn set_dock_visible(&mut self, _visible: bool) { ... }
    fn set_keep_running(&mut self, _keep: bool) { ... }
    fn monitors(&self) -> Vec<Monitor> { ... }
    fn window_frame(&self, _host: &Self::Handle) -> Option<Rect> { ... }
    fn set_launcher_shortcuts(&mut self, _shortcuts: &[LauncherShortcut]) { ... }
}

Required Associated Types

type Handle: Clone + 'static

Required Methods

fn realize( &mut self, kind: PieceKind, props: &dyn Any, id: NodeId, ) -> Self::Handle

fn update( &mut self, h: &Self::Handle, kind: PieceKind, patch: &dyn Any, anim: Option<&AnimSpec>, )

fn release(&mut self, h: Self::Handle)

Called from the turn-boundary release queue; backends may defer destruction further.

fn insert(&mut self, parent: &Self::Handle, child: &Self::Handle, index: usize)

fn remove(&mut self, parent: &Self::Handle, child: &Self::Handle)

fn move_child(&mut self, parent: &Self::Handle, child: &Self::Handle, to: usize)

Put child at index to among parent’s native children: day’s z-order resync, which walks the whole sibling row and asks for every position in turn. A child already at to must therefore cost nothing: a backend that re-parents unconditionally pays for the untouched siblings too, and where re-parenting means detach-then-add (no ViewGroup move primitive on Android) the detach resigns the focus of everything inside the subtree, which is how a text field being typed into loses the keyboard (docs/focus.md).

fn measure(&mut self, h: &Self::Handle, kind: PieceKind, p: Proposal) -> Size

fn set_frame(&mut self, h: &Self::Handle, frame: Rect, anim: Option<&AnimSpec>)

fn set_input_traits( &mut self, h: &Self::Handle, traits: &InputTraits, ) -> Option<Self::Handle>

fn set_event_sink(&mut self, sink: EventSink)

Provided Methods

fn request_frame( &mut self, _host: &Self::Handle, _cb: FrameCallback, ) -> CancelFrame

Request one frame for the window containing host. Never call inline. Each native source must stop after delivery unless requested again; no polling timer. Hidden/unmapped windows may defer delivery until visible. Native callbacks must reach the UI thread before calling Rust. The returned closure cancels safely, including when the window has closed. The mock intentionally stays pending: tests inject a manual scheduler in day-core.

fn capability(&self, _cap: Cap) -> Support

fn release_piece(&mut self, _kind: PieceKind, _h: &Self::Handle)

Give a satellite piece a chance to drop its own per-view state, immediately before release frees h (§15.2).

A backend that hosts third-party pieces implements this by looking kind up in its renderer registry and calling that piece’s release hook. Defaulted to nothing: a backend with no registry has nothing to dispatch, and one that has not wired this yet leaves piece teardown unrun rather than failing to build.

fn first_baseline( &mut self, _h: &Self::Handle, _kind: PieceKind, _size: Size, ) -> Option<f64>

Distance from the top of the widget’s frame to its first text baseline, in points, when the widget is size (docs/baseline.md). None ⇒ it has no text baseline (an image, a slider, a bare container) and a baseline-aligned row falls back to box alignment for it.

This is a measurement, not a layout mode: day places every frame itself (§7.1) and never hands a row to a native baseline-aligning container, so what it needs from the toolkit is where the text sits inside the box. Backends that cannot answer keep the default and rows stay centered, which is what every row did before this existed.

fn set_opacity( &mut self, _h: &Self::Handle, _opacity: f64, _anim: Option<&AnimSpec>, )

fn set_transform( &mut self, _h: &Self::Handle, _t: Transform, _size: Size, _anim: Option<&AnimSpec>, )

fn set_selectable( &mut self, _h: &Self::Handle, _selectable: bool, ) -> Option<Self::Handle>

fn set_cursor(&mut self, _h: &Self::Handle, _cursor: Cursor)

fn set_scroll_content(&mut self, _h: &Self::Handle, _content: Size)

fn scroll_bar_inset(&mut self, _h: &Self::Handle, _vertical: bool) -> f64

fn list_row_metrics(&mut self, _h: &Self::Handle) -> RowMetrics

fn scroll_to(&mut self, _h: &Self::Handle, _target: Rect, _animated: bool)

fn scroll_offset(&mut self, _h: &Self::Handle) -> Point

fn enable_gesture( &mut self, _h: &Self::Handle, _node: NodeId, _kind: GestureKind, )

fn focus(&mut self, _h: &Self::Handle, _node: NodeId, _focused: bool)

fn set_focusable(&mut self, _h: &Self::Handle, _node: NodeId, _focusable: bool)

fn attach_list(&mut self, _host: &Self::Handle, _source: ListSource)

fn attach_tree(&mut self, _host: &Self::Handle, _source: TreeSource)

fn set_route(&mut self, _route: &str)

fn set_undo_state(&mut self, _state: &UndoState)

fn set_edit_state(&mut self, _state: &EditState)

fn modifiers(&mut self) -> Modifiers

fn set_drag_source(&mut self, _h: &Self::Handle, _source: Source)

fn set_drop_target(&mut self, _h: &Self::Handle, _target: Target)

fn set_context_menu_fn( &mut self, _h: &Self::Handle, _node: NodeId, _f: ContextMenuFn, )

fn set_app_menu(&mut self, _items: &[MenuItem])

The application menu (macOS/Windows/Linux menu bar; the app-bar overflow on Android; the UIMenuBuilder main menu on iPadOS/Catalyst). Replaces any previous app menu.

fn set_context_menu( &mut self, _h: &Self::Handle, _node: NodeId, _items: &[MenuItem], )

A context menu for h, shown on secondary-click (desktop) or long-press (mobile). Passing an empty slice removes it.

fn edit_toolbar(&mut self, _h: &Self::Handle, _ops: &[ToolbarOp]) -> bool

Edit the window’s toolbar (docs/toolbars.md): the ToolbarOps, removals first, then insertions in ascending position. The bar starts empty, and becomes empty again when every item has been removed, at which point the backend takes it off the window.

An item no op names must keep its native widget untouched, which is what keeps a search field focused while the page around it changes. Day sends an edit only when the bar changed, at most once per turn, and an item keeps its ToolbarItem::action for as long as its window shows an item with that id, so a native item’s handler never needs repointing. Keep a ToolbarMirror and place each new item after ToolbarMirror::prev_where its group.

Returns whether the edit was applied. false (the window has no bar to edit yet) makes Day send the whole bar again at the next change rather than assume this one landed.

fn update_toolbar(&mut self, _h: &Self::Handle, _patch: &ToolbarPatch)

Apply a targeted change to one live toolbar item, the path a bound signal writes through, so syncing a search field does not rebuild the bar. No-op if the item is not present.

fn supports_lifecycle(&self, phase: Lifecycle) -> bool

fn set_a11y(&mut self, _h: &Self::Handle, _a11y: &A11yProps)

Apply a node’s accessibility annotations (docs/accessibility.md): the label, hint and value the screen reader speaks, an explicit role, whether the node is hidden from assistive technology, and the automation identifier. Called with the node’s whole accumulated set each time any of it changes, so every member is written on every call. Only an explicit role is applied: a native control reports its own.

fn announce(&mut self, _text: &str, _urgent: bool)

Speak text through the screen reader without moving its focus (docs/accessibility.md; probe Cap::Announce). urgent interrupts what is being read; otherwise the sentence waits its turn. Nothing happens when no screen reader is running. The default is a backend that reaches no announcement API.

fn read_native(&self, _h: &Self::Handle) -> NativeSnapshot

Read a widget’s native state back from the platform for a11y_audit and assert_native (§14.2, docs/testing.md) to diff against Day’s expectation. Default: nothing read; the audit skips the node and assert_native records each field as unread.

fn replay(&mut self, _h: &Self::Handle, _ops: &[DrawOp], _size: Size)

fn font_families(&mut self) -> Vec<FontFamilyInfo>

Every family this toolkit can draw canvas text in, with the faces each ships (docs/fonts.md; probe Cap::FontList). Default: none. day::font_families calls this once per process and caches the answer: enumeration is slow on every platform (fontconfig, a DirectWrite collection, an XML parse on Android) and the set does not change under a running app.

fn measure_text( &mut self, _text: &str, _size: f64, _font: &CanvasFont, ) -> Option<TextMetrics>

Measure one line of canvas text at size points in font, in the same engine Toolkit::replay draws DrawOp::Text with, so a TextAnchor::LEADING anchor plus the returned ascent lands on the drawn baseline. None = cannot measure; the facade then answers TextMetrics::approximate.

fn decode_image(&mut self, _req: u64, _id: BitmapId, _bytes: &[u8])

Decode encoded image bytes (PNG/JPEG/…) into a native image, answering req with Event::ImageDecoded.

The id in that event is minted by the caller (day-core), not the backend: the backend keeps its own side table from that id to whatever it decoded.

The default does nothing because a default body cannot reach the event sink (it is installed per backend by Toolkit::set_event_sink, not reachable through this trait), so there is no way for it to answer. day-core asks Cap::ImageDecode first and resolves the request as ImageError::Unsupported itself, which is why a backend with no decoder needs no code here at all.

fn image_info(&mut self, _id: BitmapId) -> Option<BitmapInfo>

What a decoded image is: pixel size, scale, format, alpha (BitmapInfo).

Synchronous: every backend that decoded the image already holds these facts. None means the id names nothing live.

fn image_properties(&mut self, _id: BitmapId) -> Option<ImageProperties>

The metadata beyond the pixels: EXIF orientation, DPI, capture time (ImageProperties, probe Cap::ImageProperties). None where the backend has no metadata reader, which is most of them.

fn encode_image(&mut self, _req: u64, _id: BitmapId, _spec: &EncodeSpec)

Encode a decoded image back to bytes per spec, answering req with Event::ImageEncoded. A format outside Self::encode_formats answers ImageError::Encode rather than silently substituting another one.

Defaulted to nothing for the same reason as Self::decode_image: day-core probes Cap::ImageEncode and answers Unsupported without ever calling this.

fn encode_formats(&mut self) -> Vec<ImageFormat>

Which formats Self::encode_image can write, the Cap::ImageEncode counterpart of Self::font_families/Cap::FontList. Empty by default.

fn release_image(&mut self, _id: BitmapId)

Drop a decoded image and everything the backend cached for it. Called when the app’s last handle to it goes away; an id the backend never saw is a no-op.

fn render_bitmap( &mut self, _req: u64, _id: BitmapId, _ops: &[DrawOp], _size: Size, _scale: f64, )

Replay ops into a new offscreen bitmap of size points at scale pixels per point (export_pixels gives the pixel size), with a transparent background and the canvas’s top-left origin. Store it under id in the same table Self::decode_image fills, so image_info, encode_image, release_image, the image piece and DrawOp::Image all take it, then answer req with Event::BitmapRendered (its BitmapInfo::scale is scale).

The painter must be the one Self::replay uses, so text, gradients, clips and stamps match the screen. Defaulted to nothing: day-core probes Cap::CanvasBitmap and answers ExportError::Unsupported itself.

fn render_pdf(&mut self, _req: u64, _pages: &[PdfPage], _info: &PdfInfo)

Replay each page into one PDF document and answer req with Event::PdfRendered. Units are PDF points, top-left origin; shapes and text stay vector, and images embed at their pixel size. pages is never empty. Defaulted to nothing: day-core probes Cap::CanvasPdf first.

fn snapshot_window(&mut self) -> Result<Vec<u8>, String>

fn snapshot_origin(&mut self, _root: &Self::Handle) -> Option<Point>

Where root, the primary window’s root container, sits in Self::snapshot_window’s image, in points from its top-left. A reader of the capture (dayscript sample_pixel) maps Day’s frames into it with this; it matters where the capture spans more than Day’s content on more than one side, as Android’s edge-to-edge content does (status bar above, navigation bar below).

Defaulted to None, which the reader takes as “any rows beyond Day’s content are above it”, true where the only extra area is a title bar.

fn prepare_snapshot( &mut self, _host: Option<&Self::Handle>, _revision: u32, ) -> Result<Readiness, String>

Establish a fresh screenshot checkpoint after reactive work and native transitions. revision is stable across retries and unique to the request; host selects a secondary window, or None for the primary. Never block the UI thread waiting for a frame. Pending requests are retried within the dayscript deadline.

Ready means the platform render checkpoint completed, not that a vsync callback proves pixels were displayed. OnCapture delegates freshness to snapshot_window.

fn snapshot_window_chrome(&mut self) -> Result<Vec<u8>, String>

The same capture with the window’s own chrome: title bar, toolbar, whatever the platform draws around the content (docs/window-image.md).

Defaulted to Self::snapshot_window: a backend that cannot separate the two (or has no chrome to speak of, a phone) answers with the content shot rather than an error, so an app asking for chrome degrades to “what there was” instead of failing. The dayscript screenshot step never calls this, which is what keeps every captured gallery baseline byte-identical to before it existed.

fn toggle_sidebar(&mut self, _host: &Self::Handle) -> bool

Show/hide the sidebar pane of the navigation host host, which is what the sidebar affordance a nav(Sidebar) contributes for itself drives (SIDEBAR_TOGGLE_ID). false when host has no pane to toggle (a stack, a tab bar, no sidebar concept at all).

Per host, not per process: a second window’s button collapses that window’s sidebar and not the first’s. The item’s own action makes the call, and dayscript’s toolbar: step presses the item like any other, so a walkthrough drives exactly the path a click takes. Defaulted, so a backend with no sidebar needs no code. docs/toolbars.md, docs/navigation.md.

fn native_back(&mut self) -> bool

Press the platform’s own back affordance (the navigation bar’s back button on iOS, the system back on Android) on the innermost navigation host that has something to pop. What nav_back() does not do: that is Day’s rail, which pops the model and lets the backend follow, while this runs the native path first (the bar’s shouldPop, the dispatcher’s callbacks, the pop itself) and lets the backend report it to Day as a user back, guard and all. dayscript’s nav_back: { native: true } drives it, so a walkthrough can cover the code that a real tap runs and Day’s rail never reaches. false when this toolkit has no native back or nothing is popped by it. Defaulted, so a desktop needs no code. docs/navigation.md.

fn ui_idle(&mut self) -> bool

Whether the UI has settled, with no native transition (modal present/dismiss, nav push) still animating. The dayscript screenshot step polls this before capturing so shots never catch a half-faded dialog or half-pushed page. Backends without async transitions (or without a way to know) report true.

fn present(&mut self, _req: u64, _spec: &PresentSpec)

fn dismiss(&mut self, _req: u64)

fn open_url(&mut self, _url: &str)

Open url in the platform’s default handler: the system browser for http(s), the mail client for mailto:, etc. Backs the link piece. Fire and forget: there is no result, and an unopenable URL is ignored. The default no-ops so a backend that hasn’t wired it up still compiles.

fn share_support(&self) -> Support

Whether a native share chooser is available. Does not probe installed share targets.

fn share_url(&mut self, _url: &str, _title: &str) -> bool

Present the system share chooser. True means presentation started, not that sharing completed. Never sends data without the user’s choice of a target.

fn application_handlers( &mut self, _query: &HandlerQuery, ) -> Result<ApplicationHandlers, ApplicationError>

Read current OS associations. Unsupported platforms must not fabricate a default.

fn open_url_with_application( &mut self, _url: &str, _application: &str, completion: OpenApplicationCompletion, )

Open with an opaque application identifier returned by application_handlers.

fn defer_system_gestures(&mut self, _edges: Edges)

Ask the OS to require a second swipe for its edge gestures on edges (docs/cover.md): the union requested by every mounted defers_system_gestures modifier, re-sent whenever that set changes (Edges::NONE when the last one unmounts). iOS defers the home indicator / notification edges; Android enters swipe-to-reveal immersive mode while non-empty. The default no-ops (desktop has no system edge gestures).

fn set_status_bar_hidden(&mut self, _hidden: bool)

Hide (true) or show the system status bar (docs/cover.md): whether any mounted status_bar_hidden modifier currently asks for it hidden, re-sent whenever that answer may have changed (false when the last request unmounts). iOS answers the root and cover view controllers’ prefersStatusBarHidden; Android and HarmonyOS hide the status bar through their window inset controls. The default no-ops (desktop and web have no status bar); report Cap::StatusBarHidden alongside an implementation.

fn dark_mode(&mut self) -> bool

Whether the platform is rendering in dark appearance right now. Apps painting custom surfaces (opaque overlay panels, scrims) branch on this so their fills track the theme the default text colors already follow; hardcoding either theme’s surface produces dark-on-dark or light-on-light text on the other. Queried at build time (a piece rebuilt after a theme change re-queries). The default honors a DAY_THEME launch override and otherwise answers light.

fn reduce_motion(&mut self) -> bool

Whether the user asked the system for less motion (docs/accessibility.md; probe Cap::ReduceMotion): macOS and iOS “Reduce Motion”, Android “Remove animations” (an animator duration scale of zero), GTK’s gtk-enable-animations off, Windows “Show animations” off, the web’s prefers-reduced-motion. Read at launch; a backend that watches the setting calls day_core::note_motion_changed when it flips. Day then applies every finite animation at its destination and keeps only indeterminate motion. The default is a backend that reads no such setting.

fn set_appearance(&mut self, _dark: Option<bool>)

App-level appearance override: Some(true) forces dark, Some(false) forces light, None returns to following the system. Backends restyle their native widgets in place and answer the override from dark_mode; app-painted surfaces pick it up on their next rebuild. Cap::Appearance reports whether the backend honors this; the default ignores the call.

fn set_app_badge(&mut self, _badge: &AppBadge)

Put badge on the app’s icon in the Dock / launcher / home screen (docs/badge.md).

Fire-and-forget, like set_appearance: a payload this toolkit cannot render is ignored, and the app probes Cap::AppBadge{Count,Text,Dot} before choosing one. Never substitute: a backend that turned Text("beta") into Count(1) would put a wrong number on a user’s icon, which is worse than showing nothing. The default ignores every call.

fn on_suspend(&mut self)

fn on_resume(&mut self)

fn on_memory_warning(&mut self)

fn adopt(&mut self, _raw: RawHandle) -> Self::Handle

fn open_window( &mut self, _id: NodeId, _options: &WindowOptions, _kind: WindowKind, ) -> WindowOpenReply<Self::Handle>

Open a native OS window per options + kind: create and show the window, wire its events to id (WindowResized with the content size in points, WindowClosed after the native close, WindowFocused on key/active changes), and answer with its content container handle, the same contract as the ready root container. Backends whose window creation is asynchronous (a scene, an activity, an ability) answer WindowOpenReply::Pending and complete later through day_core::finish_window_open(id, raw, size), which goes through Toolkit::adopt. The default answers Unsupported; day-core then presents the content as a fullscreen cover in the primary window instead.

fn close_window(&mut self, _host: &Self::Handle)

Close the native window whose content container is host (a handle open_window produced). Asynchronous: the platform confirms with Event::WindowClosed on the window’s root node, and only then does day-core tear the subtree down. Idempotent; unknown hosts are ignored. Never called with the primary window’s container.

fn quit_app(&mut self)

End the application: the last window with WindowRole::Primary has closed (docs/windows.md). day-core decides when, since it owns the window registry and the role each window carries; the backend supplies only the platform’s exit: NSApplication.terminate, QCoreApplication::quit, GtkApplication.quit, PostQuitMessage. Everything day-core wanted to happen first (secondary windows disposed, WillTerminate delivered) already has by the time this is called.

The default does nothing, which is right for the backends whose process lifetime is not theirs to end: a browser tab, an Android activity, an iOS scene.

fn focus_window(&mut self, _host: &Self::Handle)

Bring the window whose content container is host to front and make it key/active: the focus half of open-or-focus singleton windows. Default no-op.

fn set_window_title(&mut self, _host: &Self::Handle, _title: &str)

Retitle the window whose content container is host. Default no-op.

fn fit_window(&mut self, _host: &Self::Handle, _size: Size)

Resize the window whose content container is host to fit size of content, and pin it there: what WindowOptions::size_to_fit asks for (docs/windows.md).

size is the content size Day measured, not the window’s outer frame: the backend adds its chrome. A settings panel is the case this exists for, and every desktop platform sizes one to its content rather than to a number the app guessed; a fixed height either clips the last row or leaves a band of empty panel under it, and which one you get depends on the user’s text size.

Default no-op, so a toolkit that cannot resize a live window keeps the size it was opened at, which is what every backend did before this existed.

fn snapshot_window_of( &mut self, _host: &Self::Handle, ) -> Result<Vec<u8>, String>

Snapshot the window whose content container is host (the dayscript screenshot step’s window: target). The default answers the primary snapshot, so backends that never open windows stay correct without changes.

fn apply_window(&mut self, _host: &Self::Handle, _change: &WindowChange)

Apply one property change to the window whose content container is host (docs/windows.md “Window properties”). The primary window arrives with its root container, like set_window_title.

Fire-and-forget, like set_app_badge: a change this toolkit cannot make is ignored, and the app probes the matching Cap (named on each WindowChange variant) before relying on it. A change the platform completes later (a fullscreen transition, a zoom animation) reports its outcome through Event::WindowStateChanged, never by assuming the request took. The default ignores every change.

fn native_window_tabs(&self) -> bool

True OS window groups, as distinct from native tab widgets.

fn native_document_tabs(&self) -> bool

Native in-window document/section tab control; OS grouping is reported separately.

fn group_windows(&mut self, _hosts: &[Self::Handle])

Join/reorder these windows in an OS tab group. Content remains window-owned.

fn window_tab_order(&self, _host: &Self::Handle) -> Vec<NodeId>

Current native order of the group containing this window, including detached groups.

fn set_dock_menu(&mut self, _items: &[MenuItem])

Install the app’s Dock menu (docs/menus.md “Dock menu”): the items macOS shows above its own when the user right-clicks the app’s Dock icon, built from the app’s [[shortcuts]] and its dock_menu(..) entries. Same item model and dispatch as set_app_menu; an empty slice removes the menu. Cap::DockMenu reports support; the default ignores the call.

fn set_drag_region(&mut self, _h: &Self::Handle, _drag: bool)

Make the node at h move its window when the user drags it, as a title bar does (.window_drag_region(), docs/window-chrome.md): the region’s own background starts a native window drag (with the platform’s snapping and edge tiling), a double click does what the user’s title-bar double-click setting says, and controls inside the region keep receiving their own clicks. false releases it. Cap::DragRegion; the default ignores the call, so on a phone the region is an ordinary view.

fn set_status_items(&mut self, _items: &[StatusItemSpec])

Show these status items, replacing the previous set (docs/status-item.md): add the ones whose id is new, update the ones that changed, remove the ones no longer listed. A click on an item runs its activate action or opens its menu; menu choices dispatch Event::MenuAction like the app menu’s. Cap::StatusItem; the default ignores the call, which is what a phone and the web do.

fn set_app_progress(&mut self, _progress: AppProgress)

Show progress on the app’s Dock or taskbar icon (docs/status-item.md). Cap::AppProgress; the default ignores it.

fn set_dock_visible(&mut self, _visible: bool)

Show or hide the app’s Dock icon while it runs: a menu-bar app hides it and lives in its status item (macOS activation policy). Cap::DockVisibility; the default ignores it.

fn set_keep_running(&mut self, _keep: bool)

Keep the process running when its last window closes (docs/windows.md “Keeping the app running”). When true, the backend must not end the app on its own as windows close: it reports every close, the first window’s included, as Event::WindowClosed, and day-core decides whether to call quit_app. When false, the backend keeps its platform’s own rule. A backend whose process lifetime is not its own (a phone, a browser tab) ignores it, which is the default.

fn monitors(&self) -> Vec<Monitor>

The displays attached now (docs/windows.md “Monitors”). Cap::Monitors; the default answers none, and day-core then describes the primary window’s own size as one display.

fn window_frame(&self, _host: &Self::Handle) -> Option<Rect>

The outer frame of the window whose content container is host, in points on the desktop’s coordinate space (top-left origin), or None where the platform does not say (a phone, Wayland’s positions). Read when the app asks for it and when day-core saves a remembered frame (WindowOptions::remember_frame).

fn set_launcher_shortcuts(&mut self, _shortcuts: &[LauncherShortcut])

Replace the launcher shortcuts the app set while running (docs/deep-links.md “Launcher shortcuts”), shown beside the ones Day.toml declares: iOS Home Screen quick actions, Android dynamic shortcuts, the macOS Dock menu. Each opens its route through the deep-link intake. Cap::DynamicShortcuts; the default ignores the call.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors