Expand description
Day, the umbrella crate apps depend on. One backend feature per binary (§3.2).
Re-exports§
Modules§
- async_
image - Images decoded from reactive bytes, with a placeholder and optional clipping. Uses the core decoder and canvas; no toolkit-specific image pipeline or HTTP dependency.
- clipboard
- MIME-typed text and binary clipboard data, with async browser support.
- colorpicker
- day_pieces::colorpicker is a color chooser bound two-way to a
Signal<Color>, in two idioms (docs/colorpicker.md; DESIGN.md §15). - combobox
- Core editable combo box. Protocol types live in
day-spec; each supported toolkit owns its native renderer and any required C++ or Java shim. - conformance
- Tests that run inside the built app (docs/testing.md):
#[day::test],Case,Drive. Tests that run inside a built Day app (docs/testing.md): aCaseis a page plus a drive, or a headless run, declared next to the code it tests with#[day::test]and collected in a registry. The dayscript engine runs them on a real toolkit underday test; the mock harness runs the same functions undercargo test. Nothing here knows how a step is executed: aDriveBackenddoes, and the engine supplies one. - cursor
- Pointer shapes for the
.cursor()decorator (docs/cursor.md). - datetime
- day_pieces::datetime: core date and time pickers with native toolkit renderers and a composed DOM fallback (docs/datepicker.md; DESIGN.md §15).
- frame
- Window-scoped display scheduling (docs/frames.md). Native frame requests are shared by
one-shot clients, continuous subscriptions and the legacy
frame_clockpiece. No timers, no implicit physics clamp, and no native request when there is no demand. - lifecycle
- App-lifecycle support for the backend compiled into this binary (docs/lifecycle.md).
- pager
- Native interactive horizontal paging. Slots have stable native identities;
orderchooses which slots participate and their reading order. Changing order never rebuilds a page. Apps must defer changing slot contents whilebusyis true. Native callbacks carry the presentation epoch, so delayed completions cannot select a recycled slot. - prefs
- prelude
- pullrefresh
- day_pieces::pullrefresh: pull-to-refresh for any Day scrollable, modeled on SwiftUI’s
refreshable(action:)(DESIGN.md §15; docs/extending.md). - reactive
- The reactive core, whole (docs/async.md):
day::reactive::{Resource, Load}for async data loading. Namespaced because the prelude’sResourceis the asset handle above, a different type that predates the async one. - record
- dayscript recording and action logging (docs/dayscript.md “Recording”, DESIGN §14.6):
install an observer that sees the user’s taps, edits, selections, and navigation.
day::record::{start, start_into, start_to_file, stop, is_recording, recording_signal, script, steps, save, clear, exclude_prefix}captures them into a replayable dayscript; a recorder also arms headlessly fromday launch --record <file>(theDAY_RECORDenv, honored insideday_script::init). What it records is an ordinary dayscript, so it replays cross-toolkit throughplay_scriptorday launch -t <target> --script <file>. - res
- Day’s own strings, named the way an app’s are:
res::str::day_cancel(),res::str::day_about_app(name), one typed function per message in the core catalog (day-localization/catalog/en.ftl), generated from it at build time (docs/localization.md). - searchfield
- Core search input with a toolkit-owned native renderer: NSSearchField, UISearchTextField, GtkSearchEntry, a Qt search field, Android search input, XAML AutoSuggestBox, or DOM search input.
- stepper
- day_pieces::stepper: a numeric stepper field, a text field with increment/decrement arrows,
bound two-way to any
Binding<f64>(docs/stepper.md). - testing
- Tweening for canvas animations (docs/tween.md):
Lerp,Timing,animate,Tweened. Opt-in presentation policy for functional walkthroughs: fast mode is reduced motion forced on (docs/accessibility.md), nothing more. This is not a virtual clock: timers, network requests, physics and media retain their real timing. - transfer
- Native drag-and-drop data and acceptance policy. Native drag data and synchronous destination policy. No clipboard or process-local transport.
- tween
- Tweening for canvas animations (docs/tween.md):
Lerp,Timing,animate,Tweened. Tweening for self-drawn content (docs/tween.md): the pieces a canvas animation needs that native widgets get from their toolkit.
Macros§
- day_
start - One entry point for every platform that needs one: the single line an app’s
lib.rscarries instead of one macro per platform. - day_
start_ android - Expands to the two JNI exports that start the app,
DayBridge.nativeStart(the primary window) andDayBridge.nativeStartWindow(a secondary one), wired to the given root piece. They live in the app cdylib because they name the app’s root; every other native the bridge declares is registered by day-toolkit-material’sDayBridgebinding (docs/android-jni.md). - day_
start_ arkui - Expands to the
day_arkui_startC export the HarmonyOS ArkUI shim’sstart(...)NAPI wrapper calls (from ArkTS:import native from 'libday_arkui.so'; native.start(nodeContent, w, h, density)). It mounts the app’srootpiece into the ArkTSNodeContentand runs the loop. - day_
start_ ios - Expands to the
day_mainC export the iOS Runner’smain.swiftcalls (@_silgen_name("day_main")). The optional title is currently unused on iOS (the window fills the screen bounds); accepted for future window-scene use. - day_
start_ macos - Expands to the
day_mainC export the macOS Runner’smain.swiftcalls, theplatform/macos/Xcode host project’s entry (§17.4). The cargo-driven build keeps using the app’s ownsrc/main.rs; both paths call the same [launch], so the app behaves identically however it was built. - day_
start_ web - Expands to the
day_dom_mainC export the web host’sshim.jscalls once the wasm module is instantiated (wasm.day_dom_main()at the end ofstart()incrates/day-cli/resources/web/shim.js). - debug
- Logging (docs/logging.md).
day::info!("…")and friends are thelogcrate’s macros, re-exported so an app needs nologdependency of its own for the common case. Because they arelog’s, anything that speakslog(env_logger,tracing-log, a hand-writtenlog::Log) works without adapters. - error
- Logging (docs/logging.md).
day::info!("…")and friends are thelogcrate’s macros, re-exported so an app needs nologdependency of its own for the common case. Because they arelog’s, anything that speakslog(env_logger,tracing-log, a hand-writtenlog::Log) works without adapters. - id
- Display-synchronized, cancellable frame callbacks for any UI client. Declare an ID at its piece, including a link-time catalog entry.
- info
- Logging (docs/logging.md).
day::info!("…")and friends are thelogcrate’s macros, re-exported so an app needs nologdependency of its own for the common case. Because they arelog’s, anything that speakslog(env_logger,tracing-log, a hand-writtenlog::Log) works without adapters. - log_
enabled - Logging (docs/logging.md).
day::info!("…")and friends are thelogcrate’s macros, re-exported so an app needs nologdependency of its own for the common case. Because they arelog’s, anything that speakslog(env_logger,tracing-log, a hand-writtenlog::Log) works without adapters. - require_
lifecycle - Compile-time assert that the backend in this binary delivers
$phase, else a build error. Use it to make a hard dependency on a platform-specific phase explicit:day::require_lifecycle!(day::Lifecycle::DidEnterBackground);fails to compile on desktop. For soft handling, guard withlifecycle::supported/lifecycle_supportedinstead. - resources
- Surface the resources
day-buildgenerated for this crate aspub mod res(§18.5). - routes
- Define a plain routes enum and its
Routeimpl in one shot: - trace
- Logging (docs/logging.md).
day::info!("…")and friends are thelogcrate’s macros, re-exported so an app needs nologdependency of its own for the common case. Because they arelog’s, anything that speakslog(env_logger,tracing-log, a hand-writtenlog::Log) works without adapters. - warn
- Logging (docs/logging.md).
day::info!("…")and friends are thelogcrate’s macros, re-exported so an app needs nologdependency of its own for the common case. Because they arelog’s, anything that speakslog(env_logger,tracing-log, a hand-writtenlog::Log) works without adapters.
Structs§
- AnyPiece
- Type-erased piece for heterogeneous branches and dynamic construction.
- Application
- Application
Handlers - Asset
Dir - A bundled-asset directory (§18.5): a folder’s path relative to
resource/assets/,/-separated, no trailing slash. The generatedres::assets::…tree carries one constant per folder, sharing its module’s name:res::assets::web::minisiteis theAssetDirandres::assets::web::minisite::index_htmla file within it. - Asset
Name - The bundled-data name that
resourceresolves by: the file’s path relative toresource/assets/,/-separated (a top-level file is just its file name, extension included). - Async
Image - A growing image surface. Empty and invalid sources show the placeholder.
- Bitmap
- Raster images from bytes (docs/images.md): decode an encoded PNG or JPEG the app already
holds (a download, a file the user picked, a paste) into the platform’s image type, then
show it with
image(&bitmap)or draw it withDraw::image. - Bitmap
Id - A decoded image the toolkit holds, addressed by an id day-core mints.
- Bitmap
Info - What a decoded image is, in the terms every backend can answer
(
Toolkit::image_info, docs/images.md). - Blocking
- The blocking pool (docs/async.md):
spawn_blockingruns a job on a worker thread and resolves on the awaiting side; std-only, so it lives in day-async and is re-exported here. The futurespawn_blockingreturns: the job’s value once a pool thread has run it. - BuildCx
- Canvas
Exports - Canvas export (docs/canvas.md “Exporting”): render a recorded
Drawingto a bitmap or a PDF through the toolkit’s own painter.canvas_exports()says which of the two this target offers; the PDF writer is native on AppKit, UIKit, GTK, Qt and Android only. What this toolkit can export a canvas drawing to (Cap::CanvasBitmap,Cap::CanvasPdf). Read it to enable or hide export commands, the wayimage_encode_formatsdecides which formats to offer. - Case
- One test: what it proves, what it needs, the page it shows and the body that drives it.
Built by a
#[day::test]function each time the test runs, so the signals a page and its drive share are fresh per run; the registry names it after that function. - Catalog
- An embedded, private Fluent namespace. Generated by
day_build::generate_locales. Catalog identity is its static address, so identical keys in different crates never collide.nameis only the qualified lookup name used by scripting (crate::file::key). - Command
- An application operation shared by buttons, menus, toolbars, and direct callers
(docs/commands.md): one id, one title, one availability, one handler, presented through
button,menu_itemandtoolbar_item. - Drawing
- Canvas export (docs/canvas.md “Exporting”): render a recorded
Drawingto a bitmap or a PDF through the toolkit’s own painter.canvas_exports()says which of the two this target offers; the PDF writer is native on AppKit, UIKit, GTK, Qt and Android only. A recorded drawing at a fixed size: what a [canvas] would replay, kept for export. - Drive
- The handle a test drives the app with. Every method awaits the op and fails the test with the step’s own message when the op fails after its retry window.
- Edit
State - What the app’s edit bridge can currently do, mirrored into the toolkit
(
Toolkit::set_edit_state) so native menu validation enables the stock items.can_pasteis the app’s half (“a paste handler is installed”); the toolkit combines it with its own clipboard-has-text check where one exists. - Element
Id - Display-synchronized, cancellable frame callbacks for any UI client.
An application-owned element identity, declared with
crate::id!. - Encode
Spec - What
Toolkit::encode_imageshould produce (docs/images.md). - Fail
- A failed assertion, with the sentence the report shows.
- Font
Family - The family name of a bundled custom font, feeding
Font::custom. Holds a&'static str(soFontstaysCopy); generatedres::fonts::…constants supply it. The untypedFont::Custom(&'static str, f64)variant remains the escape hatch for a family known another way. - Image
Name - The bundled-image name that
resource()callers resolve by (the file stem). - Image
Properties - The metadata an image file carries beyond its pixels (
Toolkit::image_properties). - KeyEvent
- Launcher
Shortcut - A launcher shortcut the app sets while it runs (docs/deep-links.md “Launcher shortcuts”): a route to open and the label the launcher shows, already localized.
- Localized
Text - A localized text source:
label(tr("greeting").arg("name", name))(§12.2). - Modifiers
- The keyboard modifiers held at an interaction, queryable ambiently
(
Toolkit::modifiers):primaryis the platform’s command key (⌘ on Apple platforms, Ctrl elsewhere, the same conventionShortcut::primaryuses). Touch-only backends answer all-false. - Monitor
- One display (docs/windows.md “Monitors”), in points on the desktop’s coordinate space: top-left origin at the primary display’s top-left corner.
- Native
Ref - A liveness-checked reference to a mounted piece’s realized node: the retained half of the
tweaks API (docs/tweaks.md). Capture one with
Decorate::native_ref, then reach the native widget later (from event handlers, timers) through a toolkit ext accessor.node/withyieldNonebefore mount and after the node’s subtree is disposed, so async races are safe no-ops. - PdfDocument
- Canvas export (docs/canvas.md “Exporting”): render a recorded
Drawingto a bitmap or a PDF through the toolkit’s own painter.canvas_exports()says which of the two this target offers; the PDF writer is native on AppKit, UIKit, GTK, Qt and Android only. A PDF of one or more drawings, one per page; each page takes its drawing’s size in PDF points (1/72 inch, the same unit as canvas points: US Letter is 612 × 792, A4 595 × 842). - PdfInfo
- The document information a PDF carries. A backend whose writer has no metadata API (Android’s
PdfDocument) ignores it. - PdfPage
- One page of a PDF
Toolkit::render_pdfwrites: the page size in PDF points (1/72 inch, the same unit as canvas points) and the ops to replay onto it, origin top-left. - RNode
- Realized-node key.
NodeId(the spec-boundary id) is its FFI encoding. - Render
Bitmap - Canvas export (docs/canvas.md “Exporting”): render a recorded
Drawingto a bitmap or a PDF through the toolkit’s own painter.canvas_exports()says which of the two this target offers; the PDF writer is native on AppKit, UIKit, GTK, Qt and Android only. A bitmap render in flight. Resolves with the renderedBitmap, or why it could not be. Nothing is asked of the toolkit until the first poll. - Render
Pdf - Canvas export (docs/canvas.md “Exporting”): render a recorded
Drawingto a bitmap or a PDF through the toolkit’s own painter.canvas_exports()says which of the two this target offers; the PDF writer is native on AppKit, UIKit, GTK, Qt and Android only. A PDF render in flight. Resolves with the document’s bytes, or why they could not be produced. Nothing is asked of the toolkit until the first poll. - Resource
- A handle to a bundled resource’s bytes with efficient random read-only access.
- Status
Image - A small runtime RGBA image for a status item: charts, meters, or a grid of results.
- Task
Handle - A handle to a spawned
task.Copyand!Send(the executor is thread-local). - Text
Metrics Cache Stats - What
measure_text’s cache has done on this thread: a diagnostic, for an app that wants to see whether its drawing is measuring the same strings over and over (it usually is). - Vector
Name - The bundled-vector name that
resource()callers resolve by (docs/vectors.md): the stem of aresource/vectors/SVG (or.symbolsetbundle). Vectors and images share one per-backend resolution namespace; staging guarantees every vector name resolves as whatever form that backend loads natively (a VectorDrawable, a catalog entry, a rasterized PNG). - Window
Handle - A live secondary window (docs/windows.md). Cheap to clone; inert after close.
- Window
Image - The request built by
window_image. - Window
Options
Enums§
- AppBadge
- What to show on the app’s icon in the Dock, launcher, home screen, or taskbar (docs/badge.md).
- AppProgress
- A progress indicator on the app’s Dock or taskbar icon (
Toolkit::set_app_progress, docs/status-item.md). - Application
Error - Attention
- How strongly a window asks for the user’s attention (
WindowChange::RequestAttention). - Blocking
Error - The blocking pool (docs/async.md):
spawn_blockingruns a job on a worker thread and resolves on the awaiting side; std-only, so it lives in day-async and is re-exported here. Why aBlockingfuture resolved without its job’s value. - Date
Fields - Which parts of an instant to write. The locale decides their order, words and punctuation.
- EditOp
- A standard edit command a platform route delivered (
Event::Edit). - Export
Error - Why a canvas export could not answer (docs/canvas.md “Exporting”).
- FArg
- Handler
Query - Image
Error - Why an image operation could not answer.
- Image
Format - An encoded image format: what
BitmapInfo::formatreports andEncodeSpec::formatasks for. Not every backend encodes every one: askToolkit::encode_formats(theCap::ImageEncodepair ofToolkit::font_families/Cap::FontList) rather than assuming. - Image
Source - Where a raster image’s pixels come from (docs/images.md).
- Keep
Running - Whether the app keeps running when its last window closes (docs/windows.md “Keeping the app
running”), set with
set_keep_running. - Lifecycle
- An app-lifecycle phase (docs/lifecycle.md). Each backend maps these onto its OS’s native app /
activity delegate. Some phases only exist on some platforms (a mobile app enters the
background and can be low on memory, a desktop app cannot), so
Lifecycle::is_universalmarks the ones every backend delivers, andToolkit::supports_lifecyclereports per-backend truth. - Window
Background - What shows behind a window’s content (docs/window-chrome.md).
- Window
Chrome - The frame a window wears (docs/window-chrome.md), set once when it opens.
- Window
Kind - What a secondary window is, so backends can apply platform conventions (docs/windows.md).
- Window
Level - How a window stacks against other apps’ windows (
WindowChange::Level,Cap::WindowLevel). - Window
Material - The system materials a window background can use (
WindowBackground::Material). - Window
Placement - Where a window opens (
WindowOptions::placement). - Window
State - How a window is shown (docs/windows.md “Window properties”): what the window’s
state()signal holds and whatWindowChange::Stateasks for. - Window
Tabbing - Whether and how a window joins macOS window tabs (
WindowOptions::tabbing,Cap::WindowTabbing). Other platforms have no system window tabs and ignore it.
Constants§
- EXPORT_
MAX_ PIXELS - The most pixels a rendered bitmap may hold in total: 64 megapixels, 256 MB at four bytes a pixel, which is already more than the tightest per-app heap (Android’s) comfortably holds.
- EXPORT_
MAX_ SIDE - The largest side, in pixels, a rendered bitmap may have (docs/canvas.md “Exporting”).
day-core answers
ExportError::TooLargeabove it before any toolkit allocates.
Traits§
- Async
Image Builder - Builder methods of
AsyncImage, reachable through aDecorated(docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order. - Into
Element Key - Display-synchronized, cancellable frame callbacks for any UI client. Explicit, stable canonical text for an instance key. No blanket Display conversion. Integer 42 and text “42” intentionally denote the same key. Composite keys must define an unambiguous app-owned encoding before the framework percent-escapes it.
- IntoF
Arg - Disjoint-marker conversion for
.argvalues (the same E0119 dodge asIntoText). - Into
NumberF Arg - Marker for
IntoFArgvalues that carry a number, required for a Fluent variable used as a plural /selectselector, where CLDR plural rules select on a number (so a string can’t be passed there by mistake). Implemented for the numericIntoFArgtypes only (i64,f64, and theirSignals); the generatedres::str::<key>(…)functions (§18.5) type such parameters asimpl IntoNumberFArginstead ofimpl IntoFArg. - Piece
- A UI description consumed once (§5.2). Returns the root realized node it created.
- Piece
Seq - Children of a container (§5.1): a tuple of pieces (the floem
ViewTuplepattern), aVecor array of one piece type, or anOptionof a piece. Implemented for exactly those shapes, never via a blanket, to stay coherent. All of them are build-time children: evaluated once when the parent builds, with no keyed identity or reconciliation. A child that must come and go at runtime is awhen, akeyed, or aneach.
Functions§
- app_
temp_ dir - An app-writable scratch directory. The OS temp dir is not app-writable on every target
(Android reports
getCacheDir()), so a backend records the right location at startup and this is how an app asks for it. For derived files an app can rebuild: rendered documents, thumbnails, export staging. An app-writable scratch directory: the backend-supplied one, elsestd::env::temp_dir(). Used by the file-save flow (docs/files.md) to stage bytes before the native save picker. - application_
handlers - Query current system associations on the UI thread. macOS AppKit implements all query
kinds; other backends return
Unsupported. No application is launched by discovery. - async_
image - Decode each source asynchronously. A replacement cancels the previous decode; disposal cancels the pending task. A failed replacement clears the previous picture.
- blocking_
limit - The blocking pool (docs/async.md):
spawn_blockingruns a job on a worker thread and resolves on the awaiting side; std-only, so it lives in day-async and is re-exported here. How many threads the blocking pool may hold at once: the machine’s parallelism, at least four (a job waiting behind three slow ones still gets a thread), at most thirty-two. Zero on the web, where jobs run inline. - blocking_
threads - The blocking pool (docs/async.md):
spawn_blockingruns a job on a worker thread and resolves on the awaiting side; std-only, so it lives in day-async and is re-exported here. How many pool threads exist right now, idle ones included: for diagnostics and tests. - canvas_
exports - Canvas export (docs/canvas.md “Exporting”): render a recorded
Drawingto a bitmap or a PDF through the toolkit’s own painter.canvas_exports()says which of the two this target offers; the PDF writer is native on AppKit, UIKit, GTK, Qt and Android only. What this toolkit can export a canvas drawing to. - check_
for_ updates - Run the registered Check for Updates… command.
false= none registered. - clear_
text_ metrics_ cache - Drop every cached measurement (the counters keep running).
- compare
- Compare two strings in the current locale’s collation order. Reads the locale signal (tracked), so a sort inside a reactive closure re-runs when the locale switches.
- compare_
in - Compare two strings in
locale’s collation order (untracked; accepts-u-co-extensions, e.g."zh-u-co-stroke"). Falls back to code-point order if the locale has no collation data. - current_
window - The window the caller belongs to (docs/windows.md): the one whose content is being built
right now, else the focused window, else the app’s first window. What a piece uses to change
“its” window (
current_window()?.set_content_protected(true)) without threading a handle through.Nonebefore boot. - dark_
mode - Whether the platform is rendering in dark appearance (see
Toolkit::dark_mode): the branch apps take when painting custom opaque surfaces so fills track the theme that the default text colors already follow. - decode_
image - Raster images from bytes (docs/images.md): decode an encoded PNG or JPEG the app already
holds (a download, a file the user picked, a paste) into the platform’s image type, then
show it with
image(&bitmap)or draw it withDraw::image. - decode_
image_ async - Raster images from bytes (docs/images.md): decode an encoded PNG or JPEG the app already
holds (a download, a file the user picked, a paste) into the platform’s image type, then
show it with
image(&bitmap)or draw it withDraw::image. - default_
browser - The OS-chosen browser for HTTPS links, read afresh rather than cached by Day.
- env
- An app-environment value, portably: the process environment on native targets, the page
URL’s query string on web-dom (where a browser sandbox has no process environment;
day launch --env K=Vforwards each pair as a query parameter, docs/web.md). Prefer this overstd::env::varfor anything a--envflag should be able to set on every target. - focus_
search - Programmatic navigation on the deep-link rail (docs/deep-links.md, docs/navigation.md):
route the app to
route, buffered before the root is ready and applied after, exactly like a cold launcher shortcut. The route grammar is whatday::routes!keys and dayscript speak. Activate the focused window’s searchable navigation surface (for a Find command). - focused_
window - The most recently focused open secondary window, if any.
None⇒ the primary window is key (or no secondary window exists). - font_
families - The platform’s font families with their faces (docs/fonts.md), enumerated once per
process through
Toolkit::font_familiesand cached: the answer is stable for the process (bundled fonts register before the tree exists, and nothing tracks a system font install under a running app; the OS font panels cache too), enumeration is expensive, and the query is synchronous on the UI thread. Sorted case-insensitively by family, deduplicated, and unioned with the bundled fonts (day_spec::fonts::bundled_fonts) the toolkit’s own database did not report, which is how ares/font/(Android),ms-appx(XAML) orregisterFont(HarmonyOS) family reaches a font menu without each shim parsing sfnt. Empty where the toolkit answersCap::FontList=Unsupported. - format_
catalog - Format within one private namespace; missing keys fall back only to this catalog’s default. App/core catalogs cannot accidentally supply a similarly named key from another component.
- format_
date format_date_inin the current locale (tracked, likecrate::format_decimal), so a label inside a reactive closure re-renders when the locale switches.- format_
date_ in - Write the instant
epoch_seconds(seconds since 1970-01-01T00:00:00Z, read as UTC civil time, the convention of the FluentDATETIME()builtin and of chart time axes) inlocale, showingfields(untracked). - format_
decimal - Render
vin the current locale (tracked, likecrate::compare), so a label inside a reactive closure re-renders when the locale switches. - format_
decimal_ in - Render
vinlocale, rounded tofraction_digitsand grouped by that locale’s own rule (untracked).1234.5is1,234.5inen,1 234,5infr,1.234,5inde. - format_
percent format_percent_inin the current locale (tracked), so a label inside a reactive closure re-renders when the locale switches.- format_
percent_ in - Render the fraction
vas a percentage inlocale(0.5is50%inen,50 %infr,%50intr), rounded tofraction_digitsplaces of the percentage and grouped by the locale’s rule (untracked). - image_
decode_ support - Raster images from bytes (docs/images.md): decode an encoded PNG or JPEG the app already
holds (a download, a file the user picked, a paste) into the platform’s image type, then
show it with
image(&bitmap)or draw it withDraw::image. - image_
encode_ formats - Raster images from bytes (docs/images.md): decode an encoded PNG or JPEG the app already
holds (a download, a file the user picked, a paste) into the platform’s image type, then
show it with
image(&bitmap)or draw it withDraw::image. - image_
encode_ support - Raster images from bytes (docs/images.md): decode an encoded PNG or JPEG the app already
holds (a download, a file the user picked, a paste) into the platform’s image type, then
show it with
image(&bitmap)or draw it withDraw::image. - initial_
window - A handle to the app’s first window, once adopted.
Nonebefore boot completes, and after that window closes; it is an ordinary window and can be closed like any other. - install_
edit_ bridge - Wire the app’s standard-edit handlers to the platform (docs/menus.md):
stateis a tracked read whose value mirrors into the toolkit (Cap::EditBridge: native menu validation enables the stock Cut/Copy/Paste exactly as it does for text widgets), and every invocation a platform route delivers comes back throughon_invoke. On a toolkit with no native route, themenu_role(Cut/Copy/Paste)items dispatch here instead (the same standing-id fallback the undo pair uses). Call once, after launch; installing again replaces the wiring. Most apps wantday::install_edit_commands, which adds the clipboard transport. - install_
edit_ commands - Wire the app’s shape/object Cut/Copy/Paste to the platform’s own edit commands
(docs/menus.md): the same menu items, shortcuts, and responder precedence text editing
uses. A focused text field keeps its clipboard behavior; everything else reaches these
handlers.
can_copyis a tracked read (drive it from your selection);copy/cutreturn the serialized payload (its format is the app’s: Day-Sketch uses SVG), which day places on the system clipboard;pastereceives the text the clipboard holds, falling back to the payload this app last placed there when the platform answers nothing (docs/menus.md). Menu items come frommenu_role(MenuRole::Cut/Copy/Paste). - install_
locales - Register the app’s locales (see
day_localization::install) and fix the layout direction from the locale that actually resolved (docs/localization): an RTL locale (Arabic, Hebrew, …) mirrors every horizontal placement and flips the native toolkit’s direction. Direction is resolved once, before the first layout; runtimeset_localeswitches strings but not direction. - invalidate_
size - Tell layout that a node’s intrinsic size may have changed. For tweaks (docs/tweaks.md): after a native call that alters a widget’s preferred size (fonts, tick marks, bezel styles), the measure cache along the node’s path must be invalidated, since Day can’t see native mutations it didn’t make. Relayout runs at the next turn boundary as usual. No-op on a disposed node.
- invoke_
edit - Invoke the installed edit bridge (the same handler the platform’s Cut/Copy/Paste route reaches, clipboard transport included), returning whether one is installed. An app’s own affordances (a context menu’s Cut/Copy) call this rather than duplicating the clipboard plumbing (docs/menus.md).
- launch_
external - Launch through an external toolkit’s backend (docs/extending.md “External toolkits”): the
cfg-free counterpart of the feature-gated
launchentries below, for platform-toolkit pairs registered via[package.metadata.day.toolkit]. Feature-independent becauseday build -t <external>compiles the app with only the external toolkit’s feature, so none of the launchers below exist in that build. Starts the dayscript engine exactly as they do, which is what keepsday launch --script,day drive, and the session registry working on a backend this repository has never heard of. - lifecycle_
supported - Does the running backend deliver
phase? Use this to guard registration at runtime:if day::lifecycle_supported(Lifecycle::DidEnterBackground) { on_lifecycle(...) }. - locale
- The current locale (a tracked read inside bindings).
- matches_
search matches_search_inagainst the current locale. Reads the locale signal (tracked), so a filtered list inside a reactive closure re-filters when the language changes, the same contractcrate::comparehas.- matches_
search_ in - Whether
textmatchesqueryunderlocale’s rules (untracked: pass the locale explicitly). - measure_
text - Measure one line of canvas text at
sizepoints infont(docs/fonts.md), in the engine that drawsDrawOp::Text; a toolkit that cannot measure answersTextMetrics::approximate, so a caller always gets a usable box. - modifiers
- The keyboard modifiers held right now, for interactions whose meaning they change (shift-click adds to a selection instead of replacing it). Touch platforms answer all-false; a dayscript step’s declared modifiers take precedence while it dispatches.
- monitors
- The displays attached now (docs/windows.md “Monitors”). A toolkit that cannot list them
(
Cap::Monitorsunsupported) answers with one display the size of the primary window, so a placement computed from the answer stays on screen. - on_
lifecycle - Register
fto run whenever the app reachesphase. Handlers run in registration order, in a reactive batch (signal writes coalesce into one UI update). Register early (beforelaunch, or at the top of the root builder) soWillLaunch/DidLaunchhandlers are in place when they fire. - on_
open_ files - Receive local document activations from the operating system. See docs/documents.md. Install the application’s file-open handler. Called on the UI thread; pending cold-start activations are delivered on the next UI turn. Register once in the application root.
- on_
open_ url - Receive local document activations from the operating system. See docs/documents.md. Register on the UI thread. Return true to consume a URL; false retains normal deep-link routing. Delivery never performs a privileged action.
- open_
about - Run the registered About action (docs/settings.md): the menu item’s dispatch, and what a
toolbar button or a settings row calls.
false= nothing registered (logged). - open_
new_ window - Open a window through the registered new-window builder (the
newWindowForTab:/ File ▸ New Window path).None= no builder registered. - open_
preferences - Open-or-focus the preferences surface (docs/windows.md): a
WindowKind::Preferencessingleton window on desktop, the cover fallback elsewhere: one call for menu items and toolbar gears alike.false= no preferences piece is registered (logged). - open_
url_ with_ application - Open a URL or file URL in a chosen application. Await on the UI executor. Success means the OS accepted the open request; tab/window presentation belongs to the receiving app.
- open_
window - Open a secondary window (docs/windows.md):
open_window(res::window_options().key("city").size(…), build).options.keynames the logical window: when a window with this key is already open it is focused and returned instead of duplicated (the preferences pattern); no key always opens a new one.options.kindsays whether it is a regular window or a preferences/About panel. Where the toolkit cannot open windows (Cap::MultiWindow=Unsupported; probe it to adapt chrome) the content presents as a fullscreen cover in the primary window instead, closable the same way. - pager
- play_
script - Replay a dayscript against the running app, in-process (docs/dayscript.md “Recording”): parse
yamland run each step through the embedded engine, on the main thread between flushes, the same executorday launch --scriptdrives. Returns an error while a recording is live (a replay must not record itself) and on web (no background thread; drive the page over the WebSocket transport there). Seerecord. - quit
- End the app now (docs/windows.md “Keeping the app running”): the Quit item of a status
item’s menu, a background helper’s own decision. Every window is disposed and
Lifecycle::WillTerminatedelivered first, as when the last window closes. - reduce_
motion - Whether motion should be reduced (docs/accessibility.md): the user’s system setting
(
Toolkit::reduce_motion), or a launch that forced it (DAY_REDUCE_MOTION=1, andday launch --fast, whose fast mode is this setting forced on). Day already applies every finite animation at its destination under it and keeps only indeterminate motion; this read is for the motion an app drives itself, such as aday::framesimulation or a decorative loop, which the app opts down. Reactive: a closure reading it re-runs when the setting flips. - register_
about - Declare what the app’s About command does (docs/settings.md): once, in
root(). Enables the About menu item everywhere a desktop has one (the macOS App menu, Help elsewhere; both the default menu and an installedapp_menu) andopen_about. The action is the whole contract, so a toolkit-native About dialog (libadwaita’s) and a Day window (register_about_window) register the same way. - register_
about_ window register_aboutwith a Day-rendered About window: opened under the singleton keyABOUT_KEYas aWindowKind::Aboutpanel (fixed, centered, out of the Window menu), the cover fallback where the toolkit cannot open windows. The window titles itself withoptions.title.- register_
catalog - Make a catalog available for qualified scripting lookups. Generated accessors call this automatically. Registration never changes the app locale or its default catalog.
- register_
check_ for_ updates - Declare the updater’s Check for Updates… command (docs/settings.md): the item appears
under About in the macOS App menu and in Help elsewhere, and
MenuRole::CheckForUpdatesitems lower to it. Registered by an update provider, not by the app. - register_
new_ window - Register the builder behind File ▸ New Window and the macOS tab-bar “+” (docs/windows.md):
each call opens another
WindowKind::Normalwindow. Amenu_role(MenuRole::NewWindow)item lowers to this action; without a registration it lowers disabled. - register_
new_ window_ for - Register the builder behind the macOS tab bar’s “+” for windows whose
WindowOptions::tabbingnamesgroup(docs/windows.md): each call opens another window of that group, as a tab of the window the user clicked “+” in. Groups without a registration fall back toregister_new_window’s builder. - register_
preferences - Declare the app’s preferences piece (docs/windows.md): once, in
root(), ideally beforeapp_menu. Enables the desktop Preferences window (singleton, primary+,), the auto Settings…/Preferences menu item, andopen_preferenceseverywhere (cover fallback where the toolkit cannot open windows). The window titles itself withoptions.title; useregister_preferences_withto localize it or change the size. - register_
preferences_ with register_preferenceswith explicit window options (localized title, size).- request_
route - Programmatic navigation on the deep-link rail (docs/deep-links.md, docs/navigation.md):
route the app to
route, buffered before the root is ready and applied after, exactly like a cold launcher shortcut. The route grammar is whatday::routes!keys and dayscript speak. Ask the app to navigate, from anywhere, at any time. - resource
- Open a bundled resource by name for efficient random read-only access.
- safe_
area - The window’s safe-area insets, in points. Zero on every backend that clamps Day’s root to
the safe area natively (the default everywhere); nonzero only where a backend runs the root
edge-to-edge, today day-toolkit-material’s opt-in immersive mode (docs/layout.md, the android
platform page). Compose it yourself where a background should run under the system bars:
paint the background unpadded, pad the content by these insets. The read is tracked, but
layout attributes like
.paddingcapture the value at build time, so a mid-run inset change (rotation) does not re-pad already-built pages. - set_
app_ badge - Put a badge on the app’s icon: the Dock, launcher, home screen, or taskbar (docs/badge.md).
- set_
app_ progress - Show
progresson the app’s Dock or taskbar icon (Cap::AppProgress, docs/status-item.md). - set_
appearance - Override the app’s appearance:
Some(true)dark,Some(false)light,Nonefollow the system again. On backends reportingCap::Appearancethe native widgets restyle in place anddark_modeanswers the override; app-painted surfaces pick it up on their next rebuild. Other backends ignore the call; probe before offering a theme picker. - set_
dock_ visible - Show or hide the app’s Dock icon while it runs (
Cap::DockVisibility, macOS). A menu-bar app hides it and lives in its status item;[app.macos] dock = falsein Day.toml hides it from launch, before the first frame. - set_
keep_ running - Choose whether the app keeps running when its last window closes (docs/windows.md).
- set_
launcher_ shortcuts - Replace the launcher shortcuts the app sets while it runs (docs/deep-links.md “Launcher
shortcuts”):
Resume <last document>, the three most recent chats. They show beside the Day.toml[[shortcuts]]on the iOS Home Screen, the Android launcher and the macOS Dock menu (Cap::DynamicShortcuts), and each opens its route like a deep link. Labels are shown as given, so pass localized text. - set_
log_ level - Raise or lower the level Day’s default logger emits, at runtime.
DAY_LOGsets it at startup on native targets; the web launch path reads?DAY_LOG=from the page URL. Set the maximum level that will be emitted. Separate frominit_loggingbecause the web launch path has to supply the level from the page URL rather than the environment, and because an app may want to raise or lower it at runtime. - share_
support - Whether the current toolkit can present a native sharing chooser.
- share_
url - Present a native chooser for a URL. Call directly from user activation (required on web). Returns false if unavailable or presentation failed; cancellation is not an error and no completion is implied. The caller owns any explicitly labeled fallback.
- size_
class - The current window’s size class, or
Noneon a backend that does not report one yet. Tracked: a piece that lays out from this rebuilds when the window crosses a breakpoint. - sleep
- Resolve after (at least)
msmilliseconds, on the UI thread: the portable delay forday::taskflows (docs/async.md). RidesPlatform::post_delayed, so it works on single-threaded hosts (web) wherestd::thread::sleep+Settercannot. - sort_
localized - Sort a slice in place in the current locale’s collation order (tracked, like
compare). - spawn_
blocking - The blocking pool (docs/async.md):
spawn_blockingruns a job on a worker thread and resolves on the awaiting side; std-only, so it lives in day-async and is re-exported here. Runjobon a pool thread and resolve to its value on the awaiting side. - stepper
stepper(value): a numeric field with increment/decrement arrows.valueis aSignal<f64>, a day-modelField, or any other two-way binding; a step click commits one unit through it (write_commit), so under an undo stack each click is one undoable step.- task
- Spawn an async flow onto Day’s main-loop executor. This is the opt-in entry point for actions
that open modals or pickers:
button.action(|| day::task(async move { … .await … })). The future is polled once before this returns; the returned handle canTaskHandle::abortit and is freely discardable. At app termination pending tasks are dropped while reactive state is still available. Tasks submitted after shutdown begins are dropped without being polled. - test_
host - The root of an app’s test build: the app’s content, or the driven case’s page alone.
The root of an app’s test build:
contentnormally, and whileday testdrives a GUI case, that case’s page alone, built fresh for the case and disposed when the next one starts. One page mounted at a time is what keeps one case’s ids, signals and resident native views out of the next one’s way. - text_
metrics_ cache_ stats - Read the
measure_textcache’s counters (docs/fonts.md). - toolkit_
name - The display name of the toolkit compiled into this binary:
"AppKit","GTK","Qt","UIKit","Material Components","XAML","WinUI","ArkUI","DOM"(or"Mock"). Handy for a window title that names its backend. - tr
- tr_in
- Bind a key to a private crate/file catalog. Prefer generated typed accessors.
- window_
by_ key - The open window registered under
key, if any (the dayscriptscreenshotstep’swindow:target resolves here). Native windows being closed are excluded; a dismissing fallback cover remains available so reopening its key can reverse the transition. - window_
image - A PNG of this window, as the app itself sees it (docs/window-image.md).
- window_
image_ support - Whether this toolkit can hand the app a picture of its own window (
Cap::Snapshot). - window_
title - Bind the title of the window this piece is building into to a reactive closure (docs/windows.md). This is how a window comes to be named after what it shows.
Type Aliases§
- Test
Result - What a test’s body answers.
Attribute Macros§
- builder
#[day::builder(FooBuilder)]: a piece’s builder trait, generated from its inherent impl (docs/api-style.md “Typed builders and erasure”). A piece’s builder trait, generated from the inherentimplthat holds its builder methods (docs/api-style.md “Typed builders and erasure”).- test
- Mark a function that builds a
Caseas a Day test (docs/testing.md): the function stays as written, and a link-time registry entry is added beside it soday testand the mock harness find it. The test is named after the function, with hyphens for underscores:button_statusruns asbutton-status.