Module windows 

Secondary windows (docs/windows.md): the app-facing open_window API, the per-window registry, and the fallback that presents window content as a fullscreen cover where the toolkit cannot open windows (Cap::MultiWindow = Unsupported).

Windows live in the one thread-local tree as additional boundary roots (the same “wrap an externally-owned handle” record as the primary root and the list cell anchors), so bindings, find_by_id, and dayscript work across windows unchanged. Close is asynchronous everywhere: the platform (or the cover’s hide transition) confirms, and teardown runs then: one path for native and programmatic closes.

Structs

WindowHandle

A live secondary window (docs/windows.md). Cheap to clone; inert after close.

Constants

ABOUT_KEY

The singleton key the About window opens under.

PREFERENCES_KEY

The singleton key every preferences window opens under.

Functions

about_action_id

The dispatch id of the About menu action (0 = unregistered). Backends wire their stock About item to it; MenuRole::About lowering and the injection pass use it.

adopt_initial_window

Adopt the app’s first window into the registry, so it is an ordinary primary window rather than a privileged one (docs/windows.md close policy).

check_for_updates

Run the registered Check for Updates… command. false = none registered.

check_for_updates_action_id

The dispatch id of the Check for Updates… action (0 = unregistered).

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. None before boot.

finish_window_open

Backend-facing: complete a Pending window open (docs/windows.md). id is the node the backend’s open_window received; raw is the new window’s content container; size its content size in points. false ⇒ the window was closed before completion, and the backend should drop the native window it just created.

focused_scope

The scope owning the content of the window that currently has focus: the scope an app-wide command should resolve per-window state through (docs/state.md).

focused_window

The most recently focused open secondary window, if any. None ⇒ the primary window is key (or no secondary window exists).

group_windows

Explicit grouping, independent of the user’s automatic-tabbing preference.

initial_window

A handle to the app’s first window, once adopted. None before boot completes, and after that window closes; it is an ordinary window and can be closed like any other.

launch_options

What the app handed launch (title, app name, version), for surfaces that describe the app (an About page). None before launch.

monitors

The displays attached now (docs/windows.md “Monitors”). A toolkit that cannot list them (Cap::Monitors unsupported) answers with one display the size of the primary window, so a placement computed from the answer stays on screen.

native_close_requested

Native close delegate hook. Queue document code outside the toolkit callback. Returns false when the owner will decide whether to close.

native_window_tabs

Whether this backend can group actual OS windows as tabs.

new_window_action_id

The dispatch id of the New Window action (0 = unregistered), used by MenuRole::NewWindow lowering and the backends’ tab-bar “+” wiring.

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_new_window_for_group

Open another window of tab group group (the backend’s newWindowForTab: path for a window whose tabbing names a group). Uses the group’s registered builder, else the app’s New Window builder; None when neither exists.

open_preferences

Open-or-focus the preferences surface (docs/windows.md): a WindowKind::Preferences singleton window on desktop, the cover fallback elsewhere: one call for menu items and toolbar gears alike. false = no preferences piece is registered (logged).

open_window

Open a secondary window (docs/windows.md): open_window(res::window_options().key("city").size(…), build). options.key names 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.kind says 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.

open_window_count

Test/diagnostic surface: the number of open secondary windows.

preferences_action_id

The dispatch id of the auto Preferences menu action (0 = unregistered). Backends use it to wire their default-menu Settings item; the injection pass uses it for app_menu.

primary_window_count

How many non-closing primary windows keep the app alive (docs/windows.md close policy). This includes the initial window while it remains registered and open.

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::WillTerminate delivered first, as when the last window closes.

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 installed app_menu) and open_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_about with a Day-rendered About window: opened under the singleton key ABOUT_KEY as a WindowKind::About panel (fixed, centered, out of the Window menu), the cover fallback where the toolkit cannot open windows. The window titles itself with options.title.

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::CheckForUpdates items 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::Normal window. A menu_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::tabbing names group (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 to register_new_window’s builder.

register_preferences

Declare the app’s preferences piece (docs/windows.md): once, in root(), ideally before app_menu. Enables the desktop Preferences window (singleton, primary+,), the auto Settings…/Preferences menu item, and open_preferences everywhere (cover fallback where the toolkit cannot open windows). The window titles itself with options.title; use register_preferences_with to localize it or change the size.

register_preferences_with

register_preferences with explicit window options (localized title, size).

register_tab_new

Route the native group add button to a document collection rather than a window builder. Registration belongs to the current scope.

reset_windows

Reset the registry + registrations (tests; pairs with uninstall_tree).

set_launch_options

Record what the app handed launch, for open_new_window to inherit. Called once by launch_with with the options it is about to open the primary window with, already title-decorated, which is idempotent (tag_title).

window_by_key

The open window registered under key, if any (the dayscript screenshot step’s window: target resolves here). Native windows being closed are excluded; a dismissing fallback cover remains available so reopening its key can reverse the transition.

window_kind_of

The WindowKind of the open window at root, for backends and tests.

window_node_id

The window root’s spec-boundary id (backends key their per-window maps by it).

window_root_by_key

The tree root of the window registered under key: day-script’s snapshot target.

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.