Consumer upgrade notes (1.40)¶
How to move a product app between QWinUI3 1.xx minors without surprises.
Compatibility contract: compatibility-1xx.md.
Stable types: stable-api.md.
Qt floors: qt-version-compat.md.
Template (copy per release)¶
Use this block when you ship a tagged vX.YY that consumers must react to. Skip rows that are N/A.
## Upgrade X.YY → X.ZZ
**Product version:** X.ZZ (`QWINUI3_VERSION`)
**Date:** YYYY-MM-DD
**Qt:** still 6.5+ / recommended 6.8 (change only if true)
### Action required
| Area | Change | What to do |
|------|--------|------------|
| … | … | … |
### Optional / polish
- …
### No action (compatible)
- Stable Theme / shell / control APIs unchanged for this slice.
Maintainers: append a filled section below when a slice has consumer-visible breaks or important opt-ins. Pure docs / Gallery-only / additive defaults usually need only a one-line No action note.
Checklist (every upgrade)¶
- Bump / reinstall the kit (
QWINUI3_VERSION/ Release zip /add_subdirectorypin). - Confirm Qt major/minor still matches your linked kit — packaging-consumer.md.
- Skim stable-api.md changelog for new promotes or defer notes.
- Rebuild Release; run your smoke / Gallery
--smokeif you vendor the Gallery binary. - If you fork Theme colors: keep using
customAccent/ packs — do not assign readonlybgCardetc.
Recent minors (filled)¶
Upgrade 3.55 → 3.56¶
Product version: 3.56
Date: 2026-08-27
Qt: still 6.5+ / recommended 6.8
Action required¶
| Area | Change | What to do |
|---|---|---|
| — | NavigationView depth APIs (D30–D32) | None required — defaults unchanged |
Optional / polish¶
paneSearchSettingsCategoryto persist pane search highlightclearPinnedNavKeys/movePinnedNavKey/clearPaneSearch/announce()- Opt-in
announcePinChanges/announcePaneSearchChanges
No action (compatible)¶
- Pin Settings, highlight query, and default live-region path unchanged when new props stay default
Upgrade 3.54 → 3.55¶
Product version: 3.55
Date: 2026-08-27
Qt: still 6.5+ / recommended 6.8
Action required¶
| Area | Change | What to do |
|---|---|---|
| — | Silent-runtime wave sign-off (C26) | None — docs / checkpoint only |
Optional / polish¶
- Switch p50 baseline recorded in checkpoint-390
No action (compatible)¶
- No kit API or default UX / transition changes in this slice
Upgrade 3.53 → 3.54¶
Product version: 3.54
Date: 2026-08-27
Qt: still 6.5+ / recommended 6.8
Action required¶
| Area | Change | What to do |
|---|---|---|
| — | Stable-six chart coalesce inventory (C25) | None — visuals / APIs unchanged |
Optional / polish¶
- See performance.md stable-six table
- After in-place series edits, call
requestRedraw()on Line / Bar / Donut
No action (compatible)¶
- RingGauge / ChartCard remain non-Canvas hosts; KpiTile trend still uses Sparkline coalesce
Upgrade 3.52 → 3.53¶
Product version: 3.53
Date: 2026-08-27
Qt: still 6.5+ / recommended 6.8
Action required¶
| Area | Change | What to do |
|---|---|---|
| — | NavigationView pane rebuild costs (C24) | None — visuals unchanged |
Optional / polish¶
- Prefer
modelassign /patchNavItemoverrebuildNavModel()when keys/order unchanged - Nested group children keep Repeater identity when title/icon fingerprint matches
No action (compatible)¶
- Pip schedule, expand animation, and page transitions unchanged
Upgrade 3.51 → 3.52¶
Product version: 3.52
Date: 2026-08-27
Qt: still 6.5+ / recommended 6.8
Action required¶
| Area | Change | What to do |
|---|---|---|
| — | DataTable / TreeDataGrid row-height cache + skip (C23) | None — visuals unchanged |
Optional / polish¶
cacheBufferPxon DataTable / TreeDataGrid (< 0=rowHeight * 12)- TreeDataGrid
rows=replaces are coalesced viaQt.callLater(same as DataTable)
No action (compatible)¶
fixedRowHeightremains always true; variable-height virtualization still out of scope
Upgrade 3.50 → 3.51¶
Product version: 3.51
Date: 2026-08-27
Qt: still 6.5+ / recommended 6.8
Action required¶
| Area | Change | What to do |
|---|---|---|
| ListDetailsView | maxFilterResults default 0 → 256 (C22) |
Need every match on huge JS arrays? Set maxFilterResults: 0 |
Optional / polish¶
minFilterLengthon ListDetailsView (parity with ItemsView)cacheBufferPxon ItemsView / ListDetailsView (< 0= mild auto overscan)
No action (compatible)¶
- Visual / selection path unchanged for typical master lists (< 256 filter hits)
Upgrade 3.49 → 3.50¶
Product version: 3.50
Date: 2026-08-27
Qt: still 6.5+ / recommended 6.8
Action required¶
| Area | Change | What to do |
|---|---|---|
| — | Binding churn / incremental nav sync (C21) | None — visuals unchanged |
Optional / polish¶
- After replacing NavigationView
modelwith same keys, do not callrebuildNavModel()— letonModelChangedpatch - See performance.md
No action (compatible)¶
- Explicit
rebuildNavModel()still available when structure changes
Upgrade 3.48 → 3.49¶
Product version: 3.49
Date: 2026-08-27
Qt: still 6.5+ / recommended 6.8
Action required¶
| Area | Change | What to do |
|---|---|---|
| — | Remaining chart paint coalesce (C20) | None — visuals unchanged; hover/data still redraw |
Optional / polish¶
- Prefer
requestRedraw()over barecanvas.requestPaint()in custom Canvas charts - See performance.md
No action (compatible)¶
- Stable charts / DataTable / NavigationView coalesce paths unchanged
Upgrade 3.47 → 3.48¶
Product version: 3.48
Date: 2026-08-27
Qt: still 6.5+ / recommended 6.8
Action required¶
| Area | Change | What to do |
|---|---|---|
| — | Memory wave sign-off (H17) | None — docs / checkpoint only |
Optional / polish¶
- See checkpoint-390 for Gallery idle WorkingSet baseline (~136 MB WS)
No action (compatible)¶
- No runtime API or visual changes in this minor
Upgrade 3.46 → 3.47¶
Product version: 3.47
Date: 2026-08-27
Qt: still 6.5+ / recommended 6.8
Action required¶
| Area | Change | What to do |
|---|---|---|
| — | Pixmap / shadow cache caps (H16) | None — acrylic frost and default shadow blur/opacity unchanged |
Optional / polish¶
- Override pixmap budget:
QWINUI3_PIXMAP_CACHE_KB(KB; omit = 16384;0= leave Qt default) - Prefer
Image.sourceSizefor avatars / badges; see performance.md
No action (compatible)¶
ElevatedChrome/ AcrylicSurface visuals when shown match prior defaults
Upgrade 3.45 → 3.46¶
Product version: 3.46
Date: 2026-08-27
Qt: still 6.5+ / recommended 6.8
Action required¶
| Area | Change | What to do |
|---|---|---|
| — | Gallery page Component unload (H15) | None for apps — kit pageCacheLimit default stays 24 |
Optional / polish¶
- Long-browse demo shells can mirror Gallery:
pageCacheLimit: 8+pinnedPageCache: ["HomePage", "SettingsPage"] - See performance.md Gallery cold-start / page cache notes
No action (compatible)¶
- StackView.replace already destroyed off-screen page trees; only Component LRU retention changed in Gallery
Upgrade 3.44 → 3.45¶
Product version: 3.45
Date: 2026-08-27
Qt: still 6.5+ / recommended 6.8
Action required¶
| Area | Change | What to do |
|---|---|---|
| — | Chart ring caps + opt-in downsample (H14) | None — autoLod / chart visuals unchanged; ChartSeries.capacity defaults to 0 (unlimited) |
Optional / polish¶
- Live series: set
ChartSeries.capacityor useChartUtils.trimRing/LiveMetricStrip - See performance.md
No action (compatible)¶
- Existing Line/Area/Scatter LOD defaults and KpiTile / LiveMetricStrip caps unchanged
Upgrade 3.43 → 3.44¶
Product version: 3.44
Date: 2026-08-27
Qt: still 6.5+ / recommended 6.8
Action required¶
| Area | Change | What to do |
|---|---|---|
| — | DataTable lean ListView roles (H13) | None — cells / selection / CSV still use original row objects |
Optional / polish¶
- Wide tables: prefer
hiddenColumnsso filter does not scan unused fields - See performance.md for ListView role guidance
No action (compatible)¶
- Public
rows/columns/selectedRowAPIs unchanged
Upgrade 3.42 → 3.43¶
Product version: 3.43
Date: 2026-08-27
Qt: still 6.5+ / recommended 6.8
Action required¶
| Area | Change | What to do |
|---|---|---|
| — | List/Tree reuseItems + cacheBuffer defaults (H12) |
None — visuals unchanged; raw ListView/TreeView should still set reuse yourself |
Optional / polish¶
- Prefer kit recipes (
ItemsView,ListDetailsView,NavigationView,FileTree) over hand-rolled lists - See performance.md for overscan guidance
No action (compatible)¶
- Existing explicit
cacheBuffer/reuseItemson app lists still win
Upgrade 3.41 → 3.42¶
Product version: 3.42
Date: 2026-08-27
Qt: still 6.5+ / recommended 6.8
Action required¶
| Area | Change | What to do |
|---|---|---|
| — | ThemeFonts Text/Display stacks lazy (H11) | None — first textFamilies / displayFamilies still returns the same lists |
Optional / polish¶
- Density remains formula-only (
standard/compact); no Theme metric pack tables FluentIconsCatalogdefers catalog row build untilnames()/entries()Theme.iconShouldMirrorchecks codepoints before named FluentIcons map
No action (compatible)¶
- Color / spacing / UI font defaults unchanged
Upgrade 3.40 → 3.41¶
Product version: 3.41
Date: 2026-08-27
Qt: still 6.5+ / recommended 6.8
Action required¶
| Area | Change | What to do |
|---|---|---|
| — | Shared icon QFont cache (H10) |
None — defaults unchanged |
Optional / polish¶
- Prefer
Theme.iconFontFor(px)orTheme.iconFontFor(px, weight)over settingfont.familytoTheme.fontFamilyIconalone FontIcon/AnimatedIconuse the weight overload (no per-bindQFontmutate)
No action (compatible)¶
- Existing
iconFontFor(px)call sites keep PreferNoHinting visuals
Upgrade 3.39 → 3.40¶
Product version: 3.40
Date: 2026-08-27
Qt: still 6.5+ / recommended 6.8
Action required¶
| Area | Change | What to do |
|---|---|---|
| — | Cold-start wave (S10–S17) sign-off | None — docs / checkpoint only |
Optional / polish¶
- checkpoint-390.md cold-start section filled; interactive shell ~335 ms local Win Release vs 1500 ms CI gate
No action (compatible)¶
- Kit QML APIs unchanged
Upgrade 3.38 → 3.39¶
Product version: 3.39
Date: 2026-08-27
Qt: still 6.5+ / recommended 6.8
Action required¶
| Area | Change | What to do |
|---|---|---|
| CI consumers | Gallery smoke now fails if main= / app= exceed absolute budgets |
Keep Release Gallery under performance.md CI table; local: python scripts/smoke_gallery.py --check-startup-budget |
Optional / polish¶
- Absolute budgets: Win
main< 1500 ms /app< 800 ms; Linux offscreenmain< 2000 ms /app< 1000 ms - Auto-enabled under
CI/GITHUB_ACTIONS; opt-in locally via flag orQWINUI3_CHECK_STARTUP_BUDGET=1
No action (compatible)¶
- Kit QML APIs unchanged
Upgrade 3.37 → 3.38¶
Product version: 3.38
Date: 2026-08-27
Qt: still 6.5+ / recommended 6.8
Action required¶
| Area | Change | What to do |
|---|---|---|
| — | Optional-host cold path (S15) | None for product apps that already probe/attach on demand |
Optional / polish¶
FrameStatsMonitorconnectsframeSwappedonly whenenabledorshowRhi; Gallery attaches after enable / CLIKeyboardEnginedefers Keyman CoreloadLayoutuntil firstprocessVk/previewVk/setLayoutId- Gallery WebView2 page: no auto Runtime Timer — Check Runtime, Go, or Retry
No action (compatible)¶
- Kit QML APIs unchanged; WebView2Host still probes on first visible activate
Upgrade 3.36 → 3.37¶
Product version: 3.37
Date: 2026-08-27
Qt: still 6.5+ / recommended 6.8
Action required¶
| Area | Change | What to do |
|---|---|---|
| — | Gallery-only catalog lazy path | None for product apps |
Optional / polish¶
- Gallery Home featured / default recents resolve via a small hot index
- Full
ControlCatalogmodel builds after the first presented frame (search / pane / navigate still force it)
No action (compatible)¶
- Kit QML APIs unchanged
Upgrade 3.35 → 3.36¶
Product version: 3.36
Date: 2026-08-27
Qt: still 6.5+ / recommended 6.8
Action required¶
| Area | Change | What to do |
|---|---|---|
| — | Import-set documentation + example CMake helper | None unless you want qwinui3_link_qml_import_set |
Optional / polish¶
- Default examples use the shell import set (
Theme+Extras+Platform) QWinUI3.Extras.Chartsis opt-in (examples/dashboard, Gallery chart pages)- Helper:
cmake/QWinUI3QmlImportSets.cmake—shell/charts/osk/webview2/gallery scripts/lint_qml_imports.pyforbids deferred URIs on shell examples and GalleryMain.qml
No action (compatible)¶
- Same URIs as 3.35; this slice is graph/docs + CMake helper
Upgrade 3.34 → 3.35¶
Product version: 3.35
Date: 2026-08-27
Qt: still 6.5+ / recommended 6.8
Action required¶
| Area | Change | What to do |
|---|---|---|
| Charts | LineChart / BarChart / ChartSeries / … moved to QWinUI3.Extras.Charts |
Add import QWinUI3.Extras.Charts. Static apps also QWINUI3_IMPORT_QML_PLUGINS_CHARTS + link qwinui3_extras_chartsplugin |
| OSK | OnScreenKeyboard / KeyboardEngine moved to QWinUI3.Extras.Osk |
Add import QWinUI3.Extras.Osk. Static: QWINUI3_IMPORT_QML_PLUGINS_OSK + qwinui3_extras_oskplugin |
| WebView2 | WebView2Host moved to QWinUI3.Platform.WebView2 |
Add import QWinUI3.Platform.WebView2. Static: QWINUI3_IMPORT_QML_PLUGINS_WEBVIEW2 + qwinui3_platform_webview2plugin |
QWINUI3_IMPORT_QML_PLUGINS still loads style + theme + extras + platform only (nav/shell cold path). Sparkline, ChartCard, KpiTile, ChartUtils, and gauges stay on QWinUI3.Extras.
Optional / polish¶
- Default Bootstrap no longer registers chart, OSK, or WebView2 C++ types before first import of those modules
No action (compatible)¶
- Apps that never instantiate charts / OSK / WebView2 — no import or plugin changes
Upgrade 3.33 → 3.34¶
Product version: 3.34
Date: 2026-08-27
Qt: still 6.5+ / recommended 6.8
Action required¶
| Area | Change | What to do |
|---|---|---|
| — | Cold-start Bootstrap / Theme deferrals | None (defaults unchanged visually) |
Optional / polish¶
configureEnvironmentpins a soft RHI default (preferredPlatformBackend/applyDirect) — no Vulkan/D3D host probe before first frame- Opt in to legacy probe + fallback:
QWINUI3_RHI_PROBE=1 FluentIconsbuilds the Iconography catalog rows lazily; named glyphs still load on firstFluentIconsuse- Mono font family resolution deferred until
ThemeFonts.monoFont*/monoFamily
No action (compatible)¶
- Public APIs additive (
preferredPlatformBackend,applyDirect); default chrome/fonts unchanged
Upgrade 3.32 → 3.33¶
Product version: 3.33
Date: 2026-08-27
Qt: still 6.5+ / recommended 6.8
Action required¶
| Area | Change | What to do |
|---|---|---|
| — | Gallery-only copy cleanup | None |
Optional / polish¶
- Removed roadmap slice labels like
(2.06)/wave 6from Gallery page titles, subtitles, and recipe copy - Removed Settings performance-arc wave checklist card
No action (compatible)¶
- Control APIs unchanged; docs/ROADMAP still track slice history
Upgrade 3.31 → 3.32¶
Product version: 3.32
Date: 2026-08-27
Qt: still 6.5+ / recommended 6.8
Action required¶
| Area | Change | What to do |
|---|---|---|
| — | NavigationView pip animation fix | None |
Optional / polish¶
- Selection pip no longer snaps before the stretch animation (syncViewport/syncToCurrent respect pending moves)
schedulePipMovelast-writer-wins;currentKeydrives pip for nested siblings
No action (compatible)¶
- Public API unchanged
Upgrade 3.30 → 3.31¶
Product version: 3.31
Date: 2026-08-27
Qt: still 6.5+ / recommended 6.8
Action required¶
| Area | Change | What to do |
|---|---|---|
| — | Internal hardening only | None |
Optional / polish¶
- Guarded bare
Qt.callLater(method)across CommandBar, MenuFlyout, TwoPaneView, layout panels, Gallery Main title-bar refresh, transitions, OSK, etc. WindowHelper::installdisconnects activeChanged/destroyed from the previous window before switching targets
No action (compatible)¶
- Public QML / C++ APIs unchanged
Upgrade 3.29 → 3.30¶
Product version: 3.30
Date: 2026-08-27
Qt: still 6.5+ / recommended 6.8
Action required¶
| Area | Change | What to do |
|---|---|---|
| — | Internal hardening only | None |
Optional / polish¶
- Guarded remaining bare
Qt.callLater(method)paths (SegmentedControl, SelectorBar, DropDownButton, TabView, ContentDialog, CatalogPage, Toast, title chrome) - WebView2Host nulls
Impl::qin destructor so COM callbacks cannot UAF after teardown
No action (compatible)¶
- Public QML / C++ APIs unchanged
Upgrade 3.28 → 3.29¶
Product version: 3.29
Date: 2026-08-27
Qt: still 6.5+ / recommended 6.8
Action required¶
| Area | Change | What to do |
|---|---|---|
| Icons | Prefer Theme.iconFontFor(px) |
Replace remaining font.family: Theme.fontFamilyIcon in app code |
Optional / polish¶
- Migrated Style/Extras/Gallery icon
Text/ToolButtonglyphs toTheme.iconFontFor iconFontForuses PreferNoHinting + NoFontMerging (avoids Fixedsys GDI merge)
No action (compatible)¶
Theme.fontFamilyIconstring remains for rare cases
Upgrade 3.27 → 3.28¶
Product version: 3.28
Date: 2026-08-27
Qt: still 6.5+ / recommended 6.8
Action required¶
| Area | Change | What to do |
|---|---|---|
| Icons | Prefer Theme.iconFontFor(px) over font.family: Theme.fontFamilyIcon |
Update custom icon Text if you still see Fixedsys DirectWrite warnings |
Optional / polish¶
- ThemeFonts.iconFontFor: outline + PreferNoHinting (stops GDI Fixedsys fallback from icon PUA + inherited UI hinting)
- FontIcon / CaptionButton / NavigationView / Button leading / HomePage: use iconFontFor
- Label / TextBlock / Drawer title: bind
font.familiesstacks
No action (compatible)¶
Theme.fontFamilyIconstring still works; iconFontFor is preferred
Upgrade 3.26 → 3.27¶
Product version: 3.27
Date: 2026-08-27
Qt: still 6.5+ / recommended 6.8
Action required¶
| Area | Change | What to do |
|---|---|---|
| — | ContentDialogQueue / ThemeFonts | None required |
Optional / polish¶
- ContentDialogQueue: skip destroyed dialogs when pumping the queue
- ThemeFonts: never fall through to GDI Fixedsys; mono uses TypeWriter + PreferNoHinting
- Flyout / CommandBarFlyout: null-safe reposition after
callLater
No action (compatible)¶
- APIs unchanged
Upgrade 3.25 → 3.26¶
Product version: 3.26
Date: 2026-08-27
Qt: still 6.5+ / recommended 6.8
Action required¶
| Area | Change | What to do |
|---|---|---|
| — | callLater teardown guards | None required |
Optional / polish¶
- SelectorBar / NavigationView / ContentDialog / PlatformTitleBar / MenuStatusWindow: null-safe
Qt.callLaterafter unload
No action (compatible)¶
- APIs unchanged
Upgrade 3.24 → 3.25¶
Product version: 3.25
Date: 2026-08-27
Qt: still 6.5+ / recommended 6.8
Action required¶
| Area | Change | What to do |
|---|---|---|
| — | SegmentedControl teardown | None required |
Optional / polish¶
- SegmentedControl: null-guard
moveIndicatorafterQt.callLater(page unload)
No action (compatible)¶
- APIs unchanged
Upgrade 3.23 → 3.24¶
Product version: 3.24
Date: 2026-08-27
Qt: still 6.5+ / recommended 6.8
Action required¶
| Area | Change | What to do |
|---|---|---|
| — | Gallery / chart / table smoke errors | None required |
Optional / polish¶
- Reverted invalid ProgressBar
orientationusage (QQC ProgressBar has no orientation) - Fixed SegmentedControl / DataTable / Drawer / AccessibilityPage ReferenceErrors
- LineChart / BarChart / AreaChart: wrap series
Connectionsin Item delegates
No action (compatible)¶
- APIs unchanged
Upgrade 3.22 → 3.23¶
Product version: 3.23
Date: 2026-08-27
Qt: still 6.5+ / recommended 6.8
Action required¶
| Area | Change | What to do |
|---|---|---|
| — | RTL padding / indicator placement | None required |
Optional / polish¶
- SpinBox / ComboBox / TextField / CheckBox / RadioButton / MenuItem: mirrored (RTL) chrome no longer overlaps text
No action (compatible)¶
- APIs unchanged
Upgrade 3.21 → 3.22¶
Product version: 3.22
Date: 2026-08-27
Qt: still 6.5+ / recommended 6.8
Action required¶
| Area | Change | What to do |
|---|---|---|
| — | Vertical Slider fill mapping | None required |
Optional / polish¶
- Slider: vertical active fill now grows from the thumb down to the bottom (Qt
visualPositionis 0 at top)
No action (compatible)¶
- APIs unchanged
Upgrade 3.20 → 3.21¶
Product version: 3.21
Date: 2026-08-27
Qt: still 6.5+ / recommended 6.8
Action required¶
| Area | Change | What to do |
|---|---|---|
| — | ComboBox click-to-open fix | None required |
Optional / polish¶
- ComboBox: non-editable field no longer eats mouse presses — click anywhere on the control opens the popup (
editable: truestill focuses the TextInput)
No action (compatible)¶
- APIs unchanged
Upgrade 3.19 → 3.20¶
Product version: 3.20
Date: 2026-08-27
Qt: still 6.5+ / recommended 6.8
Action required¶
| Area | Change | What to do |
|---|---|---|
| — | Slider / RangeSlider visual fix | None required |
Optional / polish¶
- Slider / RangeSlider: track vertically centered with thumb; fill locked to
visualPosition(no laggy width Behavior) - Tick marks use
Theme.strokeControlStrongat full opacity for readable contrast
No action (compatible)¶
- APIs unchanged
Upgrade 3.18 → 3.19¶
Product version: 3.19
Date: 2026-08-27
Qt: still 6.5+ / recommended 6.8
Action required¶
| Area | Change | What to do |
|---|---|---|
| — | Button leadingSymbol | None required |
Optional / polish¶
- Button:
leadingSymbol/leadingGlyph— Fluent icon before the label - Gallery Button — appearances, accent + icon, interactive loading demo
- Existing
appearance/loading/highlightedunchanged
No action (compatible)¶
- Stable APIs unchanged; new properties default empty
Upgrade 3.17 → 3.18¶
Product version: 3.18
Date: 2026-08-27
Qt: still 6.5+ / recommended 6.8
Action required¶
| Area | Change | What to do |
|---|---|---|
| — | CheckBox / RadioButton description | None required |
Optional / polish¶
- CheckBox:
description,header(text alias),isThreeState(tristate alias) - RadioButton:
description,header(text alias) - Gallery CheckBox — interactive three-state select-all; RadioButton — description groups
No action (compatible)¶
- Stable APIs unchanged; new properties default empty
Upgrade 3.16 → 3.17¶
Product version: 3.17
Date: 2026-08-27
Qt: still 6.5+ / recommended 6.8
Action required¶
| Area | Change | What to do |
|---|---|---|
| — | ComboBox header / editable contentItem | None required |
Optional / polish¶
- ComboBox:
header,description,errorMessage— same vocabulary as TextField (3.16) - ComboBox:
editable: trueuses an inline TextInput (WinUI editable ComboBox) - Gallery ComboBox page — header, editable, required validation demos
- FormLayout left headers still use HeaderedComboBox
No action (compatible)¶
- Stable APIs unchanged; new properties default off / empty
Upgrade 3.15 → 3.16¶
Product version: 3.16
Date: 2026-08-27
Qt: still 6.5+ / recommended 6.8
Action required¶
| Area | Change | What to do |
|---|---|---|
| — | TextField header / validation chrome | None required |
Optional / polish¶
- TextField:
header,description,errorMessage,characterLimit,isReadOnly - Gallery TextField page — WinUI TextBox demos (header, read-only, live validation, password echoMode)
- FormLayout left headers still use HeaderedTextBox
No action (compatible)¶
- Stable APIs unchanged; new properties default off / empty
Upgrade 3.14 → 3.15¶
Product version: 3.15
Date: 2026-08-27
Qt: still 6.5+ / recommended 6.8
Action required¶
| Area | Change | What to do |
|---|---|---|
| — | ProgressBar header / value label | None required |
Optional / polish¶
- ProgressBar:
header,showValue,valueLabel,trackThickness— Fluent chrome above the track - ProgressBar: Gallery demos for Running / Paused / Error and Slider-driven determinate value
- Existing
showError/showPausedunchanged
No action (compatible)¶
- Stable APIs unchanged; new properties default off
Upgrade 3.13 → 3.14¶
Product version: 3.14
Date: 2026-08-27
Qt: still 6.5+ / recommended 6.8
Action required¶
| Area | Change | What to do |
|---|---|---|
| — | RangeSlider tick marks + vertical rail | None required |
Optional / polish¶
- RangeSlider:
tickMarksVisible,tickPlacement,verticalFillThickness— same vocabulary as Slider (3.13) - Gallery RangeSlider page — horizontal ticks, vertical range demos
No action (compatible)¶
- Stable APIs unchanged; new properties default off
Upgrade 3.12 → 3.13¶
Product version: 3.13
Date: 2026-08-27
Qt: still 6.5+ / recommended 6.8
Action required¶
| Area | Change | What to do |
|---|---|---|
| — | Slider tick marks + vertical rail | None required |
Optional / polish¶
- Slider:
tickMarksVisible: truewithtickPlacement(top·bottom·bothhorizontal;left·right·bothvertical) - Slider: vertical orientation uses thick accent fill below thumb (
verticalFillThickness, default 8) - Gallery Slider page — WinUI-style tick + vertical range demos
No action (compatible)¶
- Stable APIs unchanged; new properties default off
Upgrade 3.11 → 3.12¶
Product version: 3.12
Date: 2026-08-27
Qt: still 6.5+ / recommended 6.8
Action required¶
| Area | Change | What to do |
|---|---|---|
| — | Extras pointer / icon polish | None required |
Optional / polish¶
- AppBarButton / IconicButton:
loading: true→ inline ProgressRing (I5) - SettingsCard / ChartCard:
interactive: truefor hover elevation + press scale (M10) - ListTile:
swipeHintVisible: truefor swipe-row affordance (M9) - KpiTile / ChartCard: leading symbols use
FontIcon+iconContextpresets (I7) - Gallery Style spot-check · Iconography — loading + card demos
No action (compatible)¶
- Stable APIs unchanged; new properties default off
Upgrade 3.10 → 3.11¶
Product version: 3.11
Date: 2026-08-27
Qt: still 6.5+ / recommended 6.8
Action required¶
| Area | Change | What to do |
|---|---|---|
| — | Style pointer / appearance polish | None required |
Optional / polish¶
- ToolButton / RoundButton:
appearancevariants; RoundButton.loading for async actions — pointer-feedback.md - Slider:
tickMarksVisible: truewithstepSizefor stepped tracks - ProgressBar: completion flash at 100% (honors
Theme.reducedMotion) - Gallery Style spot-check — press/hover/focus matrix
No action (compatible)¶
- Stable APIs unchanged; existing controls keep prior defaults
Upgrade 3.06 → 3.10¶
Product version: 3.10
Date: 2026-08-27
Qt: still 6.5+ / recommended 6.8
Action required¶
| Area | Change | What to do |
|---|---|---|
| — | Additive app-platform APIs + examples | None required |
Optional / polish¶
- V1–V3: copy
admin-settings,master-detail-crm,ops-console - W7–W8:
WindowMessageBusappearance+ PanelFloatHost —examples/multi-window - P3:
WindowHelper.registerFileAssociation— file-association.md - Sign-off: checkpoint-310.md
No action (compatible)¶
- Existing shells / commands / charts APIs unchanged
Upgrade 3.05 → 3.06¶
Product version: 3.06
Date: 2026-08-27
Qt: still 6.5+ / recommended 6.8
Action required¶
| Area | Change | What to do |
|---|---|---|
| — | Additive BarChart bin API | None required |
Optional / polish¶
- Prefer BarChart
{ samples; binCount }for distributions — charts.md - Keep HistogramChart for Gallery / experimental only (FL-015 closed)
No action (compatible)¶
- Existing
values/bars/seriespaths unchanged
Upgrade 3.04 → 3.05¶
Product version: 3.05
Date: 2026-08-27
Qt: still 6.5+ / recommended 6.8
Action required¶
| Area | Change | What to do |
|---|---|---|
| — | Additive dashboard APIs | None required |
Optional / polish¶
- G1: Prefer LiveMetricStrip for live KPI rows — charts.md · components/LiveMetricStrip.md
- G2: Gallery Ops console +
examples/dashboardlive tick - FL-014 closed
No action (compatible)¶
- Existing MetricCompareRow / KpiTile / DashboardShell unchanged
Upgrade 3.03 → 3.04¶
Product version: 3.04
Date: 2026-08-27
Qt: still 6.5+ / recommended 6.8
Action required¶
| Area | Change | What to do |
|---|---|---|
| — | Additive navigation APIs | None required |
Optional / polish¶
- N1:
pinNavKey/pinnedNavSettingsCategoryfor pane favorites — navigation.md - N2:
jumpListEnabled+openJumpList()for largenavModel - N3:
pushDrilldown+ bind BreadcrumbBar tobreadcrumbTrail; TitleBar Back vianavigateBack()
No action (compatible)¶
- Existing
navigateToPage/ breadcrumb helpers unchanged; drilldown is opt-in.
Upgrade 2.73 → 2.80¶
Product version: 2.80
Date: 2026-08-23
Qt: still 6.5+ / recommended 6.8
Action required¶
| Area | Change | What to do |
|---|---|---|
| — | Additive wave | None required |
Optional / polish¶
- 2.74: Opt-in
SingleInstance/QWINUI3_SINGLE_INSTANCE=1— single-instance.md;qwinui3 run. - 2.75:
ErrorBoundaryrecovery pattern (Pitfalls demo). - 2.76:
qwinui3 upgrade --from X.YY; Path C primary in packaging-consumer. - 2.77–2.79:
RecentFiles,OfflineBanner/OperationRetry,SensitiveField/ConfirmWithReason. - 2.80: checkpoint-280.md.
- ConfirmWithReason: connect
onConfirmed(reason)— do not shadow Dialogaccepted. - ColorPicker:
showAlphashows an alpha slider; hex round-trips#RRGGBBAA; V=0 keeps true black.
No action (compatible)¶
- Default remains multi-instance; Gallery does not force single-instance.
Upgrade 2.72 → 2.73¶
Product version: 2.73
Date: 2026-08-23
Qt: still 6.5+ / recommended 6.8
Action required¶
| Area | Change | What to do |
|---|---|---|
| — | Additive DX | None required |
Optional / polish¶
- Start at getting-started.md;
python scripts/qwinui3.py init/doctor --fix. - Checkpoint: checkpoint-273.md.
No action (compatible)¶
- Stable Theme / shell / control APIs unchanged for this slice.
Upgrade 2.71 → 2.72¶
Product version: 2.72
Date: 2026-08-23
Qt: still 6.5+ / recommended 6.8
Action required¶
| Area | Change | What to do |
|---|---|---|
| — | Additive | None required |
Optional / polish¶
- WindowMessageBus singleton:
post/subscribe/unsubscribe(same process). - SessionTimeout: idle + warning signals; call
poke()from shell activity.
No action (compatible)¶
- Stable Theme / shell / control APIs unchanged for this slice.
Upgrade 2.70 → 2.71¶
Product version: 2.71
Date: 2026-08-23
Qt: still 6.5+ / recommended 6.8
Action required¶
| Area | Change | What to do |
|---|---|---|
| — | Additive | None required |
Optional / polish¶
- DataTable:
copySelection()/exportCsv(toClipboard?)for CSV clipboard export. - MaskedTextField: simple
#/A/*masks. - PermissionGate: hide/disable children by
currentRole/allowedRoles.
No action (compatible)¶
- Stable Theme / shell / control APIs unchanged for this slice.
Upgrade 2.69 → 2.70¶
Product version: 2.70 Date: 2026-08-23 Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- A7 FeedbackSeverity: singleton palette + TeachingTip
severity— feedback.md. - B6 Skeleton: form/table placeholder handoff with Button.loading / ProgressRing / Shimmer.
- C6 cold start wave 11: performance.md budgets +
--startup-log. - D7 NotificationCenter:
groupingPolicy+persistCategoryfor read history. - D8 SessionRestore: nav key + DataTable scroll/selection beside geometryPersistenceKey.
- F6 fractional DPI: ThemeFonts PreferVerticalHinting on non-integer DPR — high-dpi.md.
- Checkpoint: checkpoint-270.md.
Action required (only if you adopt new APIs)¶
| Area | Change | What to do |
|---|---|---|
| TeachingTip | Optional severity |
Use FeedbackSeverity ints; -1 keeps neutral coach tips |
| NotificationCenter | Optional persistCategory |
Persist history across restarts |
| Session | Optional SessionRestore | Call restore() on startup / save() on exit |
No action (compatible)¶
- Existing InfoBar / Toast / Shimmer / NotificationCenter / geometryPersistenceKey call sites keep prior defaults.
Upgrade 2.68 → 2.69¶
Product version: 2.69 Date: 2026-08-23 Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- A6 DataTable:
rowStyle(zebra|plain),selectionAccent,headerStyle,rowBackgroundhook, row hover — data-collections.md. - B5 Flyout: directional enter slide from
placement(ContentDialog scale+fade unchanged). - C5 TreeDataGrid:
loadChildren(path, row)+releaseChildrenOnCollapse— tree-data.md. - D5 Calendar:
blackoutDates/blackoutFilteron CalendarView and CalendarDatePicker — calendar-view.md. - D6 RichEdit:
insertTable(rows, cols)+ sanitized HTML paste — rich-edit-261.md. - F4 Linux notify:
NotificationBridge.systemActions+TrayIcon.notifySystemWithActions(portal / notify-send). - F5 Wayland: modal / z-order soak checklist in platform-linux-wayland.md wave 3.
Action required (only if you adopt new APIs)¶
| Area | Change | What to do |
|---|---|---|
| TreeDataGrid | Optional loadChildren |
Return child row arrays on expand; enable releaseChildrenOnCollapse |
| Calendar | Optional blackout | Bind the same blackoutDates to CalendarView and CalendarDatePicker |
| Linux notify | Optional actions | Set systemActions: ["default", qsTr("Open")] on NotificationBridge |
No action (compatible)¶
- Existing DataTable / Flyout / Calendar / RichEdit / notify call sites keep prior defaults.
Upgrade 2.67 → 2.68¶
Product version: 2.68 Date: 2026-08-23 Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- A5 nav appearance: NavigationView
paneAppearance: standard|minimal|branded+paneLogo/brandedTitle— navigation.md. - B3 connected: ListDetailsView reverse morph on
showList()whenconnectedAnimationEnabled. - B4 charts: LineChart / BarChart / DonutChart
animateDataUpdatesseries tween — charts.md. - C3 cache:
pinnedPageCache+pageCacheMemoryAware/pageCacheMemoryBudgetMb— performance.md. - D3 Wizard: new Wizard host (StepBar + validation + Back/Next) — Gallery Wizard.
- D4 commands: CommandRegistry + CommandPalette
registryauto-discovery — commands.md. - F2 compositor: profile radius presets (GNOME 12 / Hyprland 10 / Sway 0 / KDE 8) — platform-linux-wayland.md.
- F3 ThemeSync:
followSystemAccent+ liveQStyleHints::colorSchemeChanged/systemAccent.
Action required (only if you adopt new APIs)¶
| Area | Change | What to do |
|---|---|---|
| NavigationView | Optional paneAppearance |
Use branded + paneLogo for product shells |
| CommandPalette | Optional registry |
Register scoped commands via CommandRegistry |
| Theme | Optional followSystemAccent |
ThemeSync copies WindowHelper.systemAccent |
No action (compatible)¶
- Existing NavigationView / charts / CommandPalette / ThemeSync call sites keep prior defaults.
Upgrade 2.66 → 2.67¶
Product version: 2.67 Date: 2026-08-23 Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- A3/A4 appearance: appearance-variants.md — ListTile
density/leadingPreset; SettingsCard / ChartCard / InfoBarappearance. - B1/B2 motion:
Theme.motion.*tokens; ItemsView / DataTable / ListDetailsViewitemEnter/itemExit. - C2 charts: LineChart
autoDecimate/decimateMode: "bucket"|"douglas". - C4 Style: Slider / Switch / ComboBox idle Behaviors gated to interaction.
- D2 forms: FormSection +
formFieldId/setFieldVisible— forms.md. - F1 platform:
PlatformCapabilitysingleton (Mica / blur / tray / WebView / SNI). - Sparkline: permanent defer → use KpiTile.trendValues — stable-api.md.
Action required (only if you adopt new APIs)¶
| Area | Change | What to do |
|---|---|---|
| ListTile | Prefer density over tileDensity |
tileDensity remains an alias |
| ChartCard | Prefer appearance: "elevated" |
elevated: true still works |
| Platform | Gate Mica/WebView UI on PlatformCapability.has(…) |
Show degradationHint when false |
No action (compatible)¶
- Existing SettingsCard / InfoBar / ItemsView / FormLayout call sites keep prior defaults.
Upgrade 2.65 → 2.66¶
Product version: 2.66 Date: 2026-08-23 Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Appearance A1/A2: appearance-variants.md — Button / AccentButton / HyperlinkButton
appearance; TextField / TextArea / ComboBoxfilled|outline+hasError; FormLayoutfieldAppearance/readOnly. - DataTable D1/C1:
sortSpecs(Shift+click multi-sort),hiddenColumns/setColumnVisible,columnWidthspersistence, Gallery 10k load path — data-collections.md.
Action required (only if you adopt new APIs)¶
| Area | Change | What to do |
|---|---|---|
| Buttons | Optional appearance |
Prefer explicit filled/subtle/outline/ghost over flat alone |
| Forms | FormLayout.fieldAppearance |
Push outline chrome to fields; keep errorMessage validation |
| DataTable | sortSpecs / hiddenColumns / columnWidths |
Bind widths to Settings; Shift+click for secondary sort |
No action (compatible)¶
- Existing Button / TextField / DataTable call sites — new properties default to prior visuals.
Upgrade 2.64 → 2.65¶
Product version: 2.65 Date: 2026-08-23 Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Charts + Dashboard Wave A (FL-009): deepen stable six + dashboard hosts — charts.md · charts-dashboard-arc.md.
- LineChart
zoomEnabledbrush zoom (viewStart/viewEnd/resetZoom()); keep crosshair on hover. - ChartCard
showExportAction/exportRequested/footerActions. - KpiTile
compareValue+sparklineHeight; RingGaugevalueFormat; DonutChartlegendPosition. - DashboardShell filter rail (
filterPane) + MetricCompareRow / ChartEmptyState. - Gallery Dashboard +
examples/dashboardrefresh.
Action required (only if you adopt new APIs)¶
| Area | Change | What to do |
|---|---|---|
| Dashboard layout | Prefer DashboardShell over ad-hoc ColumnLayout + TwoPaneView |
Copy examples/dashboard or Gallery Dashboard |
| LineChart | Optional zoomEnabled: true |
Teach drag-to-zoom; call resetZoom() for a Reset action |
| Empty charts | ChartEmptyState inside ChartCard | Use state: "empty" \| "loading" \| "error" |
No action (compatible)¶
- Existing stable-six dashboards keep working; new properties default off / empty.
Upgrade 2.63 → 2.64¶
Product version: 2.64 Date: 2026-08-17 Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Python Gallery (early 2.71):
examples/python-gallery/— full Gallery from PySide6 / PyQt6;packaging-python.md;python scripts/verify_python.py --smoke. - Collection perf + a11y sign-off: DataTable pin/group, ListDetailsView multi-select toolbar — collection-perf-264.md (2.64 / FL-008, FL-016).
- TreeDataGrid column resize; FileTree
filterText+ column chooser.
Action required (only if you adopt new APIs)¶
| Area | Change | What to do |
|---|---|---|
| DataTable | groupRole, columns[].pinned, columnOrder |
Pin identity columns; group ops rows; persist order in Settings |
| ListDetailsView | multiSelectEnabled, detailToolbar, selectedItems |
Bulk toolbar instead of separate ItemsView master |
| FileTree | filterText, hiddenColumnRoles |
Shared table filter; toggle metadata columns |
No action (compatible)¶
- Existing DataTable / ListDetailsView pages — new properties default off (
groupRoleempty,multiSelectEnabledfalse).
Upgrade 2.62 → 2.63¶
Product version: 2.63 Date: 2026-08-17 Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Notification center productize:
NotificationBridge→NotificationCenter— notification-center-263.md (2.63 / FL-007). - Set
maxHistory; pass stableidfor dedupe; usebridge.success()instead of manual toast + push.
Action required (only if you adopt the product stack)¶
| Area | Change | What to do |
|---|---|---|
| NotificationBridge | notificationCenter + recordInCenter |
Wire center on bridge; one API for toast + history |
| NotificationCenter | maxHistory, dedupeIdRole |
Cap stored rows; dedupe by id |
| ToastHost | Optional dedupeId on show() |
Skip duplicate transient toasts |
No action (compatible)¶
- Apps using only ToastHost / 2.27 manual center — still work; bridge params optional.
Upgrade 2.61 → 2.62¶
Product version: 2.62 Date: 2026-08-17 Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- SemanticZoom (experimental): contacts grid ↔ letter index — semantic-zoom-262.md (2.62 / FL-006).
- Gallery SemanticZoom contacts recipe; Ctrl+- / Ctrl++ keyboard zoom.
Action required (only if you adopt SemanticZoom)¶
| Area | Change | What to do |
|---|---|---|
| SemanticZoom | New experimental Extras type | import QWinUI3.Extras · one model for both views · selectGroup() on index |
| Selection | Shared state | Do not duplicate selection across two raw ItemsViews |
No action (compatible)¶
- Apps not using
SemanticZoom— no API breaks.
Upgrade 2.60 → 2.61¶
Product version: 2.61 Date: 2026-08-17 Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- RichEdit (experimental): mail/template editor — rich-edit-261.md (2.61 / FL-005).
- Gallery RichEdit mail-compose recipe;
sanitizePasteon by default.
Action required (only if you adopt RichEdit)¶
| Area | Change | What to do |
|---|---|---|
| RichEdit | New experimental Extras type | import QWinUI3.Extras · mark experimental in app docs · wire onLinkActivated |
| Paste | HTML subset | Keep sanitizePaste: true for user paste; review security-sensitive flows |
No action (compatible)¶
- Apps not using
RichEdit— no API breaks.
Upgrade 2.59 → 2.60¶
Product version: 2.60 Date: 2026-08-17 Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Friction tranche checkpoint: audit 2.51…2.60 + 3.00 prep draft — checkpoint-260 (2.60).
- Skim slice recipes 2.51…2.59 if jumping from 2.50 (stable-clarity-251.md … app-sluggishness-259.md).
No action (compatible)¶
- Docs-only audit tag; no API breaks.
Upgrade 2.58 → 2.59¶
Product version: 2.59 Date: 2026-08-17 Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- App-level perf wave 9: command recents, filter caps,
Button.loading— app-sluggishness-259.md (2.59).
Action required (only if you use these APIs)¶
| Area | Change | What to do |
|---|---|---|
| Button | New loading property (style) |
Async saves: loading: busy + enabled: canSave && !busy |
| ItemsView / AutoSuggestBox | minFilterLength · maxFilterResults |
Set on large JS-array models |
| CommandPalette | maxRecentCommands |
Optional id on commands for recents |
No action (compatible)¶
- Defaults preserve 2.58 behavior when new properties are untouched.
Upgrade 2.57 → 2.58¶
Product version: 2.58 Date: 2026-08-17 Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- OSK in apps: embedded dock recipe — copy
examples/osk-dock/— osk-in-apps-258.md (2.58).
Action required (only if you embed OSK)¶
| Area | Change | What to do |
|---|---|---|
| OnScreenKeyboard | sharedEngine · focus return · floating candidates |
One KeyboardEngine per window; see osk-in-apps-258.md |
No action (compatible)¶
- Floating OSK host unchanged —
examples/floating-osk/.
Upgrade 2.49 → 2.50¶
Product version: 2.50 Date: 2026-08-17 Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Tranche-1 checkpoint: audit 2.00…2.50 + 2.51+ friction queue — checkpoint-250 (2.50).
No action (compatible)¶
- Docs-only audit tag; no API breaks.
Upgrade 2.48 → 2.49¶
Product version: 2.49 Date: 2026-08-17 Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Performance wave 8: tranche-1 sign-off + chart/dashboard budgets — perf-signoff-2xx.md (2.49).
No action (compatible)¶
- Documentation + Gallery callouts only; no API breaks.
Upgrade 2.47 → 2.48¶
Product version: 2.48 Date: 2026-08-17 Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Friction slot (FL-009): dashboard compose decision tree — dashboard-compose-decision.md (2.48).
No action (compatible)¶
- Docs + Gallery UX only; stable chart APIs unchanged.
Upgrade 2.46 → 2.47¶
Product version: 2.47 Date: 2026-08-17 Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Field harden buffer: packaging path picker (FL-003) + stable-api import guard (FL-004) — field-harden-247.md (2.47).
- Smoke:
--smokenow loads Recipes hub + Performance pages.
No action (compatible)¶
- Docs + smoke coverage only; stable control APIs unchanged.
Upgrade 2.45 → 2.46¶
Product version: 2.46 Date: 2026-08-17 Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Docs IA v2: MkDocs 2.xx nav regroup + recipes.md hub v2 + Gallery Recipes hub mirror — docs-ia-v2.md (2.46).
No action (compatible)¶
- Documentation navigation only; no API changes.
Upgrade 2.44 → 2.45¶
Product version: 2.45 Date: 2026-08-17 Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Experimental sweep (FL-004): Gallery Experimental / Permanent defer badges + experimental-sweep.md verdict matrix (2.45).
No action (compatible)¶
- Docs + Gallery UX only; stable control APIs unchanged.
Upgrade 2.43 → 2.44¶
Product version: 2.44 Date: 2026-08-17 Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Developer diagnostics:
FrameStatsMonitor.retailMode/persistSettings/applyRetailProfile(); CLI--retail-diagnostics; FrameStats promoted stable — developer-diagnostics.md (2.44).
No action (compatible)¶
- Additive Platform API; call
applyRetailProfile()only when adopting the retail checklist.
Upgrade 2.42 → 2.43¶
Product version: 2.43 Date: 2026-08-17 Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Multi-window + onboarding: coach-on-main-shell + Settings category vs geometry — multi-window-onboarding.md (2.43).
No action (compatible)¶
- Stable Theme / shell / control APIs unchanged for this slice.
Upgrade 2.41 → 2.42¶
Product version: 2.42 Date: 2026-08-17 Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- SwipeControl deepen:
dragThreshold/nestedScrollFriendlyfor list rows + TeachingTip teaching pattern — touch-pointer.md (2.42).
No action (compatible)¶
- Stable Theme / shell / control APIs unchanged for this slice.
Upgrade 2.40 → 2.41¶
Product version: 2.41 Date: 2026-08-17 Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Command/menu wave 3: large-model CommandPalette (
commandCount/filteredCount, filter matchesshortcut) + MenuBar accelerator mirror recipe — commands.md (2.41).
No action (compatible)¶
- Stable Theme / shell / control APIs unchanged for this slice.
Upgrade 2.39 → 2.40¶
Product version: 2.40 Date: 2026-08-17 Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Performance wave 7: collection debounce/filter checklist for DataTable / ListDetailsView / NavigationView / FileTree / TreeDataGrid — performance.md (2.40).
No action (compatible)¶
- Stable Theme / shell / control APIs unchanged for this slice.
Upgrade 2.38 → 2.39¶
Product version: 2.39 Date: 2026-08-17 Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Gallery catalog expansion: 2.21…2.38 findability matrix, Home Recently shipped refresh, Pitfalls 2.xx checklist — gallery-catalog-expansion.md (2.39).
No action (compatible)¶
- Stable Theme / shell / control APIs unchanged for this slice.
Upgrade 2.37 → 2.38¶
Product version: 2.38 Date: 2026-08-17 Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Theme overrides wave 2: accent packs +
ThemePrefspersist recipe + contrast/density integration — theme-overrides.md (2.38).
No action (compatible)¶
- Stable Theme / shell / control APIs unchanged for this slice.
Upgrade 2.36 → 2.37¶
Product version: 2.37 Date: 2026-08-17 Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Carousel recipes: FlipView / PipsPager + SwipeView hosts, reducedMotion — carousel-recipes.md (2.37).
No action (compatible)¶
- Stable Theme / shell / control APIs unchanged for this slice.
Upgrade 2.35 → 2.36¶
Product version: 2.36 Date: 2026-08-17 Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Security & trust wave 3: FileTree / TreeDataGrid path trust + WebView2 download policy D/E/F — security-trust.md (2.36).
No action (compatible)¶
- Stable Theme / shell / control APIs unchanged for this slice.
Upgrade 2.34 → 2.35¶
Product version: 2.35 Date: 2026-08-17 Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Localization wave 4: fourth seed locale
de_DE+ 2.21…2.34 Gallery pageqsTrchecker — i18n-rtl.md (2.35). Runlupdate src/galleryafter adding Gallery pages.
No action (compatible)¶
- Stable Theme / shell / control APIs unchanged for this slice.
Upgrade 2.33 → 2.34¶
Product version: 2.34 Date: 2026-08-17 Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Packaging & CI consumer matrix: shared/static × Win/Linux table +
consumer-matrix.ymlCI job — packaging-consumer.md (2.34).
No action (compatible)¶
- Stable Theme / shell / control APIs unchanged for this slice.
Upgrade 2.32 → 2.33¶
Product version: 2.33 Date: 2026-08-17 Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Linux portal & tray wave 3: FilePicker / SNI tray / idle inhibit field regression suite — platform-linux-wayland.md (2.33).
No action (compatible)¶
- Docs + Gallery callouts only; platform APIs unchanged.
Upgrade 2.31 → 2.32¶
Product version: 2.32 Date: 2026-08-17 Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Media / WebView2 harden: Field matrices + WebView2 navigation policy recipes (Pattern A/B/C) — media.md · webview2.md (2.32).
No action (compatible)¶
- Docs + Gallery callouts only; MediaPlayerElement remains experimental defer; WebView2Host stable API unchanged.
Upgrade 2.30 → 2.31¶
Product version: 2.31 Date: 2026-08-17 Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
CalendarView(experimental): always-visible month grid — single / multiple / range selection; distinct from CalendarDatePicker / DatePicker — calendar-view.md.
No action (compatible)¶
- Style
MonthGridgains optional multi/range styling; CalendarDatePicker unchanged.
Upgrade 2.29 → 2.30¶
Product version: 2.30 Date: 2026-08-17 Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Mid-2.x checkpoint: checkpoint-230 — audit 2.21…2.30; 203 catalog / 225 public types; friction triage for 2.31…2.50 (no slices dropped).
No action (compatible)¶
- Docs-only checkpoint tag; no API breaks vs 2.29.
Upgrade 2.28 → 2.29¶
Product version: 2.29 Date: 2026-08-17 Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Accessibility wave 5:
TreeDataGrid/FileTreekeyboard names + live regions;ItemsWrapGrid/BreadcrumbBaraccessibleName+announceChanges— accessibility.md wave 5 checklist.
No action (compatible)¶
- Additive a11y properties; set
announceChanges: falseonly when a host already announces the same state.
Upgrade 2.27 → 2.28¶
Product version: 2.28 Date: 2026-08-17 Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Shell trim diagnostics:
NavigationViewexposessameKeySkipCount/samePageSkipCount;NavigationWindowforwards cache aliases +clearPageCache()— performance.md wave 6 checklist + advisory smoke timings.
No action (compatible)¶
- Additive counters; navigation behavior unchanged.
Upgrade 2.26 → 2.27¶
Product version: 2.27 Date: 2026-08-17 Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Notification center: Experimental
NotificationCenterdrawer (grouped history, mark read, clear) + Gallery page with InfoBadge bell, ProgressRing save path, TeachingTip — feedback.md wave 3 (FL-007).
No action (compatible)¶
- Additive experimental control; ToastHost / InfoBar unchanged.
Upgrade 2.25 → 2.26¶
Product version: 2.26 Date: 2026-08-17 Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Charts recipe wave: Gallery Charts deferred sibling chooser + stacked-area compose; charts.md Recipe wave (2.26) — stable six unchanged.
No action (compatible)¶
- No new stable chart names; deferred types remain experimental.
Upgrade 2.24 → 2.25¶
Product version: 2.25 Date: 2026-08-17 Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Industry templates: Gallery Registration, Admin CRUD, and Preferences template pages — forms.md 2.25 section; Forms & settings hub links.
- MultiSelectComboBox:
errorMessage/hasError/formBoundfor FormLayout validation parity.
No action (compatible)¶
- MultiSelectComboBox remains API-compatible; header now renders above the field (not only inside the popup).
Upgrade 2.23 → 2.24¶
Product version: 2.24 Date: 2026-08-17 Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- ItemsWrapGrid: Model-driven variable-size wrap (
WrapPanel+filterText) — Gallery ItemsWrapGrid, items-wrap-grid.md.
No action (compatible)¶
- New experimental control only; WrapPanel / ItemsRepeater unchanged.
Upgrade 2.22 → 2.23¶
Product version: 2.23 Date: 2026-08-17 Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- BreadcrumbBar integration:
NavigationView.breadcrumbModelForKey/selectBreadcrumbIndexkeep crumbs aligned with nav selection; NavigationWindow exposes the same helpers and optionalsyncSubtitleFromNavigation— navigation.md 2.23 section, Gallery BreadcrumbBar page.
No action (compatible)¶
- Additive APIs on NavigationView, NavigationWindow, and BreadcrumbBar; defaults unchanged (
syncSubtitleFromNavigationstaysfalse).
Upgrade 2.21 → 2.22¶
Product version: 2.22 Date: 2026-08-17 Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Dashboard layout: Responsive KPI/chart breakpoints + optional
TwoPaneViewfilter rail —examples/dashboard, Gallery Dashboard, charts.md 2.22 section.
No action (compatible)¶
- No new stable chart names; layout recipe only.
Upgrade 2.20 → 2.21¶
Product version: 2.21 Date: 2026-08-17 Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- TreeDataGrid (experimental):
import QWinUI3.Extras— hierarchical multi-column grid with sort/filter; Gallery TreeDataGrid page; tree-data.md.
No action (compatible)¶
- Component QML APIs unchanged except new experimental
TreeDataGrid.
Upgrade 2.19 → 2.20¶
Product version: 2.20 Date: 2026-08-17 Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Gallery full locale switch:
GalleryLanguage— Settings → Display language or i18n / RTL page; persistsGallery/uiLocale; startup--lang zh_CN. Release embeds.qmviaqt_add_translations. See i18n-rtl.md. - Horizon checkpoint: checkpoint-220 — tranche-1 audit; 2.21+ per friction table.
No action (compatible)¶
- Component QML APIs unchanged; no CMake breaking changes vs 2.19.
Upgrade 2.18 → 2.19¶
Product version: 2.19 Date: 2026-08-17 Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Docs & catalog refresh: Regenerate component API —
python scripts/generate_component_docs.py. Critical smoke adds MultiWindowPage / StyleSpotCheckPage.python scripts/smoke_gallery.py2.19.
No action (compatible)¶
- Component QML APIs unchanged; docs index counts may drift until you regenerate locally.
Upgrade 2.17 → 2.18¶
Product version: 2.18 Date: 2026-08-17 Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Performance wave 5:
DataTable/ListDetailsViewmaxFilterResults; ListDetailsView selection survives filter by object identity;NavigationView.pageCacheHits. performance.md 2.18 section.
No action (compatible)¶
- Defaults preserve prior filter behavior (
maxFilterResults: 0= unlimited).
Upgrade 2.16 → 2.17¶
Product version: 2.17 Date: 2026-08-17 Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Style polish:
Theme.bgControlRest,Theme.borderedControlFill(),Theme.fillSliderThumb; Style controls use shared fill tokens. Gallery Style spot-check. style-polish.md · theme-overrides.md.
No action (compatible)¶
- Visual-only Style token migration; public control APIs unchanged.
Upgrade 2.15 → 2.16¶
Product version: 2.16 Date: 2026-08-17 Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Command & search wave 2:
CommandPalette.filterDebounceMs/maxResults; AutoSuggestBox / SearchBoxfilterDebounceMs/maxSuggestionResults+ field-first ↑↓ keyboard. commands.md · search.md 2.16 sections.
No action (compatible)¶
- Existing palette / suggest callers gain debounced filtering automatically; defaults preserve prior UX timing.
Upgrade 2.14 → 2.15¶
Product version: 2.15 Date: 2026-08-17 Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- High-DPI wave 3:
WindowHelper.highDpiScaleFactorRoundingPolicy();screensInfo()[].fractionalScale; Gallery High-DPI & monitors per-monitor soak. high-dpi.md 2.15 section.
No action (compatible)¶
- Existing geometry restore /
screensInfo()callers gain optionalfractionalScalefield; no schema break.
Upgrade 2.13 → 2.14¶
Product version: 2.14 Date: 2026-08-17 Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Multi-window harden:
WindowHelper.ensureWindowCreated, hardenedsetTransientParent,centerOnOwner; preferDialogShellWindow.openDialog(owner)/DialogWindow.openDialog(owner). window-shells.md 2.14 checklist.
No action (compatible)¶
- Existing
openDialogcallers gain realize + owner-screen centering automatically.
Upgrade 2.12 → 2.13¶
Product version: 2.13 Date: 2026-08-17 Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Security wave 2: security-trust.md — WebView2 navigation policy patterns;
FileDropZone.acceptMimeTypes; Wayland portal regression checklist. Gallery WebView2 URL field uses demo allowlist.
No action (compatible)¶
acceptMimeTypesdefaults empty — behavior unchanged vs 2.12 when unset.
Upgrade 2.11 → 2.12¶
Product version: 2.12 Date: 2026-08-17 Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Localization wave 3: i18n-rtl.md Consumer lrelease recipe (2.x) —
qt_add_translations,QTranslatorbefore QML, package layout. Gallery seedko_KR;examples/gallery-shelldemo with--lang ko_KR.
No action (compatible)¶
- No API breaks. Apps without
.ts/.qmstay English.
Upgrade 2.10 → 2.11¶
Product version: 2.11 Date: 2026-08-17 Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- vcpkg / Conan ports: packaging-vcpkg-conan.md — overlay
ports/qwinui3/(x64-windows·x64-linux) and Conan 2 recipe; samefind_package(QWinUI3 CONFIG)layout as shared zips. FL-003 partial — 2.02 still scheduled for primary Path C productize.
No action (compatible)¶
- Zip /
add_subdirectoryconsumers unchanged. Ports do not vendor Qt.
Upgrade 2.09 → 2.10¶
Product version: 2.10 Date: 2026-08-17 Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Mid-2.x checkpoint: checkpoint-210 audits 2.00…2.10 — confirms 2.03…2.09 shipped on the 1.xx floor; 2.00 / 2.01 / 2.02 remain planned; no breaking code.
No action (compatible)¶
- No API, CMake, or Qt floor changes. Stay on 2.09 until ready — this tag is docs-only for consumers.
Upgrade 2.08 → 2.09¶
Product version: 2.09 Date: 2026-08-17 Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Media verdict: media.md closes the 1.67 promote loop —
MediaPlayerElementpermanently deferred (experimental). App-owned Multimedia plugins/codecs. No API break.
No action (compatible)¶
- Apps already gating on
available === falseneed no changes.
Upgrade 2.07 → 2.08¶
Product version: 2.08 Date: 2026-08-17 Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Charts compose: charts.md finalizes Area→
LineChart.showArea, Spark→KpiTile.trendValues, and permanent defer for sibling charts/gauges. Stable six unchanged — no API breaks.
No action (compatible)¶
- Product dashboards on the stable six need no code changes.
Upgrade 2.06 → 2.07¶
Product version: 2.07 Date: 2026-08-17 Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Accessibility wave 4:
DataTable,ListDetailsView, andNavigationViewexposeannounceChanges(default true) and callAccessible.announceon Qt 6.8+ for selection / sort / filter / nav / pane changes. SetannounceChanges: falseto opt out. accessibility.md.
No action (compatible)¶
- No breaking API changes.
Upgrade 2.05 → 2.06¶
Product version: 2.06 Date: 2026-08-17 Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- FileTree (experimental):
import QWinUI3.Extras— Explorer folderTreeView+ fileDataTable; Gallery FileTree page; tree-data.md.
No action (compatible)¶
- No breaking changes.
FileTreeis experimental — not in stable-api promote table.
Upgrade 2.04 → 2.05¶
Product version: 2.05 Date: 2026-08-17 Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Title-bar cookbook: title-bar-cookbook.md documents
StandardTitleChrome/ShellWindowheader slots,PlatformTitleBar.rightHeaderplacement, and NC hit-test troubleshooting.
No action (compatible)¶
- No API or CMake breaking changes.
Upgrade 2.03 → 2.04¶
Product version: 2.04
Date: 2026-08-17
Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Runtime diagnostics:
FrameStatsMonitor.showRhiappends active RHI label beside FPS inFrameStatsBadge/FrameStatsOverlay. Settings Show RHI; CLI--show-rhi,--show-diagnostics. performance.md.
No action (compatible)¶
- Windows / Linux shell paths unchanged. Opt-in only; defaults unchanged (
enabledfalse,showRhifalse).
Upgrade 2.02 → 2.03¶
Product version: 2.03
Date: 2026-08-17
Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Linux client shell wave 2: compositor profile shadow tuning (
shellCompositorProfile,shellShadowOpacity);WindowShellDecoration_Simplewhen kit built without QuickEffects;WindowShellContentClip/shellContentInset()for bottom-corner content bleed. platform-linux-wayland.md.
No action (compatible)¶
- Windows DWM path unchanged. Theme / stable control APIs unchanged.
Upgrade 1.90 → 2.00 (draft)¶
Status: Draft only — breaks ship in 2.00, not in 1.90. Inventory finalized in checkpoint-190.
Product version target: 2.00
Qt: floor 6.8 LTS (drop 6.5); forward 6.10+ OK — qt-version-compat.md
Action required (at 2.00)¶
| Area | Change | What to do |
|---|---|---|
| Qt | Minimum 6.8 | Raise CI / installer Qt; rebuild Release; re-run deploy (windeployqt / linuxdeploy) |
| Theme tokens | Collapse duplicate stroke/focus aliases (exact list in 2.00 release notes) | Grep your app for legacy focus/stroke names; apply remap table from 2.00 tag |
| Shell aliases | Remove Gallery-era compatibility aliases | Prefer NavigationWindow / StandardWindow / documented Extras shells — window-shells.md |
| Experimental types | Still experimental after 2.01 OSK may be promoted, moved, or removed | Pin 1.90 if you depend on undocumented experimental APIs |
Optional / polish¶
- Skim performance.md arc (1.86…1.89) before tuning on the new floor.
- OSK / IME promote and consumer packaging: 2.01+, not 2.00 by default — ROADMAP.md.
Stay on 1.90 if¶
- You must keep Qt 6.5 in production.
- You need the current 2.xx Theme / shell names without a migration window.
Upgrade 2.60 → 3.00 (draft)¶
Status: Draft only — breaks ship in 3.00, not in 2.60. Inventory refined at 2.73 + checkpoint-300.
Product version target: 3.00
Qt: floor 6.10 LTS (drop 6.8 shim path); forward 6.12+ OK — qt-version-compat.md
Action required (at 3.00)¶
| Area | Change | What to do |
|---|---|---|
| Qt | Minimum 6.10 | Raise CI / installer Qt; rebuild Release; re-run deploy |
| Deferred charts/gauges | Sibling types removed from default import or moved to experimental module | Migrate to stable six + compose — charts.md |
| Media | MediaPlayerElement not on default stable surface | App-owned Multimedia — media.md |
| Theme | Remaining 2.x stroke/focus aliases removed | Grep legacy names; apply 3.00 remap table |
| Shell | Undocumented Gallery-era window aliases removed | window-shells.md |
| CMake / PyPI | find_package(QWinUI3 CONFIG) primary; PyPI 3.00 if 2.72 shipped |
packaging-consumer.md |
Optional / polish (plan now — ship later)¶
- Complete 2.61…2.73 professional + Python tranche before pinning 3.00.
- Skim performance.md 2.x waves before tuning on Qt 6.10.
- Read compatibility-3xx.md when it ships.
Stay on 2.60 if¶
- You are mid 2.61…2.73 adoption and cannot absorb a major yet.
- You must keep Qt 6.8 in production until 2.73.
Upgrade 2.73 → 3.00 (draft)¶
Status: Draft only — breaks ship in 3.00, not in 2.73. Inventory finalized in checkpoint-300.
Product version target: 3.00
Qt: floor 6.10 LTS (drop 6.8 shim path); forward 6.12+ OK — qt-version-compat.md
Action required (at 3.00)¶
| Area | Change | What to do |
|---|---|---|
| Qt | Minimum 6.10 | Raise CI / installer Qt; rebuild Release; re-run deploy |
| Deferred charts/gauges | Sibling types removed from default import or moved to experimental module | Migrate to stable six + compose — charts.md |
| Media | MediaPlayerElement not on default stable surface | App-owned Multimedia — media.md |
| Theme | Remaining 2.x stroke/focus aliases removed | Grep legacy names; apply 3.00 remap table |
| Shell | Undocumented Gallery-era window aliases removed | window-shells.md |
| CMake / PyPI | find_package(QWinUI3 CONFIG) primary; PyPI 3.00 if 2.72 shipped |
packaging-consumer.md |
Optional / polish¶
- Skim performance.md 2.x summary before tuning on Qt 6.10.
- Read compatibility-3xx.md for the 3.xx freeze.
Stay on 2.73 if¶
- You must keep Qt 6.8 in production.
- You depend on permanent defer chart/gauge siblings without migration time.
- You use experimental APIs not promoted by 2.45 / 2.67.
Upgrade 1.89 → 1.90¶
Product version: 1.90
Date: 2026-08-17
Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- 1.xx close-out: checkpoint-190 — docs audit, perf arc sign-off, 2.00 prep draft (no breaking code).
- Performance arc: all four waves (1.86…1.89) documented in performance.md; smoke timing remains advisory —
python scripts/smoke_gallery.py.
No action (compatible)¶
- Theme / shell / stable control APIs unchanged. 1.xx freeze ends at 2.00, not at 1.90. Next planned major: 2.00 (after this tag).
Upgrade 1.88 → 1.89¶
Product version: 1.89
Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Performance wave 4 (style/charts): ElevatedChrome shadow defer; Style idle Behavior trim; chart reveal budget + coalesced redraw; Gallery heavy-page deferrals. performance.md.
No action (compatible)¶
- Theme / shell API unchanged. Interaction animations unchanged. Next: 1.90 close-out.
Upgrade 1.87 → 1.88¶
Product version: 1.88
Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Performance wave 3 (lists):
DataTabledebounces filter rebuilds;ItemsView/ListDetailsView/ItemsRepeateroptionalfilterTexton JS arrays. performance.md.
No action (compatible)¶
- Theme / shell API unchanged. Animations unchanged. Next: 1.89 style/charts perf wave.
Upgrade 1.86 → 1.87¶
Product version: 1.87
Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Performance wave 2 (navigation):
NavigationViewStackView transitions skip no-op x/y/scale animators per mode (slide/fade look the same). Compact flyout defers shadow until open.TabViewidle tab strip behaviors trimmed. Gallery Settings Performance arc card. performance.md.
No action (compatible)¶
- Theme / shell API unchanged. Pane collapse animation unchanged. Next: 1.88 lists perf wave.
Upgrade 1.85 → 1.86¶
Product version: 1.86
Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Performance wave 1 (shell): Solid
StandardWindowhosts clear with layer fill (notQt::white); WindowsDWMWA_BORDER_COLORmatches fill; Solid windows skip focus-in DWM timer bursts (restore feels snappier). performance.md · window-chrome.md.
No action (compatible)¶
- Theme / shell API unchanged. OSK stays experimental. Next: 1.87 navigation perf wave.
Upgrade 1.84 → 1.85¶
Product version: 1.85
Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- ContentDialog / Flyout / CommandBarFlyout return focus to the opener on close. InfoBar announces on open (
Accessible.announceon Qt 6.8+). ImeCandidateBar announces candidates without taking focus. Gallery Accessibility wave 3 sample. accessibility.md.
No action (compatible)¶
- Theme / shell / stable control APIs unchanged. OSK stays experimental.
Upgrade 1.83 → 1.84¶
Product version: 1.84
Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Copy
examples/floating-oskforOnScreenKeyboardWindow(not the Gallery). Keyman Core is inthird_party/keymanwith the clone. on-screen-keyboard.md.
No action (compatible)¶
- Theme / shell / stable controls unchanged. OSK stays experimental.
Upgrade 1.82 → 1.83¶
Product version: 1.83
Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Experimental OSK: floating host no-activate soak (
WM_MOUSEACTIVATE/ noraise()); long-press flyout stays in-window on Qt 6.8+. Gallery checklist vs dock. Honest limits: elevated / UIPI / UWP / games may ignoreSendInput. on-screen-keyboard.md.
No action (compatible)¶
- Theme / shell / stable controls unchanged. OSK stays experimental. Docked
systemWidestill defaults off.
Upgrade 1.81 → 1.82¶
Product version: 1.82
Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Experimental OSK:
OnScreenKeyboardWindowfloating host; WindowsSendInputinto the focused desktop app (systemWide, default on for the floating window; dock stays off). on-screen-keyboard.md. - Gallery: removed unused
--visual-smoke/scripts/smoke_visual.py(1.62 opt-in subset). CI--smokeunchanged.python scripts/smoke_gallery.py.
No action (compatible)¶
- Theme / shell / stable controls unchanged. OSK stays experimental. Docked
OnScreenKeyboard.systemWidestill defaults off.
Upgrade 1.80 → 1.81¶
Product version: 1.81
Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Experimental OSK: Windows 11 behavior (not Win10 classic) — long-press digit hints + punctuation alt flyout,
keyboardSizeSmall/Default/Large, clipboard strip, emoji category chips, rounder press-scale keys. on-screen-keyboard.md.
No action (compatible)¶
- Theme / shell / stable controls unchanged. OSK stays experimental.
Upgrade 1.79 → 1.80¶
Product version: 1.80
Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Experimental OSK: Win11 default touch layout chrome (Esc/Tab/dual Shift, lang chip 英/中/あ/한, number hints, settings/grab/close).
navigateKey/pasteClipboardonKeyboardEngine. on-screen-keyboard.md.
No action (compatible)¶
- Theme / shell / stable controls unchanged. OSK stays experimental. Mic / Win keys remain chrome-only.
Upgrade 1.78 → 1.79¶
Product version: 1.79
Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Linux / Wayland: stronger portal
parent_window(QtportalWindowIdentifierwhen GuiPrivate is available; window realized before export); Bootstrap detectsWAYLAND_SOCKET; experimental OSK CapsLock tracking on Linux. platform-linux-wayland.md.
No action (compatible)¶
- Theme / shell / stable controls unchanged. OSK stays experimental. Rebuild Linux kits with
qt*-private-dev/ GuiPrivate for the best Wayland parent export.
Upgrade 1.77 → 1.78¶
Product version: 1.78
Qt: unchanged (6.5+ / recommended 6.8)
Docs / posture¶
- Long-horizon checkpoint: checkpoint-178. Prefer field harden / pause vs new surfaces;
1.79+only for field-driven P0s or park. OSK/IME stays experimental (not promoted in 1.74 / 1.76 / 1.77).
No action (compatible)¶
- Theme / shell / stable controls unchanged. Freeze (1.40) still active.
Upgrade 1.76 → 1.77¶
Product version: 1.77
Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Experimental OSK:
hardwareInput(default on) routes physical keyboard keys in this app through the same engine as the dock. Not OS-wide. on-screen-keyboard.md.
No action (compatible)¶
- Existing Theme / shell / stable controls unchanged. OSK stays experimental. Set
hardwareInput: falseto leave keys to the system IME.
Upgrade 1.75 → 1.76¶
Product version: 1.76
Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Experimental OSK IME deepen (MIT-only): pinyin prefix phrases + regenerated tables; hangul compound peel / Space word-break; Japanese stays kana — kanji skipped (no MIT lexicon). on-screen-keyboard.md · NOTICE-pinyin.md.
No action (compatible)¶
- Existing Theme / shell / stable controls unchanged. OSK stays experimental.
Upgrade 1.74 → 1.75¶
Product version: 1.75
Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Experimental OSK: more Keyman layouts — English (UK), Italiano, Português, Polski, Svenska, Türkçe. Re-fetch with
python scripts/fetch_keyman_keyboards.py. on-screen-keyboard.md · NOTICE-Keyman.md.
No action (compatible)¶
- Existing Theme / shell / stable controls unchanged. OSK stays experimental.
Upgrade 1.73 → 1.74¶
Product version: 1.74
Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Experimental OSK soak: Gallery language-matrix checklist, candidate-bar a11y, romaji trailing-
n/ small kana. Still experimental — not promoted. on-screen-keyboard.md.
No action (compatible)¶
- Existing Theme / shell / stable controls unchanged. OSK stays experimental.
Upgrade 1.72 → 1.73¶
Product version: 1.73
Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Experimental OSK: 日本語 (romaji→kana) and 한국어 (2-beolsik hangul) share
ImeCandidateBar. Emoji layer has no engine. Keyman Core is still layouts only. on-screen-keyboard.md.
No action (compatible)¶
- Existing Theme / shell / stable controls unchanged. OSK stays experimental.
Upgrade 1.71 → 1.72¶
Product version: 1.72
Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Experimental OSK: switch to 中文 for in-app pinyin (
ImeCandidateBar). Lexicon is MIT pinyin-data, not Microsoft Pinyin. on-screen-keyboard.md · NOTICE-pinyin.md.
No action (compatible)¶
- Existing Theme / shell / stable controls unchanged. OSK stays experimental.
Upgrade 1.70 → 1.71¶
Product version: 1.71
Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Experimental
OnScreenKeyboardnow feeds SIL Keyman Core (MIT, static). Globe / ComboBox switches en/de/fr/es/ru/ar.kmx. on-screen-keyboard.md · NOTICE-Keyman.md. - Configure fetches Core into gitignored
third_party/keyman(scripts/fetch_keyman_core.py,QWINUI3_FETCH_KEYMAN). Without it,engine.backendstays"builtin". - Still not Qt Virtual Keyboard;
QT_IM_MODULEstays unset.
No action (compatible)¶
- Existing Theme / shell / stable controls unchanged. OSK stays experimental.
Upgrade 1.69 → 1.70¶
Product version: 1.70
Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Experimental
OnScreenKeyboarddock +KeyboardEngine(en-US). Host in a shell footer /CatalogPage.footer. on-screen-keyboard.md. - Do not enable Qt Virtual Keyboard;
QT_IM_MODULEstays unset.
No action (compatible)¶
- Existing Theme / shell / stable controls unchanged. OSK is additive and experimental.
Upgrade 1.68 → 1.69¶
Product version: 1.69
Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Theme knobs are kit-wide: drop
ThemeAppearanceSettingson your Settings page; copyTheme.recipeText()into another app. Shells runThemeSync(follow system a11y / color). theme-overrides.md. - Persist Theme with
ThemePrefs(persist: true) — keep geometry ongeometryPersistenceKey.
No action (compatible)¶
- Existing
Theme.dark/followSystem*assignments still work. Gallery Main no longer special-cases OS sync.
Upgrade 1.67 → 1.68¶
Product version: 1.68
Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Linux portal harden: platform-linux-wayland.md / system-integration.md — FilePicker no longer falls back to zenity after a portal timeout; filters + save
current_name; reveal OpenURI fallback;WindowHelper.portalParentWindow(). - Gallery System integration live
parent_windowreadout.
No action (compatible)¶
- FilePicker QML signatures unchanged. Pass
Window.windowas before.
Upgrade 1.66 → 1.67¶
Product version: 1.67
Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Media cookbook: media.md — soak checklist + honest defer for remaining 1.xx (
MediaPlayerElementstays experimental). - Gallery MediaPlayerElement decision callout.
No action (compatible)¶
- No promote; stub / real player behavior unchanged. Apps already using Multimedia keep the same API.
Upgrade 1.65 → 1.66¶
Product version: 1.66
Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Charts cookbook: charts.md — remaining siblings/gauges deferred for remaining 1.xx (prefer Line/Bar/Donut + RingGauge + KpiTile + ChartCard).
- Gallery Charts / Dashboard hubs split stable vs deferred;
examples/dashboardnow uses all six stable types.
No action (compatible)¶
- Stable six unchanged; no new chart engine. Deferred types still ship (experimental).
Upgrade 1.64 → 1.65¶
Product version: 1.65
Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Settings persistence cookbook: settings-persistence.md —
Settings/ QSettings, portable Ini, honest “roaming”,schemaVersion; keep geometry ongeometryPersistenceKey. - Gallery Settings persistence; examples
form-settings+gallery-shellprefs.
No action (compatible)¶
- Docs + Gallery / example patterns only; no Theme or shell API breaks.
Upgrade 1.63 → 1.64¶
Product version: 1.64
Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Security & trust cookbook: security-trust.md — WebView2 user-data / app-side URL allowlists, FileDropZone filters, FilePicker ownership (not a sandbox product).
- Gallery Security & trust + Pitfalls / WebView2 / FileDropZone callouts.
No action (compatible)¶
- Docs + Gallery only; WebView2Host / FileDropZone APIs unchanged.
Upgrade 1.62 → 1.63¶
Product version: 1.63
Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Print / share / export cookbook: print-share.md — grabToImage → FilePicker.saveFile → revealFileInFolder; optional app-side PrintSupport.
- Gallery Print / share / export interactive demo.
No action (compatible)¶
- Docs + Gallery only; no new kit PrintSupport dependency.
Upgrade 1.61 → 1.62¶
Product version: 1.62
Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Visual smoke subset:
python scripts/smoke_visual.py --build-dir build(Gallery--visual-smoke);python scripts/smoke_gallery.py. - Not part of default
smoke_gallery.py— keep CI fast. Hash--compareis best-effort.
No action (compatible)¶
- Default
--smokepath unchanged.
Upgrade 1.60 → 1.61¶
Product version: 1.61
Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
find_package(QWinUI3 CONFIG)sketch: packaging-consumer.md Path C; shared zips shiplib/cmake/QWinUI3/+include/QWinUI3/Bootstrap.h.- Tiny consumer:
examples/find-package-consumer/; verify withpython scripts/verify_find_package.py. - Not an official vcpkg/Conan port.
No action (compatible)¶
- Existing Path A /
add_subdirectoryflows unchanged; Config is additive in packages.
Upgrade 1.59 → 1.60¶
Product version: 1.60
Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Mid-horizon checkpoint: checkpoint-160 — still 1.xx; 1.61+ order confirmed.
- Gallery Pitfalls mid-horizon checklist; smoke critical pages include Search recipes + High-DPI.
No action (compatible)¶
- Docs / Gallery / smoke list only; APIs unchanged.
Upgrade 1.58 → 1.59¶
Product version: 1.59
Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- In-app search cookbook: search.md — AutoSuggestBox / SearchBox / filter-above vs CommandPalette.
- Gallery Search recipes interactive demo; AutoSuggest / SearchBox / commands cross-links.
No action (compatible)¶
- Docs + Gallery only; existing controls unchanged.
Upgrade 1.57 → 1.58¶
Product version: 1.58
Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- High-DPI / multi-monitor cookbook: high-dpi.md; Gallery High-DPI & monitors readout.
- Geometry restore now
setScreens after clamp so mixed-DPI DPR updates (window-helper.md).
No action (compatible)¶
- Additive restore behavior + docs; existing keys unchanged.
Upgrade 1.56 → 1.57¶
Product version: 1.57
Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Touch / pen cookbook: touch-pointer.md — target floors, scroll vs drag, stylus hover notes.
- Gallery Touch & pointer page + callouts on Button / Slider / Nav / FileDropZone / SwipeControl; density & a11y cross-links.
No action (compatible)¶
- Docs + Gallery only; no new input stack.
Upgrade 1.55 → 1.56¶
Product version: 1.56
Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Multi-window recipe: secondary
ToolShellWindow/ ownedDialogShellWindow, distinctgeometryPersistenceKeys, shared Theme — window-shells.md. - Runnable
examples/multi-window; Gallery Multi-window page.
No action (compatible)¶
- Additive example + docs; existing single-window shells unchanged.
Upgrade 1.54 → 1.55¶
Product version: 1.55
Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Gallery Onboarding coach — sequenced
TeachingTips, focus handoff, “don’t show again” viaQtCore.Settings— feedback.md. - Cross-links in keyboard.md / dialogs-flyouts.md.
No action (compatible)¶
- Recipe-only; no new required control family.
Upgrade 1.53 → 1.54¶
Product version: 1.54
Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Second Gallery seed locale
ja_JPalongsidezh_CN— i18n-rtl.md; Gallery i18n page locale ComboBox +--langcopy.
No action (compatible)¶
- Additive seed + docs; no API breaks.
Upgrade 1.52 → 1.53¶
Product version: 1.53
Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Experimental
AnimatedIconfor glyph state swaps — icons.md. UsecheckedoriconState/iconStates(not Qt QuickItem.state). - Gallery AnimatedIcon page; honors
Theme.reducedMotion.
No action (compatible)¶
- Additive experimental type; no Lottie dependency.
Upgrade 1.51 → 1.52¶
Product version: 1.52
Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Local/CI smoke now also loads
FontIconPage/PitfallsPage/ExamplesTemplatesPageas critical pages —python scripts/smoke_gallery.py. - No open field P0s were reported after 1.51; this buffer shipped CI/docs harden instead of skipping.
No action (compatible)¶
- Additive smoke coverage only.
Upgrade 1.50 → 1.51¶
Product version: 1.51
Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Read maturity-1xx.md — stay on 1.xx; prefer harden /
gallery-shell/ stable-api. - Freeze doc revisited: compatibility-1xx.md (still the merge gate).
No action (compatible)¶
- Docs + Gallery Pitfalls checklist only; no API renames.
Upgrade 1.49 → 1.50¶
Product version: 1.50
Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Prefer
examples/gallery-shellas the product app frame (keep-vs-delete in its README). NavigationWindownow exposespageModule/hostContent/pageTransition/navigateBack()for Gallery-style StackView pages.
No action (compatible)¶
- Default
hostContent: true+content:slot unchanged for existing NavigationWindow demos.
Upgrade 1.48 → 1.49¶
Product version: 1.49
Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Glyph hover/press micro-motion on
FontIcon/IconButton/AppBarButton— see icons.md. - Opt out with
microMotionEnabled: false; tunehoverScale/pressScale. - Gallery Iconography micro-motion strip + IconButton / AppBarButton pages.
No action (compatible)¶
- Defaults are additive;
Theme.reducedMotionstill forces scale1. - IconButton no longer scales the whole control — only the glyph (visual polish).
Upgrade 1.47 → 1.48¶
Product version: 1.48
Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Follow dialogs-flyouts.md for 2+ queued dialogs, owner
Overlay.overlay, and Esc/onClosingpatterns. - Gallery ContentDialog page: Enqueue A → B → C stress demo (critical smoke).
Action required (behavior fix)¶
| Area | Change | What to do |
|---|---|---|
ContentDialogQueue.replaceCurrent |
No longer pumps the pending queue while replacing | If you relied on the old race (pending opening mid-replace), switch to explicit show() after close |
No action (compatible)¶
- FIFO
show()/cancel/clearQueuesemantics unchanged for the common path.
Upgrade 1.46 → 1.47¶
Product version: 1.47
Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Follow shell-extras.md for Snap Layouts toggle, taskbar export loop, and attention/reveal patterns.
- Gallery System integration page hosts the demos (critical smoke).
No action (compatible)¶
- Additive docs + Gallery UX; stable taskbar / attention / reveal / idle APIs unchanged. Snap Layouts remains experimental.
Upgrade 1.45 → 1.46¶
Product version: 1.46
Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Follow packaging-consumer.md shared vs static matrix, windeploy/linuxdeploy, and strip-restricted steps.
No action (compatible)¶
- Additive docs + smoke check; archive layout and CMake targets unchanged.
Upgrade 1.44 → 1.45¶
Product version: 1.45
Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Use i18n-rtl.md for lupdate/lrelease and Gallery
--lang zh_CNafter generating.qm. - Gallery
--lang zh_CNafter generating.qm— i18n-rtl.md.
No action (compatible)¶
- Additive docs + optional CLI; no default language auto-switch.
Upgrade 1.43 → 1.44¶
Product version: 1.44
Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Follow keyboard.md for Ctrl+K / dialog Esc-Enter / list arrows end-to-end.
- Gallery Accessibility page hosts the keyboard tour checklist.
No action (compatible)¶
- Docs + Gallery callouts; existing CommandPalette / dialog APIs unchanged.
Upgrade 1.42 → 1.43¶
Product version: 1.43
Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Use
Theme.contrastRatio/contrastPassesAAwhen pickingcustomAccent— color-contrast.md. - Gallery Theme overrides shows a live AA table.
No action (compatible)¶
- Additive Theme helpers + docs; existing branding knobs unchanged.
Upgrade 1.41 → 1.42¶
Product version: 1.42
Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Use adaptive-layout.md for TwoPaneView / ListDetailsView / Nav
autobreakpoints. - Prefer documented defaults (
minWideWidth: 720,autoCompactThreshold: 1008).
No action (compatible)¶
- Additive docs + Gallery; existing TwoPane / ListDetails APIs unchanged.
Upgrade 1.40 → 1.41¶
Product version: 1.41
Qt: unchanged (6.5+ / recommended 6.8)
Optional / polish¶
- Prefer drag-drop.md for FileDropZone + FilePicker browse + CopyButton /
WindowHelperclipboard. - Gallery FileDropZone / CopyButton pages updated.
No action (compatible)¶
- Additive docs + Gallery;
FileDropZone/CopyButton/ clipboard helpers unchanged in shape.
Upgrade 1.39 → 1.40¶
Product version: 1.40
Qt: unchanged (6.5+ / recommended 6.8)
Action required¶
| Area | Change | What to do |
|---|---|---|
| Docs gate | Published compatibility-1xx.md | Prefer frozen Theme / shell / stable APIs for new code; treat this doc as the 1.4x gate |
Optional / polish¶
- Link your internal “supported kit” page to compatibility-1xx + stable-api.
- Gallery Pitfalls page points at the freeze (no API change).
No action (compatible)¶
- No Theme token renames, no shell API removals, no stable control breaks in 1.40.
Upgrade 1.38 → 1.39¶
Product version: 1.39
Optional / polish¶
- Apps using
NavigationViewpage stacks: considerpageCacheLimit(default 24) andinitialPageTransition: "none"for cold start — performance.md. clearPageCache()available after long browse sessions.
No action (compatible)¶
- Existing NavigationView call sites keep working; cache limit only evicts least-recently-used Components (not a public type rename).
Upgrade 1.37 → 1.38¶
Product version: 1.38
Optional / polish¶
- Linux field hosts: read platform-linux-wayland.md failure matrix (SSD, portal parent, SNI).
No action (compatible)¶
- Docs / Gallery System integration callouts only.
When we would break (2.00 territory)¶
Examples that do not belong in a quiet 1.xx:
- Renaming
Theme.bgCardor stableNavigationView.openPage - Dropping Qt 6.5 without a named roadmap decision
- Removing a type listed as Stable on stable-api without a deprecation window
Track those under the 2.00 plan in ROADMAP.md (after 1.90). Draft remap table: upgrade-notes.md Upgrade 1.90 → 2.00 (draft) and checkpoint-190; the breaks land in 2.00. Apps that cannot leave Qt 6.5 stay on 1.90.
3.00 territory (after 2.73): Qt 6.10 floor, experimental cleanup, final Theme/shell alias removal — draft in upgrade-notes.md Upgrade 2.73 → 3.00 (draft) and checkpoint-300. Apps that cannot leave Qt 6.8 stay on 2.73.