Skip to content

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

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:

qwinui3_gallery.exe --startup-log
qwinui3_gallery.exe --smoke --startup-log

--smoke prints main=…ms, pages=…ms, total=…ms after creating the critical set only — it does not open every control page.

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-log before adopting.
  • CI may run qmlcachegen when qmlcachegen is on PATH (same guard as scripts/qwinui3.py tool 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 }]
    }
}

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).


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.


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.


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.


qwinui3-gallery / python -m qwinui3_gallery:

  1. configure_environment() — kit + binding only
  2. Lazy-import QtCore / QtGui / QtQml and Gallery @QmlElement modules
  3. register_types(engine) immediately before engine.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:

  1. ItemsRepeater enables reuseItems — matches DataTable / ItemsView.
  2. Prefer role-based delegates over JSON.parse / deep copies in delegate.
  3. Defer optional surfaces (MediaPlayerElement / WebView2 Gallery pages use Loader).
  4. Drive animations with Theme.duration(...) so reduced motion collapses work.
  5. Wide DataTables: use the horizontal scrollbar; don’t nest a second flickable that fights the row ListView.
  6. pageCacheLimit + initialPageTransition: "none" on Gallery NavigationView (1.39); Gallery tightened to 8 + pins in 3.46.
  7. 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