Recipes hub (2.46 v2)¶
LoB how-tos for shipping with QWinUI3. Prefer these over inventing a second stack. Generated control pages live under Component API. Gallery: last pane group Recipes → Recipes hub (also motion, a11y, system, media how-tos).
Docs IA v2 (2.46): docs-ia-v2.md — MkDocs Planning + Recipes regroup; this hub mirrors Gallery rows.
Planning & product expansion¶
| Doc | One-liner |
|---|---|
| Planning hub | Friction gate + expansion tracks (2.51→3.00) |
| Friction log | Open P0/P1 rows — post-2.50 gate |
| Roadmap strategy | Phases through 3.00 |
| Charts & dashboard arc | New types + stable six deepen |
| Component capabilities | All modules — existing control API deepen |
| Icons & dashboard | KPI / ChartCard symbols |
2.xx developer & stability¶
| Recipe | One-liner |
|---|---|
| Tranche-1 perf sign-off (2.49) | FL-008 partial — 2.x wave 5→8 summary |
| Stable vs experimental clarity (2.51) | FL-004 queue closed — lint_qml_imports.py + Pitfalls |
| First app in an hour (2.52) | examples/first-app/ + preview DashboardShell |
| Linux top-3 parity (2.53) | Nav shell clip + sway profile + FilePicker guard |
| Files on Linux (2.57) | Portal parent fallback + reveal + drop reject UX |
| Navigation mental model (2.56) | Back vs pane vs stack guardrails |
| Forms unlike WinUI (2.55) | Async validate + dialog queue priority |
| Window chrome footguns (2.54) | Geometry v2 + maximize hit-test refresh |
| Field harden buffer (2.47) | Checkpoint P0/P1 triage — packaging picker + import guard |
| Docs IA v2 | MkDocs + hub regroup for 2.xx docs (2.46) |
| Developer diagnostics | FrameStats dev vs retail · --retail-diagnostics (2.44) |
| Experimental sweep | FL-004 verdict matrix + Gallery badges (2.45) |
2.xx controls & Gallery¶
| Recipe | One-liner |
|---|---|
| Dashboard compose decision (2.48) | FL-009 — deferred chart → stable six tree |
| Gallery catalog expansion | 2.21…2.38 findability matrix (2.39) |
| Calendar view | Experimental month grid (2.31) |
| Items wrap grid | Experimental wrap layout (2.24) |
| Style polish | Spot-check + polish notes (2.32) |
| Multi-window onboarding | Second-window recipe (2.14 harden) |
Stable API: prefer types on stable-api.md. 1.xx freeze: compatibility-1xx.md · upgrade-notes.md.
Start building¶
| Recipe | One-liner |
|---|---|
| Qt Creator | Open root CMakeLists → Gallery or example (no .pro) |
| Consumer packaging | Shared vs static / windeploy / strip (1.46) · find_package (1.61) |
| Python / PySide6 / PyQt6 | python scripts/qwinui3.py python — Gallery + shared kit (2.64) |
| vcpkg / Conan | Overlay port + Conan 2 recipe (2.11) |
| 1.xx compatibility | Will-not-break Theme / shells / stable controls (1.40 / 1.51) |
| 1.xx maturity checkpoint | Where we are; harden-first posture (1.51) |
| Upgrade notes | Consumer checklist + template (1.40) |
| Qt version compat | 6.5+ / 6.8 LTS / CI matrix |
| Conventions | Radius, Accessible, Extras import |
App shells & chrome¶
| Recipe | One-liner |
|---|---|
| Window shells | ShellWindow vs StandardWindow · multi-window (1.56 · 2.14 harden) |
| Window chrome | DPI / backdrop / geometry failure modes |
| High-DPI & multi-monitor | DPR matrix · geometry clamp + setScreen (1.58) |
| WindowHelper | Geometry persistence, backdrop, platform APIs |
| AppWindow | Presenters / title-bar height |
| Linux / Wayland | CSD, Solid, portals, field matrix (1.38 / 1.68 / 1.79) |
| Graphics backend | RHI ship table · OpenGL for frost |
| Transparency / DWM | Gallery Solid policy · Mica notes |
Navigation, forms, data¶
| Recipe | One-liner |
|---|---|
| Navigation & TabView | Pane modes, Back, footer |
| Carousel / FlipView | PipsPager + SwipeView hosts · reducedMotion (2.37) |
| Forms & settings | FormLayout validation + SettingsCard |
| Appearance variants | Button / input appearances + DataTable pro grid (2.66) |
| Settings persistence | QSettings / Settings · portable Ini · schemaVersion (1.65) |
| Data collections | DataTable / ItemsView / ListDetailsView |
| Tree & hierarchical | TreeView expand / a11y |
| Input & pickers | Number / date / time / color |
| Density & responsive | Compact metrics, narrow shells |
| Touch, pen & pointer | Targets · scroll vs drag · pen notes (1.57) |
| Adaptive layout | TwoPaneView / ListDetailsView breakpoints (1.42) |
| Theme overrides | Accent / density / branding · copy recipe (1.69) · wave 2 packs + ThemePrefs (2.38) |
| Color & contrast | AA diagnostics / high contrast (1.43) |
| Icons & FluentIcons | Symbol font + micro-motion + AnimatedIcon (1.53) |
| i18n / RTL | qsTr + seed locales + LayoutMirroring · consumer lrelease (2.12) |
Feedback, dialogs, commands¶
| Recipe | One-liner |
|---|---|
| Feedback surfaces | InfoBar / Toast / TeachingTip / onboarding coach / Progress |
| Dialogs & flyouts | ContentDialogQueue FIFO / Esc (1.48) |
| Commands & menus | CommandPalette / CommandBar / MenuFlyout |
| Keyboard-first | Global chords → palette → dialogs → lists (1.44) |
| On-screen keyboard | Floating Win11 OSK + Windows system-wide (1.83 harden); still experimental |
| In-app search & AutoSuggest | Suggest · filter-above · catalog jump (1.59) |
| Accessibility | Focus return / live regions (1.85); names checklist |
Platform & media¶
| Recipe | One-liner |
|---|---|
| System integration | FilePicker / Tray / NotificationBridge (1.68 / 1.79 portal) |
| Print, share & export | grabToImage · save · reveal · PrintSupport notes (1.63) |
| Security & trust | WebView2 / drop / picker / path trust · wave 2 (2.13) · wave 3 (2.36) |
| Drag-drop & clipboard | FileDropZone / CopyButton / WindowHelper (1.41) |
| Shell extras | Snap / taskbar / attention / reveal (1.47) |
| WebView2 | Stable Edge host (Windows) |
| Media | Optional Multimedia — permanent defer 2.09 |
| Charts & gauges | Stable six + deferred remaining (1.66) |
| Animations | ConnectedAnimation / reducedMotion |
| Carousel | FlipView / PipsPager hosts (2.37) |
| Performance | Lists, models, chart budgets, Gallery cold start (1.39) |
Quality¶
| Recipe | One-liner |
|---|---|
| Gallery CatalogPage | Page host slots (Item not Page) |
| Collection perf (2.64) | DataTable pin/group · ListDetailsView bulk toolbar |
| Notification center (2.63) | Toast + history NotificationBridge stack |
| Semantic zoom (2.62) | Contacts SemanticZoom (experimental) |
| Rich edit (2.61) | Mail / template RichEdit (experimental) |
| 3.xx compatibility (draft) | Breaking close-out notes |
Examples (in repo)¶
| Example | Recipe pair |
|---|---|
examples/gallery-shell |
window-shells.md / navigation.md (1.50) |
examples/multi-window |
window-shells.md multi-window (1.56) |
examples/nav-settings |
navigation.md |
examples/settings-cards |
forms.md / theme |
examples/dashboard |
charts.md (1.66 stable six) |
examples/master-detail |
data-collections.md |
examples/form-settings |
forms.md |
examples/floating-osk |
on-screen-keyboard.md (1.84) |
Build from Creator or presets: qt-creator.md · examples/README.md.
Product app presets (Light Photos / LoB)¶
From product-integration.md — common traps when shipping beyond Gallery demos.
CommandBar (viewer / product toolbar)¶
| Property | Gallery / advanced | Product preset |
|---|---|---|
compact |
true or Theme compact |
false |
isDynamicOverflowEnabled |
varies | true |
isToggleButtonVisible |
false hides chevron |
true |
defaultLabelPosition |
"collapsed" |
"bottom" |
CommandBar {
compact: false
isDynamicOverflowEnabled: true
isToggleButtonVisible: true
defaultLabelPosition: "bottom"
AppBarButton { text: qsTr("Share"); symbol: FluentIcons.Share }
}
MenuFlyout (long / context menus)¶
| Issue | Fix |
|---|---|
| Scroll jumps to top | Snapshot dynamic counts in onAboutToShow; avoid live selectedCount bindings while open |
| Grid right-click | popupAtGlobal(Overlay.overlay, mouse.x, mouse.y) — not only showAt(item) |
| Tall menu | contentMaxHeight: 480 |
MenuFlyout {
id: ctx
contentMaxHeight: 480
onAboutToShow: snapshotSelection()
}
// Grid MouseArea.onClicked: ctx.popupAtGlobal(Overlay.overlay, mouse.x, mouse.y)
IconButton accent icons¶
Use accentIcon: true (alias of highlighted) for rating stars / favorited glyphs — not iconColor (does not exist).