Windows (WinUI 3)

Tier 2 · Demi-supported

Day’s Windows target presents shared Rust UI code through WinUI 3 controls. This reference covers the Windows build tools, runtime requirements, and packaging needed for the app.

windows-winui is a Tier 2 target using the Windows App SDK. Its controls use the Fluent styles of Windows 11.

Getting started

You need the Visual Studio C++ Build Tools (for MSVC and the Windows SDK) and the MSVC Rust toolchain. The C++/WinRT shim is compiled by build.rs against the Windows SDK, whose cppwinrt.exe also generates the WinUI projection.

rustup default stable-msvc
cargo install --git https://github.com/daybrite/day day-cli
day new app my-app --toolkit windows-winui
cd my-app
day launch -t windows-winui

The app’s Cargo.toml carries a winui = ["day/winui"] feature, which the day new template adds.

Development builds (day build, day launch) run framework-dependent, so they need the Windows App Runtime 2.5.1 or newer installed (the Microsoft.WindowsAppRuntime.2 framework package), from Microsoft’s Windows App SDK downloads. If it is missing, the app offers that download page at start-up. day doctor --toolkit winui checks the MSVC toolchain and the runtime.

There is no NuGet or Visual Studio project. On first use the build downloads the Windows App SDK’s NuGet packages itself (about 270 MB, with the in-box curl and tar) into %LOCALAPPDATA%\day\winappsdk. DAY_WINAPPSDK points the build at an already laid-out copy for an offline machine; DAY_WINAPPSDK_CACHE moves the cache.

To run the same codebase against GTK or Qt on a Windows machine, see Qt and GTK on a Windows host.

Canvas graphics

Canvas elements use Microsoft’s Win2D drawing API. Screen drawing and offscreen bitmap export share the same renderer, including paths, geometric clipping, gradients, transformed images and bundled fonts. Drawing::to_png(scale) supports transparent PNG export; vector PDF export is not yet supported.

Day automatically fetches the pinned Microsoft.Graphics.Win2D package with the other SDK inputs. Packed apps include its native DLL, so users do not install Win2D separately.

Packing

day pack -t windows-winui     # .msix plus an NSIS -setup.exe

This writes <app>-windows-winui.msix and <app>-windows-winui-setup.exe. The installer needs NSIS (makensis, e.g. choco install nsis).

A packed app is self-contained: the Windows App SDK runtime DLLs, a merged resources.pri, and a registration-free WinRT manifest travel inside the .msix and the installer, so users install nothing extra. They need Windows 10 version 1809 or later (Windows 11 recommended). Only day pack links this way; day build and day launch stay framework-dependent.

The NSIS installer is per-user: it runs without elevation, adds a normal Add/Remove Programs entry, and offers a silent /S mode for managed deployment. The Microsoft Store rules that day store applies ([microsoft-store] in store-rules.toml) cover this target.

Caveats

  • Fewer applications have shipped on it than on the Apple, Linux, and Android targets. Day-Showcase’s full UI walkthrough passes on it, but no large app ships on it yet.
  • The web view needs the Microsoft Edge WebView2 Runtime, which ships with Windows 11 and current Windows 10. Day uses WinUI 3’s own WebView2 control.
  • picker().segmented() is a horizontal row of radio buttons, since WinUI has no native segmented control.
  • The inline time picker falls back to a flyout, because WinUI has no inline clock.
  • Text-area read-only and spell-check are native (TextBox.IsReadOnly / IsSpellCheckEnabled). .selectable(false) is emulated, because TextBox has no selection-enable property: the shim collapses each selection as it is reported and suppresses the context menu.
  • Lottie plays through lottie-web in the web view. Map has no WinUI arm and renders its placeholder. cover() presents as a topmost window-sized child (no transition, programmatic dismissal only).
  • Screenshots read the window’s real pixels, frame included, through Windows.Graphics.Capture, so they show web view and video content and work while the window is covered.
  • dayscript gates: use only_on: [windows-winui] or skip_on: [windows-winui] to include or exclude a step on this target.

Native pieces

A native piece enables WinUI through a winui feature that implies the piece’s xaml feature and turns on both day-toolkit-winui/winui and day-toolkit-xaml-sys/winui, with "winui" in [package.metadata.day.piece] backends. Its build.rs uses day_toolchain::winappsdk::shim_includes(&cppwinrt) and defines DAY_WINUI when day_toolchain::winappsdk::shim_is_winui(), and the shim switches its includes and namespace on DAY_WINUI. day new piece --toolkits winui scaffolds this; the native piece tutorial walks through it.

What each piece becomes

The generated coverage matrix, checked in CI, covers every toolkit; this table adds links and notes.

Day pieceWinUI 3 control (Microsoft.UI.Xaml.Controls)
column / row / nav_stack / sectionCanvas (Day positions children absolutely)
labelTextBlock
buttonButton (AccentButtonStyle when prominent)
toggleToggleSwitch
sliderSlider
text_fieldTextBox
secure_fieldPasswordBox
text_areaTextBox with AcceptsReturn
picker().menu()ComboBox
picker().segmented() / .inline()RadioButtons in a horizontal / vertical stack
progress(f)ProgressBar
spinner()ProgressRing
dividerBorder, 1px, themed stroke
scrollScrollViewer
listScrollViewer with Day-side cell pooling
nav (split and stack)NavigationView
nav_menuNavigationViewItems, or a ListView standalone
tabsPivot
imageImage
vectora Path in a scaling Viewbox (XAML geometry); an Image of the raster cache PNG for art outside the convertible subset
canvasCanvas with a Path per shape
dialogs / alerts / promptsContentDialog
file dialogsFileOpenPicker / FileSavePicker
menu barMenuBar
context menusMenuFlyout
external spinner()ProgressRing
external combobox()editable ComboBox
external search_field()AutoSuggestBox
external date_picker()CalendarDatePicker, or CalendarView inline
external time_picker()TimePicker
external media()MediaPlayerElement
external webview()WebView2

Text measurement is WinUI’s measure pass (Measure → DesiredSize), with a re-measure after forcing layout when a templated control reports zero before the first async layout pass.

Qt and GTK on a Windows host

windows-winui is the target you ship on Windows. To check a change against GTK or Qt on the same machine, build linux-gtk or linux-qt inside WSL 2, with the Linux packages from system requirements installed in the WSL distribution. On Windows 11, WSL shows Linux apps’ windows on the Windows desktop.