Performance handbook (1.25 / 1.39 / 1.86–1.89 / 2.18 / 2.28 / 2.40 / 2.49 / 2.59 / 3.34)¶
Practical guidance for large lists, DataTable, Canvas charts, and Gallery cold start. QWinUI3 virtualizes through Qt Quick Controls ListView — there is no separate engine. Prefer these patterns before blaming the kit.
Gallery: DataTable (heavy-page callout) · ItemsView · ItemsRepeater · Charts · Settings → Page Component cache.
Related: data-collections.md · charts.md · animations.md · python scripts/smoke_gallery.py.
Quick checklist¶
| Do | Avoid |
|---|---|
ListView / ItemsView / DataTable / ItemsRepeater with reuseItems |
Full-height Column + Repeater for thousands of rows |
QAbstractListModel (C++) for thousands+ rows |
Rebuilding huge JS arrays on every keystroke |
| Stable role names on model objects | Deep nested Qt.binding trees inside every delegate |
| Cap chart points (see below); one chart per card | Dozens of full-size Canvas charts on one screen |
Defer heavy pages (Loader / StackView push) |
Instantiating every Gallery/app page at startup |
Cap NavigationView.pageCacheLimit |
Unbounded Component caches after long browse sessions |
Honor Theme.reducedMotion for motion |
Animating the whole title bar / shell chrome |
Gallery cold start (1.39 / wave 11 — 2.70 / 3.34 S10–S11)¶
| Topic | Guidance |
|---|---|
| Critical first frame | Keep Home / shell QML lean; defer heavy catalog pages |
--startup-log |
Print wall timings for configure → first frame |
| Bootstrap RHI | Soft default only — no Vulkan/D3D probe unless QWINUI3_RHI_PROBE=1 (3.34 S10) |
| Deferred QML modules | Charts / OSK / WebView2 are separate URIs — not registered by default Bootstrap (3.35 S12) |
| Import graph | Gallery Main.qml + default examples use shell set; Extras.Charts is optional (3.36 S13) |
| Gallery catalog | Home uses a hot index (findByComponent / default recents); full _buildControls waits until after first frameSwapped (3.37 S14) |
| Icon catalog | Named FluentIcons.* glyphs load on first use; full Iconography rows deferred (3.34 S11) |
| Icon QFont | Theme.iconFontFor(px[, weight]) returns a cached PreferNoHinting QFont per size/weight (3.41 H10) — prefer over font.family: Theme.fontFamilyIcon |
| Theme font stacks | Default load builds UI stack only; Text / Display face lists resolve on first textFamilies / displayFamilies (3.42 H11); density stays formula (no metric pack tables) |
| List / Tree overscan | Kit lists set reuseItems + mild cacheBuffer (3.43 H12) — see Virtualization |
| DataTable ListView roles | Rows use lean {kind,rowIndex} wrappers — not fat business objects as model items (3.44 H13); sort key arrays only for active sortSpecs |
| Chart series buffers | Source ring caps + draw LOD documented; opt-in ChartSeries.capacity / ChartUtils.trimRing (3.45 H14) — LOD defaults unchanged |
| Gallery page unload | StackView.replace destroys off-screen trees; Gallery pageCacheLimit: **8** + pinnedPageCache: Home/Settings (3.46 H15) — kit default stays 24 |
| Image / shadow caches | QPixmapCache kit cap 16 MB (QWINUI3_PIXMAP_CACHE_KB); ElevatedChrome frees MultiEffect FBO when hidden; iconFontFor LRU 96 (3.47 H16) — acrylic/shadow look unchanged |
| Memory wave sign-off | Idle WorkingSet table filled at 3.48 H17 — checkpoint-390 (~136 MB WS avg, n=5 Win Release) |
| Paint coalesce | Experimental charts (3.49 C20); stable six inventory closed (3.54 C25) — inventory |
| Silent runtime sign-off | Warm Gallery switch p50 ≈ 146 ms (mode none, n=24) at 3.55 C26 — checkpoint-390 |
| ItemsView / ListDetailsView | Debounced filter + skip fingerprint; cacheBufferPx (3.51 C22) |
| DataTable / TreeDataGrid | Fixed rowHeight; lean-model reuse; Tree callLater + fingerprint caps (3.52 C23) |
| NavigationView pane | Structure-first sync; stable group children; flatIndex cache; expand pip coalesce (3.53 C24) |
| Binding churn | Almost no hot Qt.binding; Gallery nav assign uses incremental sync; DataTable column layout skips unchanged (3.50 C21) |
| Icon / atlas warm-up | Optional: touch FluentIcons / ThemeFonts once after first frame |
| Page cache | pageCacheLimit + pinnedPageCache (2.68); Gallery tightened in 3.46 — avoid compiling all pages at startup |
| Target budget | Aim for interactive shell < 1.5 s on CI Win Release; local desktop < 2 s — wave S10–S17 signed off at 3.40 (checkpoint-390) |
CI absolute budgets (3.39 S16)¶
python scripts/smoke_gallery.py parses Gallery --smoke app= / main= lines and fails CI when over the table below. Local runs soft-warn only unless --check-startup-budget (or QWINUI3_CHECK_STARTUP_BUDGET=1).
| Metric | Meaning | CI Win Release max | CI Linux (offscreen) max |
|---|---|---|---|
app |
Through QGuiApplication + kit configure |
800 ms | 1000 ms |
main |
Through Main.qml (interactive shell) |
1500 ms | 2000 ms |
Gate: main is the interactive-shell budget (roadmap S16). pages= / total= stay advisory (critical-page compile cost — not cold start).
Expected budget on a Release build (desktop, not a guarantee):
| Phase | What loads | Target |
|---|---|---|
| App + Bootstrap + RHI | configureEnvironment (soft RHI), GraphicsBackend |
Usually < 200–400 ms (no host probe by default) |
Main shell |
StandardWindow + NavigationView + ControlCatalog singleton + Home only |
Usually < 1–2 s wall to first paint |
| Other catalog pages | Compiled on first openPage / smoke create |
Not part of cold start |
Measure locally:
--smoke prints main=…ms, pages=…ms, total=…ms after creating the critical set only — it does not open every control page.
What Gallery already does¶
| Technique | Detail |
|---|---|
| On-demand pages | NavigationView + pageModule → Qt.createComponent per page name |
| First paint | initialPageTransition: "none" (no enter animation on Home) |
| Component LRU | Kit default pageCacheLimit: 24; Gallery uses 8 + pins Home/Settings (3.46 H15); clearPageCache() from Settings |
| Home shadows | MultiEffect deferred one frame; off when Theme.reducedMotion |
| Optional hosts | WebView2 / MediaPlayer pages use Loader until activated; WebView2 Runtime probe on Check Runtime / Go / Retry (not page Timer) (3.38 S15); Keyman Core loads on first OSK key / layout use; FrameStats frameSwapped only when FPS/RHI enabled |
| Control catalog | ControlCatalog.ensureControls() lazy cache; Home hot index so Main load does not parse the full list; left rail fills after first frame (3.37 S14 / 2.85 S1) |
| Nav model patch | NavigationView.patchNavItem(key, patch) — incremental title/badge/icon when structure unchanged (2.88 C9) |
| Theme batch apply | Theme.apply({…}) bumps tokensRevision once — bind heavy trees to revision, not every knob (2.88 C10) |
| Python Gallery | qwinui3-gallery lazy-imports Qt + Gallery types after configure_environment() (2.89 S4) |
| Smoke scope | Critical list only — python scripts/smoke_gallery.py |
Heavy pages (prefer not to touch on Home): ControlCatalog.heavyComponents() — DataTable, Charts, FontIcon, WebView2, Media, dense chart samples.
QML bytecode cache (2.85 S2)¶
qt_add_qml_module already compiles QML at build time. For shipping apps that want ahead-of-time bytecode on disk (where the toolchain supports it), run qmlcachegen on the app module after configure:
| Preset / example | URI | Typical entry QML |
|---|---|---|
| gallery-shell | QWinUI3.Examples.GalleryShell |
Main.qml |
| dashboard | QWinUI3.Examples.Dashboard |
Main.qml |
REM After Release configure (paths vary by Qt install / build tree):
qmlcachegen -i build/examples/gallery-shell/qwinui3_example_gallery_shell/qmldir ^
examples/gallery-shell/Main.qml
qmlcachegen -i build/examples/dashboard/qwinui3_example_dashboard/qmldir ^
examples/dashboard/Main.qml
Notes
- Optional — not required for Gallery or library consumers; measure with
--startup-logbefore adopting. - CI may run
qmlcachegenwhenqmlcachegenis onPATH(same guard asscripts/qwinui3.pytool probe); skip cleanly when absent. - Do not cachegen the full Gallery catalog — page QML stays on-demand via
NavigationView.pageModule.
App recipe¶
NavigationView {
pageModule: "MyApp"
pageCacheLimit: 24 // kit default; Gallery uses 8 (3.46)
pinnedPageCache: ["HomePage", "SettingsPage"] // keep hot shells warm
initialPageTransition: "none"
pageTransition: "slide" // after first page
// …
}
// After a long session:
nav.clearPageCache(true) // keep current page Component
Instance vs Component (3.46 H15): StackView.replace already destroys the previous page tree. pageCacheLimit only retains compiled Components for faster re-open — lower it on long-browse demos (Gallery) so RSS stays down; pin Home/Settings so switch time stays ≤ baseline.
Do not import every page type into Main.qml — that forces compile at startup.
Virtualization¶
| Surface | How it scrolls | Notes |
|---|---|---|
DataTable |
ListView + reuseItems + fixed rowHeight |
Lean {kind,rowIndex} model wrappers (3.44); reuse when length unchanged (3.52); cacheBufferPx / rowHeight * 12; filter/sort debounced + skip unchanged; multi-sort / hiddenColumns / columnWidths (2.66) |
ItemsView |
ListView + reuseItems |
cacheBufferPx (<0 → max(240, height * 1.5), 3.51); filterDebounceMs 120; maxFilterResults 256; optional minFilterLength |
ListDetailsView |
ListView + reuseItems |
Same cacheBufferPx / filter defaults as ItemsView (3.51); master JS-array filter |
ItemsRepeater |
ListView + reuseItems (1.25) |
cacheBuffer: Theme.navItemHeight * 8; optional filterText on JS arrays (1.88) |
NavigationView pane |
ListView (no reuseItems) |
Variable-height groups: pooling left blank gaps on collapse; mild cacheBuffer still helps SelectionPip |
FileTree / raw TreeView |
TreeView (TableView) + reuseItems |
FileTree sets the same mild buffer (3.43); raw trees should too |
TreeDataGrid |
ListView + reuseItems + fixed rowHeight |
_treeCache flatten (2.84); cacheBufferPx / rowHeight * 12 + rows callLater (3.52); _lastRefreshKey skip |
ItemsWrapGrid |
WrapPanel + Repeater (2.24) |
Not virtualized — low hundreds; optional filterText |
Raw QQC ListView |
Set reuseItems: true yourself |
Pair with a mild cacheBuffer (see table below) |
cacheBuffer recipes (3.43 H12)¶
| Pattern | Typical value | Trade-off |
|---|---|---|
| Navigation / ItemsView / FileTree / ListDetailsView | Math.max(240, Math.round(height * 1.5)) via cacheBufferPx: -1 (3.51) |
Cuts RSS vs huge buffers; still enough for fast fling |
| ItemsRepeater | Theme.navItemHeight * 8 |
Stable tile height |
| DataTable / TreeDataGrid | rowHeight * 12 via cacheBufferPx: -1 (3.52) |
Dense fixed-height rows |
| Too large | e.g. height * 10 |
RSS ↑ with little scroll gain |
Too small / 0 |
— | Fast fling shows empty bands; SelectionPip / expand can glitch |
Rule of thumb
| Row count | Guidance |
|---|---|
| ≤ a few hundred plain objects | JS arrays / ListModel are fine |
| Thousands+ | Use QAbstractListModel (or similar). Do not filter+sort the full set in JS on every keystroke |
| Tens of thousands | C++ model + keep delegates thin; consider paging / server filter |
Delegates must tolerate reuse: avoid storing per-index state on the item root without resetting in Component.onCompleted / ListView.onPooled / property bindings from model / modelData.
ItemsView {
titleRole: "name"
subtitleRole: "team"
model: employeeModel // prefer QAbstractListModel when large
}
Model roles¶
Prefer named roles (or plain object keys matching roles) so delegates stay binding-driven:
// Good — role-driven
ListTile {
title: model.name
subtitle: model.team
}
// DataTable columns
columns: [
{ title: qsTr("Name"), role: "name", width: 160, sortable: true },
{ title: qsTr("Score"), role: "score", width: 90, sortable: true }
]
| Tip | Detail |
|---|---|
| Stable identity | Selection in DataTable tracks the row object — keep object identity when resorting |
| Don’t copy rows | Mutate in place or replace the model; avoid cloning the whole table to change one cell |
| DataTable ListView | Do not bind fat row objects as the ListView model — kit uses lean index wrappers (3.44 H13); cells read _viewRows[i] |
| Sort key caches | Only active sortSpecs columns allocate per-row sort keys; hidden columns stay out of filter scans until shown |
| Section lists | ItemsView.sectionRole — sectioning still walks visible data; keep section cardinality reasonable |
| Images in rows | Prefer fixed-size icons / async Image with asynchronous: true; avoid huge decoded bitmaps in every delegate |
Charts & gauges¶
Canvas charts redraw when data or size changes. Keep series short and surfaces few.
Source ring caps vs draw LOD (3.45 H14)¶
| Layer | Surface | Default | Notes |
|---|---|---|---|
| Source ring | LiveMetricStrip |
maxPoints: **16** |
pushSample drops oldest |
| Source ring | KpiTile pushTrend |
cap 36 when omitted | Pass an explicit max for denser sparks |
| Source ring | ChartSeries |
capacity: **0** (unlimited) |
Opt-in: set capacity + append / appendXY |
| Source ring | JS values arrays |
— | ChartUtils.trimRing(values, n) or slice yourself |
| Draw LOD | Line / Area | autoLod: **true**, maxPoints: **0**, lodFactor: **2** |
Budget ≈ max(64, plotW × lodFactor); decimateMode: "bucket" |
| Draw LOD | Scatter | autoLod: **true**, lodFactor: **1** |
Density bins when over budget |
| Draw LOD | Sparkline | paint max(32, width) |
Always downsamples for paint |
Recipe: live tick → capped ring (capacity / trimRing / strip) → assign values or bind ChartSeries → invalidateLod() / requestRedraw(). Draw LOD stays on by default so visuals do not change when you only document caps.
| Guidance | Detail |
|---|---|
| Point budget | Prefer ≤ ~200–500 stored points for interactive Line/Area; let LOD thin further for Canvas |
| Cards | One chart inside ChartCard; scroll the page rather than tiling many full canvases |
| Live updates | Append/trim a capped ring; don’t rebuild a 10k-point array every tick |
| Hover | interactive: true adds hit-testing cost — turn off on dense static sparkline walls |
| Stable subset | Production: Line / Bar / Donut / RingGauge / KpiTile / ChartCard — remaining deferred 1.66 — charts.md |
ChartSeries {
id: cpuSeries
capacity: 120 // 3.45 — opt-in ring; 0 = unlimited
}
Timer {
interval: 1000; running: true; repeat: true
onTriggered: cpuSeries.append(measuredCpu)
}
ChartCard {
title: qsTr("CPU")
LineChart {
series: [{ name: qsTr("CPU"), values: cpuSeries }]
}
}
Gallery & app shells — heavy pages¶
| Pattern | Why |
|---|---|
| NavigationView page stack | Gallery opens pages on demand via pageModule + StackView — do the same in apps |
Defer with Loader |
Optional Multimedia / WebView2 / huge settings trees: active: false until needed |
| DataTable demo | Gallery ships ~200 employee rows plus a 10k load path (2.66); use maxFilterResults when filtering huge JS arrays |
| Charts hub | Small synthetic series; don’t paste multi-megabyte CSV into QML properties |
| Page Component cache | Cap with pageCacheLimit; Gallery defaults to 8 + pinned Home/Settings (3.46); clear after demos that thrash the stack |
When a page feels slow: check delegate cost and model rebuilds first, then chart point counts, then motion (Theme.reducedMotion).
Shell & window runtime (1.86)¶
Gallery and product apps on BackdropSolid (recommended — window-chrome.md).
| Symptom | Cause | Kit fix (1.86) |
|---|---|---|
| Thin white ring on dark windows (Round corners, D3D12) | DWM default border + QQuickWindow clearing white in the round-corner AA seam |
Solid hosts clear with layer fill (WindowHelper.solidHostFill / Theme.bgLayer); DWMWA_BORDER_COLOR pinned to the same RGB |
| White ring flashes on restore / refocus | Focus-in used to queue 80 ms DWM reapply bursts on every Solid window | Solid: immediate applyBorderColor + corner on activate; no extra timer on focus-in (frosted Mica/Acrylic still deferred) |
| Hitch when alt-tabbing back | Same deferred burst reflowing chrome | Solid focus path is synchronous border/corner only |
RHI: Gallery ships OpenGL on Windows for frost. D3D12 can still show a faint seam on transparent/frosted hosts — prefer OpenGL for Mica/Acrylic apps (graphics-backend.md).
Animations: pane collapse / page transitions unchanged — perf work trims redundant DWM work, not motion (see navigation.md).
Navigation & page stack (1.87)¶
Gallery navigation and TabView shells — motion unchanged, less per-frame waste.
| Area | Change | Visual impact |
|---|---|---|
NavigationView StackView |
Each pageTransition mode runs only its axes (_animOpacity / _animX / _animY / _animScale); slide and fade skip no-op scale/x/y animators |
Slide / fade / drill / cover look the same |
| Compact flyout shadow | MultiEffect layer enabled only while flyout is open (and not reduced motion) |
Shadow still appears on open |
TabView strip |
Width/opacity Behavior during reorder only; color/indicator Behavior when tab checked/hovered/focused |
Tab select + drag reorder still animate |
| Gallery Settings | Performance arc (1.86–1.89) tracker card | — |
pageCacheLimit: kit default 24; Gallery 8 + pinnedPageCache Home/Settings (3.46 H15). First page uses initialPageTransition: "none". See NavigationView.md.
Lists & data collections (1.88)¶
Virtualized tables and lists — no visual change, less work per keystroke.
| Control | Change | App note |
|---|---|---|
DataTable |
filterDebounceMs (default 120) before _viewRows rebuild; skip when filter query + sort + rows ref unchanged |
Sort still immediate; call refresh() after in-place row edits |
ItemsView |
Optional filterText + filterRoles for plain JS arrays only; filterDebounceMs 120, maxFilterResults 256 (3.51) |
C++ / ListModel: filter app-side (unchanged) |
ListDetailsView |
Same filter defaults as ItemsView (3.51); minFilterLength + fingerprint skip |
Selection index is into the filtered list |
ItemsRepeater |
Optional filterText (JS arrays) |
Delegate: bind to modelData roles once per row |
Delegate pooling: cache role strings in readonly property on the delegate root — avoids repeated _roleValue / _cellText walks when reuseItems recycles tiles.
Animations: row highlight, selection, and list motion unchanged.
Style, charts & Gallery heavy pages (1.89)¶
Animations stay — hover, press, focus, and chart reveal still run when the user interacts.
| Area | Change | Visual impact |
|---|---|---|
ElevatedChrome |
MultiEffect enabled after first frame; off when Theme.reducedMotion or chrome/window not shown (3.47) |
Shadow on open; flat when reduced motion; FBO freed when hidden |
| AcrylicSurface | Tint/ElevatedChrome over OS Mica/Acrylic — no kit blur bitmap cache |
Do not expect a QML acrylic texture pool to evict |
Style Button / TextField / Switch |
Behavior only when hovered / focused / pressed / toggled |
Same motion on interaction |
ListTile |
Color/scale Behavior when hovered / selected / pressed |
Same row feedback |
| Line / Bar / Donut charts | revealAnimationPointBudget (500); requestRedraw coalesced ~16 ms |
Reveal skips only on huge series |
| Gallery FontIcon | Filter debounced 120 ms | Same grid, fewer full-catalog walks |
| Gallery Charts / WebView2 | Deferred Loader for heavy/deferred demos |
Stable charts paint first |
Image / shadow / acrylic caches (3.47 H16)¶
| Cache | Cap / eviction | Notes |
|---|---|---|
QPixmapCache |
Kit default 16384 KB via Bootstrap; QWINUI3_PIXMAP_CACHE_KB overrides (0 = leave Qt default) |
Bound decoded Image RSS without changing decode quality |
ElevatedChrome MultiEffect |
Layer off when chrome or window not shown; still deferred 1 frame; reducedMotion flat | Same shadowBlur / blurMax / opacity when visible |
| AcrylicSurface | No kit blur texture pool | OS Mica/Acrylic is compositor-owned; chrome is ElevatedChrome |
ThemeFonts.iconFontFor |
LRU 96 (size, weight) entries | Hot icon sizes stay resident |
PersonPicture badge Image |
sourceSize = badge box |
Avoid full-res decode into tiny badges |
Wave Out: do not lower default acrylic frost or remove shadows globally — this slice only caps / frees idle memory.
Performance arc summary (1.86–1.89)¶
| Wave | Version | Theme |
|---|---|---|
| 1 | 1.86 | Shell & window runtime — solid host fill, DWM focus path |
| 2 | 1.87 | Navigation & page stack — per-axis transitions, flyout shadow defer |
| 3 | 1.88 | Lists & data collections — debounced filter, skip unchanged rebuilds |
| 4 | 1.89 | Style, charts & Gallery heavy pages — idle Behavior trim, chart budgets |
Rule for the arc: trim waste, not motion. Sign-off: checkpoint-190 (1.90).
Collection controls wave 5 (2.18)¶
Deepens 1.88 list/table perf on the 2.x floor — animations stay.
| Control | Change | App note |
|---|---|---|
DataTable |
maxFilterResults (default 0 = unlimited) caps JS filter walk |
Pair with filterDebounceMs; selection still tracks row object |
ListDetailsView |
_selectedItemRef — selection survives filter rebuild when item still visible |
filteredCount readout; same object-identity model as DataTable |
ListDetailsView |
maxFilterResults (default 256, 3.51; 0 = unlimited) + minFilterLength |
C++ / ListModel: filter app-side |
NavigationView |
pageCacheHits diagnostics; ensureComponent LRU unchanged |
Same-key nav still skips StackView replace; set pageCacheLimit |
Virtualization: all three use ListView + reuseItems — no second engine. For thousands of rows, filter/sort in C++ and bind a model.
Shell & navigation wave 6 (2.28)¶
Deepens 1.39 / 2.18 on NavigationView / NavigationWindow — animations stay. Focus: real apps with pageModule shells, not micro-benchmarks.
Real-app checklist¶
| # | Check | API / pattern | Why |
|---|---|---|---|
| 1 | Lazy pages | NavigationWindow + pageModule + hostContent: false |
Page QML compiles on first open — not at shell startup |
| 2 | Tune cache | pageCacheLimit (kit 24; Gallery 8 + pins — 3.46); clearPageCache() after major locale/theme swaps |
LRU evicts cold Components; Settings card exposes live count |
| 3 | Same destination | selectKey when key === currentKey |
Skips history push + openPage — see sameKeySkipCount |
| 4 | Same component | openPage when _openedPageName matches |
Skips StackView replace + enter/exit — see samePageSkipCount |
| 5 | First paint | initialPageTransition: "none" |
Gallery default; pair with pageTransition for later nav |
| 6 | Heavy destinations | Loader / deferred sibling (Charts 2.26) |
Avoid compiling optional surfaces until selected |
| 7 | Breadcrumb subtitle | syncSubtitleFromNavigation: true only when needed |
Avoid extra string work on every nav tick |
| 8 | Diagnostics | pageCacheHits, sameKeySkipCount, samePageSkipCount |
Log in dev; compare before/after trim passes |
| 9 | Frame budget | FrameStatsBadge / --show-fps (2.04) |
Advisory FPS — not a profiler |
NavigationWindow forwards cache + skip counters and clearPageCache() so product shells do not reach through NavigationView internals.
Advisory smoke timings¶
Gallery --smoke prints wall-clock splits. main / app are CI-gated on Release runners (3.39 S16); pages / total remain advisory:
QWinUI3 Gallery startup: app=…ms main=…ms (pages still on-demand)
QWinUI3 Gallery smoke OK (… main=…ms, pages=…ms, total=…ms)
| Field | Meaning | Use |
|---|---|---|
app |
Through QGuiApplication + engine setup |
CI soft ceiling (table above) |
main |
Through Main.qml root load |
CI hard gate — interactive shell |
pages |
Critical page QQmlComponent instantiate loop |
On-demand compile cost proxy |
total |
Wall clock to exit | Local regression hint after perf edits |
python scripts/smoke_gallery.py
python scripts/smoke_gallery.py --check-startup-budget
qwinui3_gallery.exe --smoke --startup-log
Smoke validates instantiate, not navigation frame time. Absolute limits live in scripts/smoke_gallery.py (STARTUP_BUDGET_*) and the table above — bump both together if a runner class needs headroom.
S5 / S16: CI Win Release main < 1500 ms; Linux offscreen main < 2000 ms. Local machines: compare relative deltas vs the prior tag on the same box.
NavigationView incremental navModel (2.88 C9)¶
When model changes but keys, kinds, and order stay the same, NavigationView patches the flattened ListModel in place instead of clear() + rebuild.
| API | Use |
|---|---|
patchNavItem(key, { title, badge, badgeValue, symbol, icon }) |
Single-entry live updates (locale, notification counts) |
onModelChanged |
Auto-incremental when structure unchanged; falls back to rebuildNavModel() |
NavigationWindow forwards patchNavItem. Prefer patching over reassigning navModel when only labels/badges change.
Theme token coalesce (2.88 C10)¶
Theme.apply(obj) applies density, accent, motion, and contrast knobs in one call, then bumps tokensRevision once and emits tokensChanged.
Connections {
target: Theme
function onTokensChanged() { /* refresh derived palette once */ }
}
// Or bind: property int _themeGen: Theme.tokensRevision
Avoid binding large subtrees to every individual Theme.* property when a settings panel applies multiple knobs in one frame.
Python Gallery cold start (2.89 S4)¶
qwinui3-gallery / python -m qwinui3_gallery:
configure_environment()— kit + binding only- Lazy-import
QtCore/QtGui/QtQmland Gallery@QmlElementmodules register_types(engine)immediately beforeengine.load
Measure with --startup-log or --smoke --startup-log — same fields as the C++ Gallery.
Chart coalesce inventory (2.84 C6 / 2.90 audit / 3.49 C20 / 3.54 C25)¶
ChartUtils.redrawCoalesceMs (~16 ms) batches Canvas repaints. 2.84 C6 extended coalesce beyond the stable six. 3.49 C20 closed the remaining experimental Canvas charts (Band / Dumbbell / ErrorBar / Pareto / PolarArea / Sunburst / Violin / Waffle). 3.54 C25 closes the stable six inventory (no API change). DataTable row refresh (Qt.callLater) and NavigationView pip Timer were already coalesced.
Stable six (3.54 C25)¶
| Type | Coalesce | Mechanism |
|---|---|---|
LineChart |
Yes | requestRedraw() → ChartUtils.redrawCoalesceMs |
BarChart |
Yes | same |
DonutChart |
Yes | same |
RingGauge |
N/A | QtQuick.Shapes + value Behavior — not Canvas paint |
KpiTile |
Yes (indirect) | Trend Canvas via embedded Sparkline requestRedraw() |
ChartCard |
N/A | Chrome host — child chart owns paint |
Full catalog¶
| Chart type | Coalesce | Notes |
|---|---|---|
| LineChart, BarChart, DonutChart | Yes | Stable six Canvas baseline (C2 / C25) |
| LollipopChart, FunnelChart, TreemapChart | Yes | C6 |
| BoxPlotChart, CandlestickChart | Yes | C6 |
| Area, Scatter, Heatmap, HorizontalBar, StackedBar, Combo, Histogram, … | Yes | Same requestRedraw() pattern |
| Band, Dumbbell, ErrorBar, Pareto, PolarArea, Sunburst, Violin, Waffle | Yes | 3.49 C20 |
Gauge family (*Gauge.qml) |
Partial | Value-driven Shape/repaint; not unified ChartUtils timer (RingGauge inventoried above) |
| Sankey | N/A | No public type in kit |
Gallery --smoke includes ChartsPage — compile/instantiate gate only.
App note: after mutating series in place, call requestRedraw() (or replace values / series) — coalesce batches multiple edits in the same ~16 ms window.
Binding churn audit (3.50 C21)¶
Hot path is full model rebuilds, not nested Qt.binding (kit has essentially one intentional Qt.binding in MenuStatusWindow after reparent).
| Surface | Prefer | Avoid |
|---|---|---|
| NavigationView | Assign model → structure probe then patch (2.88 / 3.53); stable nested children |
Forcing rebuildNavModel() after every label-only replace; nested Repeater reset on identical children |
| DataTable | _lastRefreshKey skip; column layout fingerprint; lean display reuse (3.50 / 3.52) |
Rebuilding pinned/scroll orders or lean wrappers when unchanged |
| ItemsView / ListDetailsView | _lastFilterKey + caps in fingerprint; cacheBufferPx (3.51 C22) |
Rebuilding filtered arrays on identical query |
| TreeDataGrid | _lastRefreshKey + caps; rows callLater; _treeCache flatten (3.52) |
Full filter/sort on every expand (use _rebuildFlatFromCache) |
| Theme | Theme.apply() / tokensRevision once |
Binding every token knob independently on hot surfaces |
Collection controls wave 7 (2.40)¶
Second collection pass on the 2.x floor — DataTable / ListDetailsView / NavigationView debounce-filter field paths, plus FileTree / TreeDataGrid when shipped. Builds on 2.18 (wave 5) and 2.28 (wave 6). Animations stay.
Real-app checklist¶
| # | Surface | Check | API / pattern | Why |
|---|---|---|---|---|
| 1 | DataTable | Debounced filter | filterDebounceMs (default 120) |
Avoid _viewRows rebuild on every key |
| 2 | DataTable | Skip unchanged | _lastRefreshKey (query + sort + rows ref) |
1.88 / 2.18 — identical filter/sort skips walk |
| 3 | DataTable | Cap filter walk | maxFilterResults > 0 on huge JS arrays |
2.18 — stop after N matches |
| 4 | DataTable | Stable selection | _selectedRowRef object identity |
Selection survives sort/filter when row still visible |
| 5 | ListDetailsView | Master filter | filterText + filterDebounceMs + filteredCount readout |
Same debounce model as DataTable |
| 6 | ListDetailsView | Cap master list | maxFilterResults |
C++ / ListModel: filter app-side instead |
| 7 | NavigationView | Pane search | Debounce in paneSearchTextEdited handler (~80–120 ms) |
Type exposes text + model — no built-in debounce |
| 8 | NavigationView | Shell trim | Wave 6: pageCacheLimit, sameKeySkipCount, samePageSkipCount |
Pair collection filter trim with nav skip metrics |
| 9 | TreeDataGrid | Branch filter | filterDebounceMs, maxFilterResults, expandOnFilter |
Tree walk is O(branches) — cap + debounce |
| 10 | TreeDataGrid | Skip unchanged | _lastRefreshKey + rows ref |
Same skip pattern as DataTable |
| 11 | FileTree | Table side | Embedded DataTable inherits filter debounce / caps | Tree side: filter treeModel app-side — do not rebuild whole tree per key |
| 12 | All lists | Virtualize | ListView + reuseItems |
No Column + Repeater for long collections |
| 13 | Large apps | Model-side filter | QAbstractItemModel + query |
JS filter+sort on thousands+ rows is not a product path |
Named paths: filter keystroke → debounce timer → refresh() → skip if key unchanged → cap walk → ListView reuse. Navigation pane search: app-owned Timer on paneSearchTextEdited before rebuilding paneSearchModel.
Charts & dashboard wave 8 (2.49)¶
Third 2.x pass on stable six + wrap grids + dashboard live series — closes tranche-1 perf sign-off with perf-signoff-2xx.md. Builds on 2.26 compose recipes and 2.48 dashboard decision tree. Animations stay.
Real-app checklist¶
| # | Surface | Check | API / pattern | Why |
|---|---|---|---|---|
| 1 | LineChart / BarChart / DonutChart | Point budget | revealAnimationPointBudget (500); coalesced redraw ~16 ms |
Skip reveal + batch paint on huge series |
| 2 | Dashboard KPI | Trend ring | KpiTile.trendValues capped (e.g. 16 samples) |
Replaces deferred Sparkline without unbounded arrays |
| 3 | Dashboard layout | Card count | One chart per ChartCard; scroll page | Avoid tiling many full canvases |
| 4 | ItemsWrapGrid | Debounced filter | filterDebounceMs (default 120) |
Wrap uses Repeater — not virtualized |
| 5 | ItemsWrapGrid | Tile count | Low hundreds max | Use ItemsView / DataTable at scale |
| 6 | CalendarView | Month cells | Bounded month model only | Experimental — no year-long virtualized grid |
| 7 | NotificationCenter | History list | Cap stored rows; group categories | Experimental drawer — not a sync engine |
| 8 | All | Motion policy | Theme.reducedMotion honored |
Perf trims DWM/debounce waste, not navigation motion |
Named paths: live metric tick → append/trim ring buffer → chart values replace; filter keystroke → filterDebounceMs → filter walk on small arrays only.
Tranche-1 performance sign-off (2.49)¶
Summary for 2.00…2.49 — full verdict doc: perf-signoff-2xx.md.
| Area | Tranche-1 posture |
|---|---|
| Lists / tables | Waves 5 + 7 — debounce, skip unchanged, maxFilterResults, reuseItems |
| Shell / nav | Wave 6 — pageCacheLimit, skip counters, deferred heavy Loaders |
| Charts / dashboard | Wave 8 — stable six point budgets + capped KPI trends |
| Wrap grids | Wave 8 — ItemsWrapGrid debounce + low hundreds cap |
| Diagnostics | 2.44 — FrameStats dev-only; applyRetailProfile() in retail |
| FL-008 | Closed — wave 10 sign-off — collection-perf-264.md; GPU million-row still out |
| Animations | Stay — no motion removal in perf waves |
Out for 2.49: GPU chart rewrite · built-in profiler · always-on retail FPS.
App-level flows wave 9 (2.59)¶
Fourth 2.x pass on command / search / carousel / async chrome — named product paths, not collection tables. Full slice doc: app-sluggishness-259.md. Builds on 2.16 debounce on CommandPalette / AutoSuggestBox and 2.37 carousel recipes.
Real-app checklist¶
| # | Surface | Check | API / pattern | Why |
|---|---|---|---|---|
| 1 | CommandPalette | Debounce + cap | filterDebounceMs (80); maxResults (64); maxRecentCommands (5) |
Avoid scanning full command tree every key |
| 2 | AutoSuggestBox | Min length + cap | minFilterLength (2 on huge lists); filterDebounceMs; maxSuggestionResults |
Skip 1-char full-array walks |
| 3 | ItemsView | Section filter | minFilterLength; maxFilterResults (256); filterDebounceMs |
JS-array filter is not a C++ model |
| 4 | Button | Async save | loading: true; enabled: !busy; preserveWidthWhileLoading |
Block double-submit + toolbar reflow |
| 5 | FlipView | Reduced motion | Swipe off when Theme.reducedMotion; use buttons / PipsPager |
Avoid heavy swipe transitions |
| 6 | Theme | Compact kiosk | Theme.applyDensityPreset("compact") |
Smaller controls without per-page hacks |
| 7 | All | Scale path | DataTable / ItemsRepeater for 1k+ rows | ItemsView filter stays for hundreds, not thousands |
Named paths: palette keystroke → debounce → capped filter + recent pin; typeahead → min length → debounce → capped suggestions; Save click → loading until promise resolves.
Out for 2.59: FL-008 collection wave 10 (2.64 shipped); GPU chart rewrite.
Collection controls wave 10 (2.64)¶
Fifth 2.x pass on DataTable / ListDetailsView / tree file surfaces — ops LoB paths. Full slice doc: collection-perf-264.md. Builds on waves 5 / 7 debounce + 2.49 tranche-1 sign-off.
Real-app checklist¶
| # | Surface | Check | API / pattern | Why |
|---|---|---|---|---|
| 1 | DataTable | Pin identity column | columns[].pinned: true |
Name/id stays visible while scrolling metrics |
| 2 | DataTable | Group rows | groupRole |
Team/status section headers for ops scan |
| 3 | DataTable | Persist order | columnOrder + moveColumn() |
Restore user layout from Settings |
| 4 | ListDetailsView | Bulk actions | multiSelectEnabled + detailToolbar |
Mail/archive without second ItemsView |
| 5 | ListDetailsView | Multi keyboard | Ctrl+click · Shift+range · Ctrl+A | Matches desktop mail selection |
| 6 | TreeDataGrid | Resize + freeze | Header splitters; freezeFirstColumn |
Wide hierarchies keep name column |
| 7 | FileTree | Filter + columns | filterText; hiddenColumnRoles |
Explorer LoB without custom chrome |
| 8 | All | Scale path unchanged | maxFilterResults + debounce |
JS arrays — not million-row GPU grid |
Named paths: ops table → pin name → group by team; mail master → multi-select → archive toolbar; file explorer → filter table → hide Modified column.
Out for 2.64: Million-row GPU grid rewrite.
Runtime diagnostics (2.04)¶
FrameStatsMonitor (Platform singleton) samples QQuickWindow::frameSwapped and exposes rolling FPS + frame time. Optional RHI backend readout (showRhi) appends the active Qt Quick graphics API (OpenGL, Vulkan, D3D11, …) from QQuickWindow::rendererInterface() or QSG_RHI_BACKEND.
| Surface | Usage |
|---|---|
| Title bar | FrameStatsBadge in TitleBar / ShellWindow rightHeader |
| Overlay | FrameStatsOverlay when inTitleBar is false |
| Gallery Settings | Show FPS, Show RHI, placement |
| CLI | --show-fps, --fps-overlay, --show-rhi, --show-diagnostics |
Opt-in only (enabled default false). Not a full profiler — advisory only. For RHI restart / backend selection see graphics-backend.md (Gallery GraphicsBackend singleton).
1.91 baseline: FPS + frame time only. 2.04 adds RHI beside FPS when showRhi is on.
Developer diagnostics productize (2.44)¶
Retail vs dev: shipping apps call FrameStatsMonitor.applyRetailProfile() (or retailMode: true + persistSettings: false) so FPS/RHI never persist from Gallery QSettings. Dev/internal builds keep CLI --show-fps / --show-diagnostics. Full cookbook: developer-diagnostics.md.
| API | Role |
|---|---|
retailMode |
Skip loading/saving enabled + RHI from QSettings |
persistSettings |
When false, toggles are session-only |
applyRetailProfile() |
One-shot retail setup + clear performance/* keys |
--retail-diagnostics |
CLI retail profile (smoke / CI) |
Promoted to stable (dev tooling): FrameStatsMonitor, FrameStatsBadge, FrameStatsOverlay — stable-api.md.
Out: Always-on FPS in retail builds.
Cheap wins (1.25 / 1.39)¶
Already applied / recommended in-tree:
ItemsRepeaterenablesreuseItems— matches DataTable / ItemsView.- Prefer role-based delegates over
JSON.parse/ deep copies indelegate. - Defer optional surfaces (
MediaPlayerElement/ WebView2 Gallery pages useLoader). - Drive animations with
Theme.duration(...)so reduced motion collapses work. - Wide DataTables: use the horizontal scrollbar; don’t nest a second flickable that fights the row
ListView. pageCacheLimit+initialPageTransition: "none"on Gallery NavigationView (1.39); Gallery tightened to 8 + pins in 3.46.- Defer Home card shadows one frame; honor reduced motion (1.39).
Out of scope¶
- Built-in profiler product
- GPU rewrite of Canvas chart engines
- Custom virtualization engine beyond QQC
ListView - Shipping a separate “lite” Gallery binary