Application platform (3.01…3.10)¶
Status: Tranche 9 — lands after checkpoint-300 (3.00 close-out).
Roadmap: ROADMAP.md
Recipes for shippable desktop apps — shell, commands, workspace, navigation, dashboards, and vertical kits.
Quick map¶
| Slice | Theme | Recipes |
|---|---|---|
| 3.01 | Shell 2.0 | title-bar-cookbook.md · window-shells.md · settings-persistence.md |
| 3.02 | Command system | commands.md — shortcutConflicts, canExecute, refreshContext |
| 3.03 | Workspace | app-platform-3xx.md — SplitWorkspace + LayoutPreset |
| 3.04 | Navigation pro | navigation.md — pins, jump list, drilldown |
| 3.05 | Dashboard live | charts.md — LiveMetricStrip · examples/dashboard/ |
| 3.06 | Charts wave B | charts.md — BarChart bins (FL-015) |
| 3.07 | Vertical kits | admin-settings · master-detail-crm · ops-console |
| 3.08 | Multi-window | window-shells.md — bus + PanelFloatHost |
| 3.09 | Platform extras | file-association.md · RecentFiles · MenuStatusWindow |
| 3.10 | Sign-off | checkpoint-310.md |
3.01 — Shell 2.0 (shipped)¶
Title-bar commands (W2)¶
Use TitleBarCommandBar in leftHeader or captionRightHeader with plain command objects:
leftHeader: TitleBarCommandBar {
commands: [
{ id: "save", label: qsTr("Save"), symbol: FluentIcons.Save,
shortcut: "Ctrl+S", action: saveDocument }
]
}
Fields: id, label/title, symbol/icon, shortcut, enabled, visible, action.
Command palette on shells (W3)¶
| Shell | Wiring |
|---|---|
| ShellWindow / NavigationWindow | commandPaletteEnabled (default true), commandPaletteCommands, Ctrl+K / Meta+K |
| StandardWindow | Attach CommandPaletteHost — Ctrl+K / Meta+K |
Gallery Main uses CommandPaletteHost (Ctrl+K). examples/gallery-shell wires SessionRestore.
Session restore (W4)¶
Host SessionRestore in a zero-size Item — not as a direct child of StandardWindow.
SessionRestore persists geometry (via geometryPersistenceKey), NavigationView key, pane open, and footer selection:
SessionRestore {
window: mainWindow
navigationView: nav
}
Component.onCompleted: session.restore()
onClosing: session.save()
Settings category defaults to <geometryPersistenceKey>/Session.
3.02 — Command system (shipped)¶
| ID | API |
|---|---|
| R1 | CommandRegistry.dispatch(id) — scoped run |
| R2 | shortcutConflicts() / conflicts — chord collisions |
| R3 | canExecute / enabled + refreshContext() |
See commands.md.
3.03 — Workspace layout (shipped)¶
SplitWorkspace (W5)¶
SplitWorkspace {
paneCount: 3
orientation: Qt.Horizontal
minPaneWidth: 120
ratios: [0.25, 0.5, 0.25]
pane1: /* … */; pane2: /* … */; pane3: /* … */
}
| Method | Role |
|---|---|
setRatios([…]) |
Normalize + apply relative widths/heights |
focusNextPane() / focusPreviousPane() |
Ctrl+Alt+Arrow |
snapshot() / applyPreset(obj) |
Serialize for LayoutPreset |
Prefer TwoPaneView when panes must collapse on narrow windows.
LayoutPreset (W6)¶
Item {
width: 0; height: 0; visible: false
LayoutPreset {
category: "MyApp/Layouts"
workspace: split
}
}
layouts.save("Editor")
layouts.apply("Monitor")
3.04 — Navigation pro (shipped)¶
Pinned favorites (N1)¶
NavigationView {
pinnedNavKeys: ["home"]
maxPinnedNavKeys: 8
pinnedNavSettingsCategory: "MyApp/NavPins" // persist JSON in QSettings
}
nav.pinNavKey("home")
nav.toggleNavPin("reports")
Pinned keys render as chips above the pane list. Right-click a chip to unpin.
Jump list (N2)¶
Drilldown stack (N3)¶
nav.pushDrilldown(qsTr("Order 42"), "OrderDetailPage")
nav.popDrilldown()
// TitleBar Back → navigateBack() pops drilldown before pageHistory
BreadcrumbBar {
model: nav.breadcrumbTrail
onItemInvoked: (i) => nav.selectBreadcrumbIndex(i)
}
NavigationWindow forwards pin / jump / drilldown APIs and breadcrumbTrail.
See navigation.md.
3.05 — Dashboard live (shipped)¶
LiveMetricStrip (G1)¶
LiveMetricStrip {
id: live
intervalMs: 1200
running: true
maxPoints: 16
compareLag: 8
periodLabel: qsTr("vs prior window")
metrics: [
{ key: "cpu", title: qsTr("CPU"), unit: "%",
cautionThreshold: 75, criticalThreshold: 90 }
]
onTick: live.pushSample("cpu", measuredCpu)
}
| API | Role |
|---|---|
pushSample / pushSamples |
Update value + ring + compare + auto delta |
tick / tickOnce |
Throttled poll hook (no per-tile Timer) |
compareLag |
Samples back for compareValue |
Ops console (G2)¶
Gallery Ops console page demos the strip + threshold event feed. examples/dashboard uses LiveMetricStrip in DashboardShell.kpiRow with a Live refresh checkbox.
Closes FL-014. Prefer MetricCompareRow only for static period strips.
See charts.md · components/LiveMetricStrip.md.
3.06 — Charts wave B (shipped)¶
BarChart bins (G3)¶
BarChart {
samples: latencyMs // raw numbers
binCount: 12
binLabelPrecision: 0
showValueLabels: true
}
// or
chart.setBinsFromSamples(samples, 10)
chart.applyBins(ChartUtils.histogramBins(samples, 10))
HistogramChart stays experimental — product apps use BarChart binning. Closes FL-015 without a new stable chart type.
See charts.md · components/BarChart.md.
3.07 — Vertical app kits (shipped)¶
| ID | Example | Stack |
|---|---|---|
| V1 | examples/admin-settings |
SettingsView · FormLayout · SettingsCard |
| V2 | examples/master-detail-crm |
ListDetailsView · DataTable · CommandBar |
| V3 | examples/ops-console |
SplitWorkspace · LayoutPreset · LiveMetricStrip · DataTable |
Copy the folder; build qwinui3_example_admin_settings / _master_detail_crm / _ops_console.
3.08 — Multi-window & panels (shipped)¶
WindowMessageBus appearance (W7)¶
WindowMessageBus.post("appearance", {
dark: Theme.dark,
accentPack: Theme.accentPack,
layoutDirection: WindowHelper.layoutDirection
})
WindowMessageBus.subscribe("appearance", function (p) { /* apply */ })
Same process only — see examples/multi-window.
PanelFloatHost (W8)¶
PanelFloatHost {
title: qsTr("Filters")
geometryPersistenceKey: "MyAppFilterFloat"
content: /* pane body Component */
}
floatPane() / dockPane() move one Component between host and owned ToolShellWindow.
3.09 — Platform desktop extras (shipped)¶
| ID | Surface |
|---|---|
| P1 | MenuStatusWindow — Gallery Window shells · window-shells.md |
| P2 | RecentFiles + WindowHelper.addToRecentDocuments |
| P3 | WindowHelper.registerFileAssociation — file-association.md |
3.10 — Checkpoint¶
checkpoint-310.md green 2026-08-27.
Related¶
- compatibility-3xx.md — stable surface after 3.00
- upgrade-notes.md — version migration notes