repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

skill(qml): new pure-QML skill (677w) + 7 examples + quickshell cross-ref

e811fabd960fccf61ac8680e2ee42a7207dfeb7b

Review <review@example.invalid> ·

unsigned

Browse filesCompare with HEAD

Changed files (23)

skills/qml/README.md

Added
new file mode 100644
1 +# qml
3 +QML (Qt Modeling Language) — the declarative UI language for QtQuick. Pure QML: no Quickshell, no Qt-specific compositor types, no platform bindings beyond the standard library.
5 +## Layout
7 +```
8 +qml/
9 +├── SKILL.md # entry point — read first
10 +├── references/ # depth, by topic
11 +│ ├── syntax.md # imports, properties, bindings
12 +│ ├── components.md # custom types, inline components
13 +│ ├── layouts.md # anchors, Layouts, the size rule
14 +│ ├── models.md # Repeater, ListView, ListModel
15 +│ ├── signals.md # signal declaration, handlers, Connections
16 +│ ├── javascript.md # JS in QML, Qt helpers
17 +│ └── common-pitfalls.md # the 18 mistakes everyone makes
18 +├── examples/ # 7 minimal, runnable QML prototypes
19 +│ ├── 01-hello/ # Rectangle + TapHandler (smallest)
20 +│ ├── 02-repeater/ # Repeater over a JS array
21 +│ ├── 03-anchors/ # anchors.fill, centerIn, margins
22 +│ ├── 04-listview/ # ListView + ListModel + add/remove
23 +│ ├── 05-form/ # GridLayout form with validation
24 +│ ├── 06-animation/ # Behavior + SequentialAnimation
25 +│ └── 07-tabs/ # TabBar + StackLayout
26 +└── README.md # this file
27 +```
29 +## Quick start
31 +```sh
32 +# Run any example (uses the system qml6 runtime)
33 +qml6 examples/01-hello/hello.qml
35 +# Lint the QML syntax
36 +qmllint examples/01-hello/hello.qml
37 +```
39 +This skill is **QtQuick/QML only**. For Quickshell-specific desktop components, see the `quickshell` skill.
41 +## Validation
43 +- All 7 examples parse clean with `qmllint` (Qt 6 linter).
44 +- All 7 examples run with `qml6` (QML runtime) — open a window, interactive.
45 +- No Quickshell imports in any example. Pure QML.
47 +To extend validation on your own machine: add a new QML file, drop it under `examples/`, and run `qmllint <file> && qml6 <file>` to verify it parses and runs.
49 +## What to read first
51 +- **`SKILL.md`** — the mental model, the common patterns, the cross-references. 10 min.
52 +- **`references/syntax.md`** — when you need to know exactly which property modifiers exist.
53 +- **`references/common-pitfalls.md`** — when something weird happens, look here first.
54 +- **`examples/`** — when you need to ship a feature, copy the closest example and adapt.
56 +## See also
58 +- **`quickshell` skill** — Quickshell uses QML for configuration. For Quickshell-specific types (`PanelWindow`, `Quickshell.Io`, `Quickshell.Services.*`, `Scope`, `Variants`, `LazyLoader`, etc.), see the `quickshell` skill. The `qml` skill is referenced by the `quickshell` skill but contains zero Quickshell knowledge.
59 +- Qt documentation: <https://doc.qt.io/qt-6/qml-tutorial.html>, <https://doc.qt.io/qt-6/qtqml-index.html>

skills/qml/SKILL.md

Added
new file mode 100644
1 +---
2 +name: qml
3 +description: Use when writing or editing QML/QtQuick code — property bindings, components, signals, models, anchors, layouts, JavaScript integration. Triggers on "qml", "qtquick", "qt qml", "qml binding", "qml signal", "qml component", "qml layout", "qt property binding". Does NOT cover Quickshell-specific types (see the quickshell skill for that).
4 +---
6 +# QML
8 +QML (Qt Modeling Language) is the declarative UI language for QtQuick. You build a tree of objects; properties propagate reactively. The language is small — the depth is in the standard library (`QtQuick`, `QtQuick.Controls`, `QtQuick.Layouts`, `QtQuick.Window`, …).
10 +This skill is **pure QML** — no Quickshell, no Qt-specific compositor types. For Quickshell desktop shells, layer-shell, or Wayland IPC, see the `quickshell` skill.
12 +## Mental model
14 +```qml
15 +import QtQuick
16 +import QtQuick.Controls
18 +ApplicationWindow {
19 + // root object: a window with an attached contentItem + header + footer
20 + width: 400; height: 300; visible: true
22 + // properties flow top-down via bindings
23 + title: "Hello"
24 + color: "white"
26 + // child objects fill the tree
27 + Column {
28 + anchors.fill: parent
29 + Text { text: "Hello" }
30 + Button { text: "Click" }
31 + }
33 +```
35 +- **Tree of objects** — each `{...}` is an object; nested objects are children.
36 +- **Property bindings** — `width: parent.width / 2` is an expression; it re-evaluates when `parent.width` changes.
37 +- **Signals** — objects emit them; you connect with `on<Signal>` handlers.
38 +- **JavaScript** — inline expressions and full functions; QML is JS-aware.
40 +## Imports
42 +```qml
43 +import QtQuick // Item, Rectangle, Text, Image, MouseArea, Timer, …
44 +import QtQuick.Window // Window, ApplicationWindow
45 +import QtQuick.Controls // Button, TextField, Label, Slider, TabBar, …
46 +import QtQuick.Layouts // RowLayout, ColumnLayout, GridLayout, StackLayout
47 +import QtQuick.Dialogs // FileDialog, MessageDialog
48 +import Qt.labs.platform 1.1 // native menu/standardPaths (labs; pin a version)
49 +import "myfile.js" as MyJs // JS file as a namespace
50 +import "subfolder" as Sub // relative-path folder import
51 +```
53 +Module imports `<Module> [Major.Minor] [as <Namespace>]`. Relative imports use a path. Always pin a major.minor for stability.
55 +## Defining a property
57 +```qml
58 +Item {
59 + property int count: 0 // int, default 0
60 + property string name: "x" // string
61 + property real ratio: 0.5 // float (QML's `real` = double)
62 + property bool enabled: true
63 + property var things: [1, "x", true] // var = untyped (rarely needed)
64 + property color tint: "red" // color string → QColor
65 + property url img: "https://example.com" // URL
66 + property MyType other // reference to another object
67 + property point p: Qt.point(0, 0) // x, y
68 + property size s: Qt.size(100, 50) // w, h
69 + property rect r: Qt.rect(0, 0, 100, 50) // x, y, w, h
70 + property date d: new Date()
71 + property list<int> nums: [1, 2, 3] // QML list
72 + property var fn: (x) => x * 2 // function
74 + // modifiers
75 + readonly property int ro: 5 // bind-once-style; can't be assigned
76 + default property Item content // default property (used when object is the value)
77 + required property var modelData // forces the user to set it
78 + property int reset: count > 0 ? 0 : 0 // always re-evaluates if count changes
80 +```
82 +- `readonly` — can be assigned in initial binding only.
83 +- `default` — this is the property an object child becomes the value of (e.g. `Item { Rectangle {...} }` is shorthand for `Item { default: Rectangle {...} }`).
84 +- `required` — the user of this type must set this; `qmllint` enforces.
86 +## Reactive bindings
88 +```qml
89 +property int count: 0
90 +Timer { running: true; interval: 1000; repeat: true; onTriggered: count++ }
92 +Item {
93 + width: count * 10 // re-evaluates every time `count` changes
94 + visible: count > 0 // reactively hides when count is 0
96 +```
98 +**This is the key insight.** You don't write update code. You write expressions; QML tracks dependencies and re-evaluates.
100 +## Signals
102 +```qml
103 +Item {
104 + signal activated(string from) // declare a signal
105 + signal toggled() // no args
107 + property int level: 0
109 + onActivated: (from) => console.log("from:", from) // handler
110 + onLevelChanged: console.log("now", level) // auto-signal for property changes
112 + Component.onCompleted: console.log("ready") // one-shot at creation
113 + Component.onDestruction: console.log("destroyed")
115 + MouseArea {
116 + anchors.fill: parent
117 + onClicked: parent.activated("click")
120 +```
122 +Every property has an auto-generated `on<Property>Changed` signal. To listen to another object's signals, use `Connections { target: x; function on<Signal>() { ... } }`.
124 +## Functions
126 +```qml
127 +Item {
128 + function square(x: int): int { return x * x }
129 + function notify(msg: string): void { console.log(msg) }
130 + property var add: (a, b) => a + b
132 +```
134 +Use `void` return for non-returning functions. Functions are JavaScript, with QML value-type semantics (e.g. `point` is passed by value).
136 +## Inline components
138 +```qml
139 +Item {
140 + component Labeled: Row {
141 + property string text
142 + Text { text: parent.text }
145 + Labeled { text: "first" }
146 + Labeled { text: "second" }
148 +```
150 +`component Name: Type { ... }` defines a type locally. Use this to avoid making a separate file for one-shot types.
152 +## Custom types in their own file
154 +```qml
155 +// MyButton.qml (PascalCase, in the same dir as the consumer)
156 +import QtQuick
157 +import QtQuick.Controls
158 +Button {
159 + property string iconName: ""
160 + icon.name: iconName
162 +```
164 +Neighbor `.qml` files with PascalCase names are auto-imported in the same directory. For subfolders, use relative imports or `qmldir` files.
166 +## Anchors and size
168 +```qml
169 +Rectangle {
170 + anchors.fill: parent // fill parent
171 + anchors.centerIn: parent // center inside parent
172 + anchors.left: parent.left // left edge to parent's left
173 + anchors.top: parent.top; anchors.bottom: parent.bottom // stretch top-bottom
175 + width: 100; height: 50 // set actual size
176 + implicitWidth: 100; implicitHeight: 50 // desired size (used by containers)
178 +```
180 +**The cardinal rule:** implicit size flows child → parent; actual size flows parent → child. Setting actual size on a child that a container will manage is a bug — the container will overwrite it. Setting implicit size on a container is correct.
182 +## Layouts (the easy way)
184 +`import QtQuick.Layouts`
186 +```qml
187 +RowLayout { // horizontal
188 + spacing: 8
189 + Item { Layout.fillWidth: true } // spacer
190 + Text { text: "right" }
193 +ColumnLayout { spacing: 8 } // vertical
194 +GridLayout { columns: 3 } // grid
195 +StackLayout { } // stack (only one visible)
196 +```
198 +`Layout.fillWidth: true` (and friends) make the child stretch. `Layout.preferredWidth: 100` sets the size before stretching.
200 +## Models and views
202 +```qml
203 +ListModel {
204 + id: list
205 + ListElement { name: "Alice"; age: 30 }
206 + ListElement { name: "Bob"; age: 25 }
209 +ListView {
210 + model: list
211 + delegate: Text { text: name } // `name` is auto-injected from the model role
213 +```
215 +Other models: `Repeater` (inline, no scroll), `ListView` (scrollable, recycles), `GridView`, `TableView`, `PathView`. For dynamic data, use `ObjectModel` or a custom C++ `QAbstractListModel`.
217 +## Component composition
219 +```qml
220 +Item {
221 + id: container
222 + default property Item body // accepts one Item as the "body"
224 + Rectangle { anchors.fill: parent; color: "lightblue" }
226 +```
228 +The consumer:
230 +```qml
231 +MyContainer {
232 + body: Column {
233 + Text { text: "first" }
234 + Text { text: "second" }
237 +```
239 +Default properties make component composition clean — the consumer doesn't have to use `body: Column {...}`, they can just put the column inside.
241 +## When NOT to use QML
243 +- C++ hot paths or large data transformations — use C++ with a QObject model exposed to QML.
244 +- Async I/O — QML has promises (`Qt.callLater`) but Node.js / Python is usually cleaner.
245 +- Complex business logic — write the logic in C++ or Python, expose the result as a property.
247 +## Cross-references
249 +- `references/syntax.md` — imports, properties, bindings in depth
250 +- `references/components.md` — defining custom types, inline components, default properties
251 +- `references/layouts.md` — anchors, layouts, the implicit/actual size rule
252 +- `references/models.md` — Repeater, ListView, ObjectModel, custom C++ models
253 +- `references/signals.md` — signal declaration, handlers, Connections
254 +- `references/javascript.md` — JS in QML, function calls, lambdas
255 +- `references/common-pitfalls.md` — `childrenRect` loops, zero-size Items, binding fights
256 +- `examples/` — 7 minimal, runnable QML prototypes (no Quickshell, no Qt-specific compositor types)
258 +## See also
260 +- **`quickshell` skill** — for using QML inside a Quickshell shell, layer-shell panels, IPC, and the Quickshell-specific types.
261 +- Qt docs: <https://doc.qt.io/qt-6/qml-tutorial.html>, <https://doc.qt.io/qt-6/qtqml-index.html>

skills/qml/examples/01-hello/README.md

Added
new file mode 100644
1 +# 01 — hello
3 +Smallest interactive QML: a colored rectangle that counts clicks.
5 +**Run:** `qml6 hello.qml`
7 +**What it teaches:**
8 +- `Window` is the top-level (use `ApplicationWindow` from `QtQuick.Controls` for menus/toolbars).
9 +- `import` statements at the top.
10 +- `Rectangle` is a visible `Item` with a `color` (background) and `radius` (rounded corners).
11 +- A property (`box.count`) reactively drives a binding (`color: tap.count % 2 ? ...`).
12 +- `TapHandler` (from `QtQuick`) detects taps on any item — no `MouseArea` needed.
13 +- `anchors.fill: parent` makes the rectangle fill its parent.
14 +- `anchors.margins: 20` adds 20px padding on all sides.
16 +**What to break and learn from:**
17 +- Remove `property int count: 0` → `box.count++` fails (no such property).
18 +- Change `color: ...` to `color: "red"` (no binding) → the rectangle no longer updates on click.
19 +- Add `width: 100; height: 50` to the Rectangle — its `anchors.fill` will override these. Pick one.
20 +- Add another Rectangle inside this one with `anchors.fill: parent` — it covers the click handler. Use `z: 1` to bring it to front, or use `preventStealing: true` on the parent's TapHandler.
22 +**Common QML pattern:** all visual properties are set via bindings, not assignments. Change a property; the UI re-renders.

skills/qml/examples/01-hello/hello.qml

Added
new file mode 100644
1 +// 01-hello/hello.qml
2 +// Smallest interactive QML: a rectangle that changes color on click.
3 +// Pure QML — no Quickshell, no Qt-specific compositor. Runs with: qml6 hello.qml
5 +import QtQuick
6 +import QtQuick.Window
8 +Window {
9 + width: 300
10 + height: 200
11 + visible: true
12 + title: "QML 01 — Hello"
14 + Rectangle {
15 + id: box
16 + anchors.fill: parent
17 + anchors.margins: 20
18 + radius: 12
19 + color: tap.count % 2 ? "steelblue" : "tomato"
21 + // count is a property the binding to `color` will react to.
22 + property int count: 0
23 + Text {
24 + anchors.centerIn: parent
25 + text: "clicked " + box.count + (box.count === 1 ? " time" : " times")
26 + color: "white"
27 + font.pixelSize: 18
28 + }
29 + TapHandler {
30 + id: tap
31 + onTapped: box.count++
32 + }
33 + }

skills/qml/examples/02-repeater/README.md

Added
new file mode 100644
1 +# 02 — Repeater
3 +`Repeater` instantiates a delegate per row of a model. No scroll, no recycling — good for small fixed lists. For longer lists, use `ListView` (see `examples/04-listview/`).
5 +**Run:** `qml6 repeater.qml`
7 +**What it teaches:**
8 +- `Repeater` parent: any `Item` (here, a `ColumnLayout`).
9 +- Model: a JS array of objects. Each element is `modelData` in the delegate.
10 +- `delegate: Item { ... }` — the per-row template. Each instance gets its own scope.
11 +- `required property var modelData` — forces the consumer (in this case the model) to provide it.
12 +- `index` is auto-injected as the row number (0..N-1).
13 +- `Layout.fillWidth: true` makes the row stretch in the parent `ColumnLayout`.
14 +- `Layout.preferredWidth: 100` sets the width before stretching (in this case, for the first column).
16 +**What to break and learn from:**
17 +- Change `model: [...]` to a number: `model: 5` — the delegate is instantiated 5 times with `index` = 0..4, but `modelData` is the same number each time.
18 +- Add `model.append({ name: "Eve", role: "New" })` to a button's `onClicked` — but **this is a JS array, not a ListModel**, so the Repeater won't update. Use `ListModel` for observable lists.
19 +- Remove `Layout.fillWidth: true` — the rows are only as wide as their content, leaving empty space on the right.
20 +- Move the Repeater to a `Row` instead of `ColumnLayout` — delegates arrange horizontally. Same shape, different parent.
22 +**Common QML pattern:** `Repeater` is the right choice for `< 20` items that fit on screen. For more, use `ListView`.

skills/qml/examples/02-repeater/repeater.qml

Added
new file mode 100644
1 +// 02-repeater/repeater.qml
2 +// Repeater: instantiate one child per model row. Inline, no scroll.
3 +// Pure QML. Run with: qml6 repeater.qml
5 +import QtQuick
6 +import QtQuick.Window
7 +import QtQuick.Layouts
9 +Window {
10 + width: 360
11 + height: 360
12 + visible: true
13 + title: "QML 02 — Repeater"
15 + ColumnLayout {
16 + anchors.fill: parent
17 + anchors.margins: 12
18 + spacing: 8
20 + // The model is a JS array of objects.
21 + Repeater {
22 + model: [
23 + { name: "Alice", role: "Engineer" },
24 + { name: "Bob", role: "Designer" },
25 + { name: "Charlie", role: "Manager" },
26 + { name: "Dana", role: "Researcher" }
27 + ]
29 + delegate: Rectangle {
30 + required property var modelData
31 + Layout.fillWidth: true
32 + implicitHeight: 44
33 + radius: 6
34 + color: index % 2 ? "#f0f0f0" : "white"
35 + border.color: "#ccc"
36 + border.width: 1
38 + RowLayout {
39 + anchors.fill: parent
40 + anchors.margins: 12
41 + Text {
42 + text: modelData.name
43 + font.bold: true
44 + Layout.preferredWidth: 100
45 + }
46 + Text {
47 + text: modelData.role
48 + color: "#666"
49 + }
50 + Item { Layout.fillWidth: true }
51 + Text {
52 + text: "#" + (index + 1)
53 + color: "#999"
54 + }
55 + }
56 + }
57 + }
58 + }

skills/qml/examples/03-anchors/README.md

Added
new file mode 100644
1 +# 03 — anchors
3 +Anchors: the manual way to position items relative to their parent's edges or center. For structured layouts (rows, columns, grids), use `QtQuick.Layouts` instead.
5 +**Run:** `qml6 anchors.qml`
7 +**What it teaches:**
8 +- `anchors.top: parent.top` — pin the top edge to the parent's top edge.
9 +- `anchors.left` / `anchors.right` / `anchors.bottom` — same for the other three.
10 +- `anchors.margins: 16` — uniform margin on all four sides.
11 +- `anchors.topMargin: 16` (etc.) — per-side override.
12 +- `anchors.centerIn: parent` — center in both axes.
13 +- `anchors.horizontalCenter` / `anchors.verticalCenter` — center in one axis.
14 +- `anchors.fill: parent` — shorthand for all four edges (left/right/top/bottom all true).
16 +**What to break and learn from:**
17 +- Set `width: 200` on the center box while it has `anchors.centerIn: parent` — `width: 200` is the size; `anchors.centerIn` is the position. Both work; the box is 200×100 centered.
18 +- Try to mix `anchors.fill: parent` with `width: 100` — `anchors.fill` wins; the width is ignored. Pick one.
19 +- Set `anchors.left: parent.left` and `anchors.right: parent.right` (but not top/bottom) on the bottom-stretch box — it now stretches horizontally only, height stays at 60. Try this; it's the canonical "side panel" pattern.
20 +- Anchor to a sibling: `anchors.left: otherBox.right` — pin left edge to another item's right edge.
22 +**Common QML pattern:** anchors are for one-off positioning. For repeated structure (a list of rows, a grid of items), use a `Layout` (`RowLayout`, `ColumnLayout`, `GridLayout`).

skills/qml/examples/03-anchors/anchors.qml

Added
new file mode 100644
1 +// 03-anchors/anchors.qml
2 +// Anchors: manual positional layout. Use for one-off positioning.
3 +// Pure QML. Run with: qml6 anchors.qml
5 +import QtQuick
6 +import QtQuick.Window
8 +Window {
9 + width: 400
10 + height: 300
11 + visible: true
12 + title: "QML 03 — Anchors"
13 + color: "#f5f5f5"
15 + // Top-left box: anchored to corners with margins
16 + Rectangle {
17 + anchors.top: parent.top
18 + anchors.left: parent.left
19 + anchors.margins: 16
20 + width: 120; height: 80
21 + color: "tomato"
22 + radius: 4
23 + Text { anchors.centerIn: parent; text: "top-left"; color: "white" }
24 + }
26 + // Top-right: anchored top + right, centered horizontally
27 + Rectangle {
28 + anchors.top: parent.top
29 + anchors.right: parent.right
30 + anchors.topMargin: 16
31 + anchors.rightMargin: 16
32 + width: 120; height: 80
33 + color: "steelblue"
34 + radius: 4
35 + Text { anchors.centerIn: parent; text: "top-right"; color: "white" }
36 + }
38 + // Center: full centerIn
39 + Rectangle {
40 + anchors.centerIn: parent
41 + width: 140; height: 100
42 + color: "mediumseagreen"
43 + radius: 8
44 + Text { anchors.centerIn: parent; text: "center"; color: "white"; font.bold: true }
45 + }
47 + // Bottom-stretch: fill the bottom edge
48 + Rectangle {
49 + anchors.bottom: parent.bottom
50 + anchors.left: parent.left
51 + anchors.right: parent.right
52 + anchors.margins: 16
53 + height: 60
54 + color: "goldenrod"
55 + radius: 4
56 + Text { anchors.centerIn: parent; text: "bottom-stretch"; color: "white" }
57 + }

skills/qml/examples/04-listview/README.md

Added
new file mode 100644
1 +# 04 — ListView
3 +`ListView`: a scrollable, recycling list. The right tool for any list that may exceed the screen height.
5 +**Run:** `qml6 listview.qml`
7 +**What it teaches:**
8 +- `ListModel` is a JS-manipulable list of rows. `append({...})`, `remove(i)`, `setProperty(i, "name", val)`, `count`.
9 +- `ListElement` is a literal row. Property names become model roles (here, `title` and `done`).
10 +- `ListView` recycles delegates — only the visible rows are kept in memory. Fine for 10 or 10,000 items.
11 +- `delegate: Rectangle { required property var modelData; ... }` — each delegate gets its own modelData.
12 +- `ListView.view.width` references the enclosing `ListView` (use this for full-width rows).
13 +- `clip: true` prevents drawing outside the view's bounds.
14 +- `tasks.count === 0` for an empty-state placeholder.
16 +**What to break and learn from:**
17 +- Add 100 items (`for (let i = 0; i < 100; i++) tasks.append(...)`) — `ListView` recycles; no slowdown.
18 +- Try to bind `width: parent.width` instead of `width: ListView.view.width` — `parent` here is the ListView's contentItem, which may not have the right size. Use `ListView.view.width` for the ListView itself.
19 +- Set `delegate.height: 200` — delegates are fixed height; spacing is independent. Compare with `implicitHeight: 200` (the desired size before stretching).
20 +- Set `cacheBuffer: 0` — no off-screen cached delegates. The default is 320 pixels above/below the view, for smooth scrolling.
21 +- Replace `ListModel` with a JS array — the `append`/`remove` calls no longer trigger re-renders. Use `ListModel` for observable lists.
23 +**Common QML pattern:** `ListView` + `ListModel` is the workhorse for any UI list. For very large or dynamic data, expose a C++ `QAbstractListModel`.

skills/qml/examples/04-listview/listview.qml

Added
new file mode 100644
1 +// 04-listview/listview.qml
2 +// ListView: scrollable list with a ListModel (observable).
3 +// Pure QML. Run with: qml6 listview.qml
5 +import QtQuick
6 +import QtQuick.Window
7 +import QtQuick.Controls
9 +Window {
10 + width: 360
11 + height: 400
12 + visible: true
13 + title: "QML 04 — ListView"
15 + ListModel {
16 + id: tasks
17 + ListElement { title: "Ship the QML skill"; done: true }
18 + ListElement { title: "Validate with prototypes"; done: true }
19 + ListElement { title: "Add component examples"; done: false }
20 + ListElement { title: "Write reference docs"; done: false }
21 + }
23 + Column {
24 + anchors.fill: parent
25 + anchors.margins: 12
26 + spacing: 8
28 + // Header
29 + Row {
30 + spacing: 8
31 + Button {
32 + text: "Add"
33 + onClicked: tasks.append({ title: "New task " + (tasks.count + 1), done: false })
34 + }
35 + Button {
36 + text: "Clear done"
37 + onClicked: {
38 + for (let i = tasks.count - 1; i >= 0; i--) {
39 + if (tasks.get(i).done) tasks.remove(i)
40 + }
41 + }
42 + }
43 + }
45 + // The list
46 + ListView {
47 + width: parent.width
48 + height: parent.height - y
49 + clip: true
50 + spacing: 4
51 + model: tasks
53 + delegate: Rectangle {
54 + required property var modelData
55 + required property int index
56 + width: ListView.view.width
57 + implicitHeight: 44
58 + radius: 4
59 + color: modelData.done ? "#e8f5e9" : "white"
60 + border.color: "#ccc"
61 + border.width: 1
63 + Row {
64 + anchors.fill: parent
65 + anchors.leftMargin: 12
66 + anchors.rightMargin: 12
67 + spacing: 8
69 + CheckBox {
70 + anchors.verticalCenter: parent.verticalCenter
71 + checked: modelData.done
72 + onToggled: tasks.setProperty(index, "done", checked)
73 + }
74 + Text {
75 + anchors.verticalCenter: parent.verticalCenter
76 + text: modelData.title
77 + font.strikeout: modelData.done
78 + color: modelData.done ? "#888" : "black"
79 + }
80 + }
82 + // Click row to delete
83 + TapHandler {
84 + acceptedButtons: Qt.RightButton
85 + onTapped: tasks.remove(index)
86 + }
87 + }
89 + // Empty state
90 + Text {
91 + anchors.centerIn: parent
92 + visible: tasks.count === 0
93 + text: "No tasks. Click Add to start."
94 + color: "#999"
95 + }
96 + }
97 + }

skills/qml/examples/05-form/README.md

Added
new file mode 100644
1 +# 05 — form
3 +A two-column form: labels + inputs, live validation, two-way bindings.
5 +**Run:** `qml6 form.qml`
7 +**What it teaches:**
8 +- `ApplicationWindow` is `Window` with a header/footer/menu — a more capable top-level for app-like UIs.
9 +- `GridLayout { columns: 2 }` for label-input pairs. `Layout.columnSpan: 2` for a full-width row.
10 +- `readonly property bool isValid: ...` — a derived property that updates whenever its dependencies change.
11 +- Two-way binding: `TextField { onTextChanged: parent.parent.email = text }` pushes the field's value up; the property's value can be set externally and the field updates.
12 +- `echoMode: TextInput.Password` — password field.
13 +- `enabled: isValid` — disable the button when validation fails.
14 +- `Qt.callLater(fn)` — defer the work so the UI updates first.
16 +**What to break and learn from:**
17 +- Remove `readonly` from `isValid` — without `readonly`, you can assign to it; bindings can break.
18 +- Add `Layout.alignment: Qt.AlignRight` to all the `Label`s — they're right-aligned in the cell.
19 +- Set `Layout.columnSpan: 2` on the password row — the field stretches across both columns.
20 +- Replace the `readonly property` validation with a `function validate()` called from `onTextChanged` — works, but the UI won't react to changes; you'd need to manually trigger a re-render.
21 +- Move the field setup to a `Component { id: formField }` — the labels and inputs are repeated; a component cleans this up.
23 +**Common QML pattern:** forms are `GridLayout { columns: 2 }` with `Label` + `TextField` rows, plus a derived `isValid` property for live validation. The `readonly` keyword is essential for derived properties — without it, the binding can be silently broken by an external assignment.

skills/qml/examples/05-form/form.qml

Added
new file mode 100644
1 +// 05-form/form.qml
2 +// Form: GridLayout with labels + inputs, two-way bindings, validation.
3 +// Pure QML. Run with: qml6 form.qml
5 +import QtQuick
6 +import QtQuick.Window
7 +import QtQuick.Controls
8 +import QtQuick.Layouts
10 +ApplicationWindow {
11 + width: 420; height: 360
12 + visible: true
13 + title: "QML 05 — Form"
15 + property string name: ""
16 + property string email: ""
17 + property int age: 0
18 + property string password: ""
19 + property string confirmPassword: ""
21 + readonly property bool passwordsMatch: password === confirmPassword
22 + readonly property bool isValid:
23 + name.length > 0
24 + && email.includes("@")
25 + && age >= 13
26 + && passwordsMatch
27 + && password.length >= 8
29 + GridLayout {
30 + anchors.fill: parent
31 + anchors.margins: 16
32 + columnSpacing: 12
33 + rowSpacing: 8
34 + columns: 2
36 + Label { text: "Name:"; Layout.alignment: Qt.AlignRight }
37 + TextField {
38 + Layout.fillWidth: true
39 + placeholderText: "Your name"
40 + onTextChanged: parent.parent.name = text
41 + }
43 + Label { text: "Email:"; Layout.alignment: Qt.AlignRight }
44 + TextField {
45 + id: emailField
46 + Layout.fillWidth: true
47 + placeholderText: "you@example.com"
48 + onTextChanged: parent.parent.email = text
49 + }
51 + Label { text: "Age:"; Layout.alignment: Qt.AlignRight }
52 + SpinBox {
53 + from: 0; to: 120
54 + value: parent.parent.age
55 + onValueChanged: parent.parent.age = value
56 + }
58 + Label { text: "Password:"; Layout.alignment: Qt.AlignRight }
59 + TextField {
60 + id: pwField
61 + Layout.fillWidth: true
62 + echoMode: TextInput.Password
63 + onTextChanged: parent.parent.password = text
64 + }
66 + Label { text: "Confirm:"; Layout.alignment: Qt.AlignRight }
67 + TextField {
68 + id: confirmField
69 + Layout.fillWidth: true
70 + echoMode: TextInput.Password
71 + onTextChanged: parent.parent.confirmPassword = text
72 + }
74 + Item { Layout.columnSpan: 2; Layout.fillWidth: true; implicitHeight: 12 } // spacer
76 + Label { text: ""; Layout.alignment: Qt.AlignRight } // empty cell
77 + RowLayout {
78 + Layout.fillWidth: true
79 + spacing: 12
81 + Text {
82 + text: isValid ? "✓ Valid" : "✗ " + (passwordsMatch ? "" : "passwords don't match")
83 + color: isValid ? "green" : (passwordsMatch ? "#888" : "red")
84 + Layout.fillWidth: true
85 + }
87 + Button {
88 + text: "Submit"
89 + enabled: isValid
90 + onClicked: Qt.callLater(() => {
91 + console.log("submitted:", JSON.stringify({
92 + name, email, age, passwordLength: password.length
93 + }))
94 + })
95 + }
96 + }
97 + }

skills/qml/examples/06-animation/README.md

Added
new file mode 100644
1 +# 06 — animations
3 +QML has two animation styles: **implicit** (a `Behavior` on a property) and **explicit** (`NumberAnimation`, `SequentialAnimation`, etc.).
5 +**Run:** `qml6 animation.qml`
7 +**What it teaches:**
8 +- `Behavior on <property> { ... }` — any change to that property triggers the animation.
9 +- `NumberAnimation` for `int`/`real` values. `duration: ms`. `easing.type: Easing.InOutQuad`.
10 +- `ColorAnimation` for `color` properties.
11 +- `SequentialAnimation on <property>` — runs the animations one after another, looping.
12 +- `loops: Animation.Infinite` — loop forever.
13 +- `PauseAnimation { duration: ms }` — wait between steps.
14 +- `ParallelAnimation { ... }` — run multiple animations at once.
15 +- `NumberAnimation { target: otherItem; property: "x"; to: ... }` — animate a different item.
17 +**What to break and learn from:**
18 +- Remove the `Behavior on x` block on `implicitBox` — the box snaps to the new position; no smooth motion.
19 +- Set `running: false` on the `SequentialAnimation on y` — the bouncing ball stops.
20 +- Add `onRunningChanged: console.log("running:", running)` to the pulse — see when the animation starts/stops.
21 +- Add `PropertyAnimation` to animate a custom property: `property real hue: 0; PropertyAnimation { target: ...; property: "hue"; to: 360; duration: 2000; loops: -1 }` — animate a `real` from 0 to 360.
22 +- Use `Easing.OutElastic` on the bounce for a springy effect.
24 +**Common QML pattern:** use `Behavior` for "any change to this property should animate." Use `SequentialAnimation` / `ParallelAnimation` for choreographed multi-step animations. For complex sequences, build them in a function and start them on demand.

skills/qml/examples/06-animation/animation.qml

Added
new file mode 100644
1 +// 06-animation/animation.qml
2 +// Animations: implicit (Behavior) and explicit (NumberAnimation, SequentialAnimation).
3 +// Pure QML. Run with: qml6 animation.qml
5 +import QtQuick
6 +import QtQuick.Window
7 +import QtQuick.Controls
9 +Window {
10 + width: 480; height: 320
11 + visible: true
12 + title: "QML 06 — Animations"
13 + color: "#fafafa"
15 + // ---- Implicit animation via Behavior ----
16 + Rectangle {
17 + id: implicitBox
18 + x: 20; y: 20
19 + width: 60; height: 60
20 + radius: 8
21 + color: "tomato"
23 + Behavior on x {
24 + NumberAnimation { duration: 400; easing.type: Easing.InOutQuad }
25 + }
26 + Behavior on y {
27 + NumberAnimation { duration: 400; easing.type: Easing.InOutQuad }
28 + }
29 + Behavior on color {
30 + ColorAnimation { duration: 400 }
31 + }
33 + MouseArea {
34 + anchors.fill: parent
35 + drag.target: parent
36 + drag.axis: Drag.XAndYAxis
37 + onPressed: parent.color = "steelblue"
38 + onReleased: parent.color = "tomato"
39 + }
40 + }
42 + Text {
43 + x: 100; y: 32
44 + text: "Drag the red box — implicit Behavior animates x, y, color"
45 + color: "#666"
46 + }
48 + // ---- Explicit animation ----
49 + Rectangle {
50 + id: explicitBox
51 + x: 20; y: 120
52 + width: 60; height: 60
53 + radius: 30
54 + color: "mediumseagreen"
56 + SequentialAnimation on y {
57 + loops: Animation.Infinite
58 + running: true
59 + NumberAnimation { from: 120; to: 240; duration: 800; easing.type: Easing.OutBounce }
60 + PauseAnimation { duration: 400 }
61 + NumberAnimation { from: 240; to: 120; duration: 600; easing.type: Easing.InQuad }
62 + }
63 + }
65 + Text {
66 + x: 100; y: 132
67 + text: "Bouncing ball — explicit SequentialAnimation, infinite loop"
68 + color: "#666"
69 + }
71 + // ---- Triggered animation ----
72 + Rectangle {
73 + id: pulseBox
74 + x: 20; y: 240
75 + width: 40; height: 40
76 + radius: 4
77 + color: "goldenrod"
78 + }
80 + Text {
81 + x: 100; y: 252
82 + text: "Click the gold box to pulse"
83 + color: "#666"
84 + }
86 + Button {
87 + x: 280; y: 246
88 + text: "Pulse!"
89 + onClicked: pulseAnimation.start()
90 + }
92 + SequentialAnimation {
93 + id: pulseAnimation
94 + ParallelAnimation {
95 + NumberAnimation { target: pulseBox; property: "scale"; from: 1.0; to: 1.4; duration: 200 }
96 + ColorAnimation { target: pulseBox; property: "color"; to: "tomato"; duration: 200 }
97 + }
98 + NumberAnimation { target: pulseBox; property: "scale"; from: 1.4; to: 1.0; duration: 200 }
99 + ColorAnimation { target: pulseBox; property: "color"; to: "goldenrod"; duration: 200 }

skills/qml/examples/07-tabs/README.md

Added
new file mode 100644
1 +# 07 — tabs
3 +`TabBar` + `StackLayout`: the canonical pattern for top-level navigation.
5 +**Run:** `qml6 tabs.qml`
7 +**What it teaches:**
8 +- `TabBar { TabButton { text: "..." } }` — one tab per `TabButton`. `currentIndex` is auto-managed.
9 +- `StackLayout { currentIndex: bar.currentIndex }` — show one child at a time, indexed by the tab bar.
10 +- `Layout.fillWidth: true` and `Layout.fillHeight: true` on the StackLayout makes it fill the column.
11 +- Each child of the StackLayout is a full "page" of the app.
13 +**What to break and learn from:**
14 +- Add a 4th tab and page — `TabButton { text: "..." }` and a child of the StackLayout.
15 +- Add icons: `TabButton { icon.name: "go-home" }` — uses the system icon theme.
16 +- Set `currentIndex: 1` on the StackLayout — opens to the Settings tab.
17 +- Add a `SwipeView` from `QtQuick.Controls` instead of `StackLayout` — touch-swipeable pages. Pair with `TabBar` to keep them in sync.
18 +- Animate the transition: `Behavior on currentIndex { NumberAnimation { duration: 200 } }` on the StackLayout — but the transition is between two children, not a single property; this is harder. For animated transitions, use `SwipeView` or a `StackView` with `replaceEnter`/`replaceExit` transitions.
20 +**Common QML pattern:** tabs are a `TabBar` and a `StackLayout` with `currentIndex` bound together. Add a `SwipeView` if you want touch-swipe support.

skills/qml/examples/07-tabs/tabs.qml

Added
new file mode 100644
1 +// 07-tabs/tabs.qml
2 +// Tabs: TabBar + StackLayout. Common pattern for top-level navigation.
3 +// Pure QML. Run with: qml6 tabs.qml
5 +import QtQuick
6 +import QtQuick.Window
7 +import QtQuick.Controls
9 +ApplicationWindow {
10 + width: 480; height: 320
11 + visible: true
12 + title: "QML 07 — Tabs"
14 + ColumnLayout {
15 + anchors.fill: parent
16 + spacing: 0
18 + TabBar {
19 + id: bar
20 + Layout.fillWidth: true
21 + TabButton { text: "Home" }
22 + TabButton { text: "Settings" }
23 + TabButton { text: "About" }
24 + }
26 + StackLayout {
27 + id: stack
28 + Layout.fillWidth: true
29 + Layout.fillHeight: true
30 + currentIndex: bar.currentIndex
32 + // Home page
33 + Item {
34 + Column {
35 + anchors.centerIn: parent
36 + spacing: 12
37 + Text { text: "Home"; font.pixelSize: 24; font.bold: true }
38 + Text { text: "Welcome to the QML skill demo."; color: "#666" }
39 + }
40 + }
42 + // Settings page
43 + Item {
44 + Column {
45 + anchors.fill: parent
46 + anchors.margins: 16
47 + spacing: 8
48 + Text { text: "Settings"; font.pixelSize: 20; font.bold: true }
49 + CheckBox { text: "Enable animations" }
50 + CheckBox { text: "Show advanced" }
51 + RowLayout {
52 + Label { text: "Volume:" }
53 + Slider { Layout.fillWidth: true; from: 0; to: 100; value: 50 }
54 + }
55 + }
56 + }
58 + // About page
59 + Item {
60 + Column {
61 + anchors.centerIn: parent
62 + spacing: 8
63 + Text { text: "About"; font.pixelSize: 24; font.bold: true }
64 + Text { text: "QML 07 — Tabs example"; color: "#666" }
65 + Text { text: "Demonstrates TabBar + StackLayout"; color: "#888"; font.pixelSize: 12 }
66 + }
67 + }
68 + }
69 + }

skills/qml/references/common-pitfalls.md

Added
new file mode 100644
1 +# Common Pitfalls
3 +The mistakes that catch everyone once. Re-read before debugging a "weird" QML behavior.
5 +## 1. `childrenRect` binding loop
7 +```qml
8 +Item {
9 + implicitWidth: childrenRect.width // WRONG: creates a loop
10 + implicitHeight: childrenRect.height
11 + Rectangle {
12 + anchors.fill: parent
13 + implicitWidth: 50
14 + implicitHeight: 50
15 + }
17 +```
19 +`childrenRect` is the actual geometry of children, not implicit. The container's `implicitWidth` ends up depending on itself. The QML engine may resolve to a value, but the result is wrong (usually 0×0).
21 +**Fix:** use anchors (so the parent sets actual size) and let the child set `implicitWidth`/`implicitHeight`:
23 +```qml
24 +Item {
25 + Rectangle {
26 + anchors.fill: parent
27 + implicitWidth: 50
28 + implicitHeight: 50
29 + }
31 +```
33 +Or use a `Column`/`Row` for stacking, or `MarginWrapperManager` (Quickshell extension) for auto-margin.
35 +## 2. Zero-size items
37 +```qml
38 +Item {
39 + property string label: "hello"
40 + // No implicitWidth/Height; no children with size
41 + // → 0×0, invisible.
43 +```
45 +`Item` defaults to 0×0. The engine may warn on first show. Always set `implicitWidth`/`implicitHeight` (or use a child that has them) for visible components.
47 +For invisible containers, set `width: 0; height: 0` explicitly to silence the warning.
49 +## 3. Binding "fight" (read and write the same property)
51 +```qml
52 +Slider {
53 + value: model.volume
54 + onValueChanged: model.volume = value
56 +```
58 +This *looks* like a loop but isn't. The `onValueChanged` handler fires when the user moves the slider; the assignment to `model.volume` breaks the binding to it. The next read of `model.volume` re-evaluates the `value:` binding. Standard QML behavior.
60 +The **real** binding fight is when an external system writes back to a bound property, causing infinite re-evaluation. The fix is to set one side explicitly (`value: ...; onMoved: ... = value` — `onMoved` fires only for user gestures, not programmatic changes).
62 +## 4. Forgetting to declare a property
64 +```qml
65 +Item {
66 + Component.onCompleted: count = 5 // ReferenceError: count is not defined
68 +```
70 +`count` isn't a property of `Item`. Either:
72 +```qml
73 +Item {
74 + property int count: 0
75 + Component.onCompleted: count = 5
77 +```
79 +Or accept it as a `property var` on the parent.
81 +## 5. JavaScript expression outside a binding
83 +```qml
84 +Text {
85 + text: { // WRONG: this is a JS object literal, not a binding
86 + const x = "hello"
87 + x
88 + }
90 +```
92 +`{` after `:` starts a multi-line binding (returns the last value as the result). To get an object literal, use `({})` or `Qt.binding` is not a thing — just `property var obj: ({ a: 1 })`.
94 +## 6. Mixing `width` and `anchors.fill`
96 +```qml
97 +Rectangle {
98 + anchors.fill: parent
99 + width: 100 // ignored when anchors.fill is set
101 +```
103 +`anchors.fill` sets left/right/top/bottom, which the parent uses to determine the rectangle's size. A `width: 100` will be overwritten. Pick one.
105 +## 7. Looping with bindings
107 +```qml
108 +Item {
109 + property int a: 1
110 + property int b: a + 1
111 + property int c: b + 1 // b changes → c changes. OK.
112 + Component.onCompleted: a = 5 // → b = 6, c = 7. OK.
114 +```
116 +But:
118 +```qml
119 +Item {
120 + property int a: b + 1 // forward reference
121 + property int b: 0
123 +```
125 +is fine — declaration order doesn't matter for bindings; only the dependency graph does. **The engine detects cycles and breaks them at runtime** — your code won't error, it'll just be wrong.
127 +## 8. `null` and undefined
129 +```qml
130 +property var maybeUser: someObj?.user
131 +property string name: maybeUser?.name ?? "anonymous"
132 +```
134 +`?.` is optional access (returns `undefined` if any link is null). `??` is nullish coalescing. Use both for safe navigation of uncertain structures.
136 +**Without `?.`:** `undefined.foo` throws at runtime.
138 +## 9. Forgetting `id` for cross-reference
140 +```qml
141 +Item {
142 + Text {
143 + text: parent.parent.label // works but brittle
146 +```
148 +```qml
149 +Item {
150 + id: root
151 + Text {
152 + text: root.label // explicit, survives refactor
155 +```
157 +Always use an id for cross-references.
159 +## 10. Component reuse — only one `id` per scope
161 +```qml
162 +Repeater {
163 + model: 3
164 + Rectangle {
165 + id: r // ERROR: each delegate is a new scope, but you used the same id name in source
168 +```
170 +`Repeater` doesn't actually conflict here because each delegate is a separate component instantiation. But:
172 +```qml
173 +Item {
174 + id: root
175 + Rectangle { id: r; ... }
176 + Rectangle { id: r; ... } // ERROR: duplicate id
178 +```
180 +Id is unique within a single component scope. Use a counter or different names.
182 +## 11. Binding doesn't react to JS object changes
184 +```qml
185 +property var config: ({ theme: "dark" })
186 +text: config.theme === "dark" ? "white" : "black"
187 +config.theme = "light" // does NOT trigger text to re-evaluate
188 +```
190 +QML's reactivity tracks property accesses, not deep object mutations. To trigger re-eval, re-assign the whole var:
192 +```qml
193 +config = ({ ...config, theme: "light" })
194 +```
196 +Or use a real `Q_PROPERTY` on a C++ object.
198 +## 12. Wrong focus target
200 +```qml
201 +Item {
202 + Keys.onPressed: (event) => { ... } // never fires
204 +```
206 +`Item` doesn't have focus. For key handling to work, the item must be `focus: true` AND be the focus owner. For fullscreen key handling, use a `Shortcut` instead:
208 +```qml
209 +Shortcut {
210 + sequence: "Ctrl+S"
211 + onActivated: save()
213 +```
215 +## 13. Text not wrapping
217 +```qml
218 +Text {
219 + text: longString
220 + width: 200
221 + // doesn't wrap because the implicitWidth is unbounded
223 +```
225 +Add `wrapMode: Text.Wrap` or `wrapMode: Text.WordWrap`. Or set an explicit `width` (which you did) — the issue may be the parent not constraining it.
227 +## 14. MouseArea on a child doesn't get clicks
229 +```qml
230 +Rectangle {
231 + color: "red"
232 + Text {
233 + anchors.centerIn: parent
234 + text: "click"
236 + MouseArea {
237 + anchors.fill: parent
238 + onClicked: console.log("clicked")
241 +```
243 +The Text consumes clicks if it has its own MouseArea (or some other focus/interactivity). The Rectangle's MouseArea might not get the click.
245 +**Fix:** add `MouseArea { anchors: fill; preventStealing: true }` to the Text, or put the MouseArea on top of the Text.
247 +## 15. Children of a `Loader` aren't children of the parent
249 +```qml
250 +Item {
251 + id: parent
252 + Loader {
253 + id: l
254 + sourceComponent: Rectangle { color: "red" }
256 + Component.onCompleted: console.log(children.length) // 1 (the Loader, not the Rectangle)
258 +```
260 +The `Loader`'s loaded item is a child of the Loader, not the parent. To access it: `l.item`.
262 +## 16. `Component.onCompleted` doesn't fire for items inside a `Loader` until loaded
264 +```qml
265 +Loader {
266 + sourceComponent: Item {
267 + Component.onCompleted: console.log("loaded")
270 +```
272 +`Component.onCompleted` fires when the component is instantiated — for Loader items, that's when `active: true` (or when `sourceComponent` is set and the item loads).
274 +## 17. JSON parsing failure
276 +```qml
277 +property var data: JSON.parse(text)
278 +```
280 +If `text` is invalid JSON, this throws and the property is never set. Wrap in a try-catch:
282 +```qml
283 +property var data: {
284 + try { return JSON.parse(text) }
285 + catch (e) { return null }
287 +```
289 +## 18. QML reloading state
291 +When you save a `.qml` file, QML hot-reloads. Some state is lost (component instances), some is preserved (`PersistentProperties` in Quickshell; `Settings` in Qt.labs.settings). Plan for state loss during development.
293 +## Quick debugging
295 +- Add `console.log("here", value)` in suspect expressions.
296 +- Use `Component.onCompleted: console.log(JSON.stringify(props))` to dump an object.
297 +- Set `visible: true` on hidden components to see them.
298 +- Use `Qt.application.debugging` or attach `qml --inspect` to debug interactively.
299 +- Check the runtime log (`log.log` in Quickshell; Qt prints to stderr) for binding loop warnings.
301 +## See also
303 +- `references/components.md` — for the `id` rules and component reuse
304 +- `references/layouts.md` — for the `childrenRect` trap and sizing
305 +- `references/signals.md` — for `Shortcut` and event handling
306 +- `references/javascript.md` — for binding-vs-imperative-assignment rules

skills/qml/references/components.md

Added
new file mode 100644
1 +# Components
3 +A QML **component** is a reusable type defined as a `.qml` file. The file's root object becomes the type. Every consumer instantiates that root as a child.
5 +## Defining a component
7 +`MyButton.qml` (PascalCase, same directory as the consumer):
9 +```qml
10 +import QtQuick
11 +import QtQuick.Controls
13 +Button {
14 + property string iconName: ""
15 + property var onActivate: () => {}
17 + icon.name: iconName
18 + onClicked: onActivate()
20 +```
22 +Consumer:
24 +```qml
25 +import "."
27 +Column {
28 + spacing: 8
29 + MyButton { text: "Save"; iconName: "document-save"; onActivate: () => save() }
30 + MyButton { text: "Cancel"; iconName: "dialog-cancel" }
32 +```
34 +The consumer treats the file as a type. Property assignments go to the matching `property` declarations in the file. `id` inside the file is private.
36 +## Required properties
38 +Use `required` to force the consumer to provide a value:
40 +```qml
41 +// UserCard.qml
42 +import QtQuick
44 +Item {
45 + required property var user
46 + required property string role
48 + Text { text: user.name + " (" + role + ")" }
50 +```
52 +Consumer:
54 +```qml
55 +UserCard {
56 + user: currentUser
57 + role: "admin"
59 +// omitting user or role → qmllint error
60 +```
62 +## Default properties
64 +Mark one property as `default` so the consumer can put an object child inside instead of using the property name:
66 +```qml
67 +// Card.qml
68 +import QtQuick
70 +Rectangle {
71 + color: "white"
72 + border.color: "gray"
73 + border.width: 1
74 + radius: 4
76 + default property alias contents: inner.data
77 + property alias body: inner
79 + Item {
80 + id: inner
81 + anchors.fill: parent
82 + anchors.margins: 8
83 + }
85 +```
87 +Consumer — both forms work:
89 +```qml
90 +// Form 1: explicit
91 +Card { body: Column { Text {} Button {} } }
93 +// Form 2: shorthand (default property)
94 +Card {
95 + Column { Text {} Button {} }
97 +```
99 +The shorthand works because `default property alias contents: inner.data` makes any child object go into `inner.data`.
101 +## Inline components
103 +For a one-shot type used in one file only:
105 +```qml
106 +import QtQuick
108 +Item {
109 + component NumberedLabel: Row {
110 + property int number
111 + property string text
112 + Text { text: number + ". " + parent.text }
115 + Column {
116 + NumberedLabel { number: 1; text: "First" }
117 + NumberedLabel { number: 2; text: "Second" }
120 +```
122 +`component Name: Type { ... }` defines a type inside the file. It can reference outer ids. Use this for small specialized types that don't deserve their own file.
124 +## Aliases
126 +`property alias name: <target>.<property>` exposes a sub-object's property as your own:
128 +```qml
129 +// MyText.qml
130 +Text {
131 + property alias body: text // re-export `text` as `body`
132 + text: ""
134 +```
136 +```qml
137 +// Consumer
138 +MyText {
139 + body: "hello" // sets the inner `text` property
141 +```
143 +Aliases are **live** — they re-evaluate when the target changes. Use them to expose only the parts of an internal object that consumers need.
145 +## File organization
147 +| Pattern | When |
148 +| --- | --- |
149 +| Inline component (`component X: Item { ... }`) | Type is local to one file. |
150 +| `X.qml` neighbor | Type is small and used in this directory. |
151 +| `widgets/X.qml` + `import "widgets" as W` | Larger project, multiple subdirs. |
152 +| `qmldir` for the directory | Best LSP support for `widgets/`. |
153 +| C++ `Q_OBJECT` registered with `QML_ELEMENT` | High-performance or library types. |
155 +## The "must start with uppercase" rule
157 +A QML object literal `Foo { ... }` is parsed as an object instance. A lowercase identifier `foo` is parsed as a property binding or reference. The casing rule is what makes this unambiguous:
159 +- `MyButton {}` — instantiate the type `MyButton`
160 +- `myButton: someId` — bind the property `myButton`
162 +## Component vs Item
164 +`Item` is the base non-visual type. `Rectangle`, `Text`, `Image` are all `Item` subclasses. For a custom non-visual type, extend `Item` (or `QtObject` for purely behavioral types without visual children).
166 +`QtObject` is the lightest type — no visual tree participation. Use for value types, model wrappers, etc. Needs `import QtQml`.
168 +## Singleton component
170 +Mark a component as a singleton to make it accessible by name from anywhere in the same module:
172 +```qml
173 +// Theme.qml
174 +pragma Singleton
175 +import QtQuick
177 +QtObject {
178 + readonly property color primary: "#3367d6"
179 + readonly property color background: "#fafafa"
181 +```
183 +Add it to a `qmldir`:
185 +```
186 +singleton Theme 1.0 Theme.qml
187 +```
189 +Use it:
191 +```qml
192 +import MyModule 1.0
193 +Rectangle { color: Theme.background }
194 +```
196 +Singletons are useful for app-wide theme/config. They live in the engine's QML context.
198 +## Reusable component checklist
200 +- [ ] File name is PascalCase.
201 +- [ ] Root type is the smallest useful base (`Item`, `QtObject`, or a specific visual).
202 +- [ ] `required` for any property the consumer must set.
203 +- [ ] `default property` for the most-likely-set child.
204 +- [ ] `property alias` to expose internal sub-object properties cleanly.
205 +- [ ] `signal` for events the consumer should listen to.
206 +- [ ] `Component.onCompleted` for one-time setup.
208 +## Common mistakes
210 +- **Forgetting `required`** — qmllint can catch a missing property, but a non-required one with no default value silently evaluates to `undefined` at runtime.
211 +- **`property var` overuse** — `var` defeats qmllint. Use the specific type (`string`, `int`, `var model: MyType`).
212 +- **Two `default` properties** — QML allows only one `default`. The second one will throw a parse error.
213 +- **Alias to a non-existent target** — `property alias x: y` requires `y` to be an id in scope.
214 +- **Alias to a function** — aliases work for properties, not for functions. Use a plain function declaration.

skills/qml/references/javascript.md

Added
new file mode 100644
1 +# JavaScript in QML
3 +Every QML expression is JavaScript. You can write `property int x: 1 + 2`, run a loop in a function, or import a full `.js` file.
5 +## Inline expressions
7 +```qml
8 +Item {
9 + property int doubled: count * 2
10 + visible: name.length > 0
11 + color: enabled ? "red" : "gray"
12 + text: `Hello, ${name}!` // template literal
14 +```
16 +Most expressions are JS. Multi-line:
18 +```qml
19 +property var result: {
20 + const x = compute(x)
21 + const y = compute(y)
22 + return x + y
24 +```
26 +## Functions
28 +```qml
29 +Item {
30 + function square(x: int): int { return x * x }
31 + function notify(msg: string): void { console.log(msg) }
33 + Component.onCompleted: notify("x² = " + square(5))
35 +```
37 +Type annotations (`int`, `string`, `void`) are optional. The function body is full JS.
39 +## Lambdas
41 +```qml
42 +Item {
43 + property var adder: (a, b) => a + b
44 + property var doubler: (x) => x * 2
46 + Button {
47 + onClicked: (mouse) => console.log("at", mouse.x, mouse.y)
48 + }
50 +```
52 +Lambdas (arrow functions) work anywhere a function is expected. The most common use: signal handler with arguments.
54 +## Property aliases to functions
56 +You can't `property alias` a function, but you can wrap it:
58 +```qml
59 +// MyButton.qml
60 +Button {
61 + property var onActivate: () => {}
62 + onClicked: onActivate()
64 +```
66 +## Imports
68 +```qml
69 +// helpers.js
70 +.pragma library
72 +function format(n) { return n.toFixed(2) }
73 +function greet(name) { return `Hello, ${name}` }
74 +```
76 +```qml
77 +// Consumer
78 +import "helpers.js" as Helpers
80 +Item {
81 + Text { text: Helpers.greet("world") }
82 + Text { text: Helpers.format(3.14159) }
84 +```
86 +`.pragma library` (in the .js file) makes the file a stateless library — its top-level state is shared across all importers, not per-importer.
88 +## Captures
90 +QML objects can be captured by id and used inside JS:
92 +```qml
93 +Item {
94 + id: root
95 + property int count: 0
96 + Timer {
97 + interval: 1000; running: true; repeat: true
98 + onTriggered: root.count++ // bind through id, not closure
99 + }
101 +```
103 +Capturing `root` (by id) is the canonical way. Closures over local variables work but are less reliable across re-instantiation.
105 +## `Qt.*` helpers
107 +```qml
108 +Qt.formatDate(date, "yyyy-MM-dd")
109 +Qt.formatTime(date, "HH:mm:ss")
110 +Qt.formatDateTime(date, "yyyy-MM-dd HH:mm")
111 +Qt.rgba(0.5, 0, 0, 1)
112 +Qt.hsva(h, s, v, a)
113 +Qt.lighter(color, factor)
114 +Qt.darker(color, factor)
115 +Qt.tint(baseColor, tintColor)
116 +Qt.callLater(fn, ...args) // schedule fn for next event loop tick
117 +Qt.application.name
118 +Qt.application.version
119 +Qt.platform.os // "linux", "windows", "osx", "android", "ios"
120 +Qt.platform.osVersion
121 +Qt.inputMethod // IM state
122 +Qt.styleHints // UI style hints
123 +```
125 +`Qt.callLater` is the right way to defer work to the next event-loop iteration (without a `Timer`).
127 +## Object literals
129 +QML objects are JS objects with type semantics. You can construct them in JS:
131 +```qml
132 +property var point: Qt.point(10, 20)
133 +property var size: Qt.size(100, 50)
134 +property var rect: Qt.rect(0, 0, 100, 50)
135 +property var list: ["a", "b", "c"]
136 +property var map: ({ a: 1, b: 2 })
137 +```
139 +Mutating a `var` doesn't trigger binding updates (the binding tracks property reads, not deep changes). For observable state, use `Q_PROPERTY` on a C++ object, or a ListModel.
141 +## Async work
143 +QML doesn't have native promises but has some workarounds:
145 +```qml
146 +Item {
147 + Timer {
148 + interval: 100
149 + running: true
150 + onTriggered: doDeferredWork()
154 +// Or chain with Qt.callLater
155 +function doChain() {
156 + step1()
157 + Qt.callLater(() => { step2(); Qt.callLater(step3) })
159 +```
161 +For real async, use a `WorkerScript` (deprecated in Qt 6) or a C++ QObject with `Q_INVOKABLE` methods that return a `QFuture` (Qt 6+).
163 +## Iterating
165 +```qml
166 +property var items: [1, 2, 3, 4, 5]
168 +// for-of
169 +for (const x of items) console.log(x)
171 +// for-in (over keys, for plain objects)
172 +for (const k in ({a: 1, b: 2})) console.log(k, ":", this[k])
174 +// map
175 +const doubled = items.map(x => x * 2)
177 +// filter
178 +const evens = items.filter(x => x % 2 === 0)
180 +// reduce
181 +const sum = items.reduce((acc, x) => acc + x, 0)
182 +```
184 +JS array methods work as expected. Note: the result is a plain JS array, not a model — bindings to it won't reactively update.
186 +## Strings
188 +```qml
189 +property var s: "Hello, World"
191 +s.length // 12
192 +s.indexOf("World") // 7
193 +s.toUpperCase() // "HELLO, WORLD"
194 +s.split(", ") // ["Hello", "World"]
195 +s.startsWith("Hello") // true
196 +s.includes("World") // true
197 +s.replace("World", "QML") // "Hello, QML"
198 +s.padStart(20, "-") // "-------Hello, World"
199 +```
201 +`Number.toFixed(2)`, `Date.toISOString()`, `Math.PI`, `JSON.parse`, `JSON.stringify` all work.
203 +## Common mistakes
205 +- **Heavy work in a binding** — bindings re-evaluate on every dependency change. Long-running JS in a binding blocks the UI. Use a function called from a `Timer` instead.
206 +- **Mutating a `var` property** — the binding doesn't re-evaluate. Use a real `Q_PROPERTY` or replace the whole var.
207 +- **Using `this` in a delegate** — `this` refers to the delegate context, which can be confusing. Bind by id or by the model role.
208 +- **Forgetting `Qt.callLater` for cross-binding side-effects** — if a binding changes a property that another binding depends on, you can get a binding loop. Defer with `Qt.callLater`.
209 +- **Capturing local variables in a long-lived closure** — they don't update. Bind to a property instead.
211 +## When to use JS vs C++
213 +| Use JS for | Use C++ for |
214 +| --- | --- |
215 +| Property expressions | High-performance loops over millions of items |
216 +| Small algorithms (sort, filter) | Database access |
217 +| UI glue (toggle, format) | Image processing |
218 +| One-time setup | Heavy data models |
219 +| Validation | Network I/O |
221 +For anything CPU-bound or data-heavy, push it to C++ via `Q_INVOKABLE` and `Q_PROPERTY` and bind to the result.

skills/qml/references/layouts.md

Added
new file mode 100644
1 +# Layouts
3 +QML has two layout systems: **anchors** (manual, for one-off cases) and **Layouts** (`RowLayout`, `ColumnLayout`, etc., for repeated structure). Pick one and stick with it in a region.
5 +## The cardinal rule
7 +> **Implicit size flows child → parent. Actual size flows parent → child.**
9 +| Direction | Property | Use |
10 +| --- | --- | --- |
11 +| Child → parent | `implicitWidth`, `implicitHeight` | "I want to be this big." |
12 +| Parent → child | `width`, `height` | "You are this big." |
14 +Containers (`RowLayout`, `GridLayout`, `Item`-based) read children's `implicitWidth`/`implicitHeight` to determine their own size, then assign `width`/`height` to children. A child that sets both will be overwritten by the container.
16 +## Anchors
18 +Quick positional layout. Use for one-off positioning, not for whole UIs.
20 +```qml
21 +Rectangle {
22 + // fill
23 + anchors.fill: parent
24 + anchors.margins: 8 // uniform margin
26 + // stretch one axis
27 + anchors.left: parent.left
28 + anchors.right: parent.right
30 + // center
31 + anchors.centerIn: parent
32 + anchors.horizontalCenter: parent.horizontalCenter
33 + anchors.verticalCenter: parent.verticalCenter
35 + // pin to a side
36 + anchors.top: parent.top
37 + anchors.bottom: parent.bottom
39 + // margins (per side)
40 + anchors.leftMargin: 16
41 + anchors.rightMargin: 16
42 + anchors.topMargin: 8
43 + anchors.bottomMargin: 8
45 +```
47 +- `anchors.fill: parent` is shorthand for left/right/top/bottom all true.
48 +- Margins can be set per-side or via `anchors.margins: <n>` (all four).
49 +- Mixing anchors with `width`/`height` is usually wrong — pick one.
51 +## Layouts (QtQuick.Layouts)
53 +```qml
54 +import QtQuick.Layouts
56 +RowLayout { // horizontal
57 + spacing: 8
58 + Text { text: "First" }
59 + Item { Layout.fillWidth: true } // spacer
60 + Text { text: "Last" }
63 +ColumnLayout { spacing: 8 } // vertical
64 +GridLayout { columns: 3 } // grid, 3 wide
65 +StackLayout { currentIndex: 0 } // only one child visible
66 +```
68 +`Layout.*` attached properties:
70 +| Property | Effect |
71 +| --- | --- |
72 +| `Layout.fillWidth: true` | Stretch to fill the row width. |
73 +| `Layout.fillHeight: true` | Stretch to fill the column height. |
74 +| `Layout.preferredWidth: 100` | The size before stretching. |
75 +| `Layout.minimumWidth: 50` | Won't go below this. |
76 +| `Layout.maximumWidth: 200` | Won't go above this. |
77 +| `Layout.alignment: Qt.AlignCenter` | Position within the cell. |
78 +| `Layout.leftMargin: 8` | Per-side margin override. |
79 +| `Layout.row: 0` / `Layout.column: 1` | For `GridLayout` — explicit cell. |
80 +| `Layout.rowSpan: 2` / `Layout.columnSpan: 2` | For `GridLayout` — span cells. |
82 +`Layout.fillWidth: true` + `Layout.fillHeight: true` is the "make me stretch in both directions" combo.
84 +## GridLayout
86 +```qml
87 +GridLayout {
88 + columns: 2
89 + columnSpacing: 16
90 + rowSpacing: 8
92 + Label { text: "Name:"; Layout.alignment: Qt.AlignRight }
93 + TextField { Layout.fillWidth: true }
95 + Label { text: "Email:"; Layout.alignment: Qt.AlignRight }
96 + TextField { Layout.fillWidth: true }
98 +```
100 +A simple form: two columns, `Label` in column 1, `TextField` in column 2.
102 +## The childrenRect trap
104 +A common bug:
106 +```qml
107 +Item {
108 + implicitWidth: childrenRect.width // WRONG
109 + implicitHeight: childrenRect.height
110 + Rectangle {
111 + anchors.fill: parent
112 + implicitWidth: 50
113 + implicitHeight: 50
116 +```
118 +`childrenRect` is the **actual** geometry of the children, not the implicit. Binding `implicitWidth` to it makes the container's size depend on itself (`container.implicitWidth = container.width via anchor = container.implicitWidth = ...`), which is a binding loop.
120 +The right answer is to use anchors (so the container sets the child's actual size) and let the child set `implicitWidth`/`implicitHeight` (which the container reads):
122 +```qml
123 +Item {
124 + Rectangle {
125 + anchors.fill: parent
126 + implicitWidth: 50
127 + implicitHeight: 50
130 +```
132 +Or use `MarginWrapperManager` (Quickshell extension) or `Column`/`Row` for auto-stacking.
134 +## StackLayout
136 +Only one child is visible at a time:
138 +```qml
139 +StackLayout {
140 + currentIndex: 1 // show the second child
141 + Page1 {}
142 + Page2 {}
143 + Page3 {}
145 +```
147 +`currentIndex` is the visible child. Use with `TabBar { onCurrentIndexChanged: stack.currentIndex = currentIndex }` for tabbed UIs.
149 +## Repeater inside a Layout
151 +```qml
152 +ColumnLayout {
153 + Repeater {
154 + model: ["a", "b", "c"]
155 + Text { text: modelData } // modelData is auto-injected
158 +```
160 +`Repeater` instantiates one delegate per model item, as a child of the parent layout. The delegates are added/removed when the model changes.
162 +## Common mistakes
164 +- **Setting `width` and `height` in a Layout child** — the Layout will overwrite these. Use `Layout.preferredWidth`.
165 +- **Mixing `anchors.fill` with `width`/`height`** — choose one.
166 +- **Putting a non-`Item` in a Layout** — Layouts only arrange `Item` subclasses. For a plain string, wrap in `Text` or `Label`.
167 +- **Binding to `childrenRect`** — creates a loop. Use anchors or layouts.
168 +- **Forgetting `Layout.fillWidth`** — your child will be its `implicitWidth` and the row will have a lot of empty space on the right.
170 +## What to choose
172 +| Use case | Pick |
173 +| --- | --- |
174 +| Single rectangle pinned to a corner | `anchors` |
175 +| 3 buttons in a row | `RowLayout` |
176 +| Form with labels + fields | `GridLayout { columns: 2 }` |
177 +| Tabbed views | `StackLayout` + `TabBar` |
178 +| Scrollable list | `ListView` (not a Layout) |
179 +| Auto-margin (no binding loops) | `MarginWrapperManager` (Quickshell extension, see `quickshell` skill) |

skills/qml/references/models.md

Added
new file mode 100644
1 +# Models and Views
3 +A **model** is a thing that produces rows of data. A **view** is the visual representation. QML separates them: the view doesn't care where the data comes from, the model doesn't care how it's rendered.
5 +## Inline model: `ListModel`
7 +```qml
8 +import QtQuick
10 +ListModel {
11 + id: list
12 + ListElement { name: "Alice"; age: 30 }
13 + ListElement { name: "Bob"; age: 25 }
16 +ListView {
17 + model: list
18 + delegate: ItemDelegate {
19 + text: name + " (" + age + ")"
20 + }
22 +```
24 +`ListElement` is a literal row. Property names become **roles** that the delegate can bind to by name (e.g. `name` and `age`).
26 +## JS array as a model
28 +```qml
29 +Repeater {
30 + model: [{name: "Alice"}, {name: "Bob"}]
31 + Text { text: modelData.name }
33 +```
35 +A plain JS array works for static data. Each element is `modelData`.
37 +## Built-in model types
39 +| Type | Source |
40 +| --- | --- |
41 +| `ListModel` | JS appendable list of `ListElement`. |
42 +| `ObjectModel` | List of arbitrary QML objects; delegates are the actual instances. |
43 +| `XmlListModel` | Parses XML. |
44 +| `QAbstractListModel` (C++) | The Qt-standard way to expose data to QML. |
45 +| Any `QAbstractItemModel` | Tree/table models. |
46 +| A JS array | Static list. |
47 +| A number (`model: 10`) | Repeats the delegate N times, `index` is 0..N-1. |
49 +## Built-in views
51 +| View | Use |
52 +| --- | --- |
53 +| `Repeater` | Inline; instantiates one delegate per model row, no scrolling. |
54 +| `ListView` | Scrollable vertical list; recycles delegates. |
55 +| `GridView` | Scrollable grid. |
56 +| `PathView` | Along a `Path`. |
57 +| `TableView` | Tabular (rows × columns). |
59 +`Repeater` is the simplest. `ListView` recycles (only visible rows are kept in memory) — important for long lists.
61 +## Repeater pattern
63 +```qml
64 +Column {
65 + Repeater {
66 + model: 5 // count, or array, or ListModel
67 + Rectangle {
68 + width: 100; height: 30
69 + color: index % 2 ? "lightgray" : "white"
70 + Text { anchors.centerIn: parent; text: "row " + index }
71 + }
72 + }
74 +```
76 +`index` is auto-injected as the row number. `modelData` is the row value (for array models).
78 +## ListView pattern
80 +```qml
81 +ListView {
82 + width: 200; height: 300
83 + model: listModel
84 + spacing: 4
85 + clip: true // don't show content outside the view
87 + delegate: ItemDelegate {
88 + width: ListView.view.width
89 + text: model.name
90 + onClicked: console.log("clicked", model.name)
91 + }
93 + ScrollBar.vertical: ScrollBar { }
95 +```
97 +Key things:
98 +- `ListView.view.width` references the enclosing ListView's width — use this in delegates for full-width rows.
99 +- `clip: true` prevents drawing outside the view's bounds.
100 +- Add a `ScrollBar.vertical` (from `QtQuick.Controls`) for usability.
102 +## Sectioning
104 +`ListView.section.property` groups rows by a role value:
106 +```qml
107 +ListView {
108 + model: myModel
109 + section.property: "category" // role name
110 + section.delegate: Label { text: section }
111 + delegate: ItemDelegate { text: name }
113 +```
115 +## Dynamic models
117 +For data that changes, use `ListModel`'s `append`/`remove`/`set`:
119 +```qml
120 +ListModel {
121 + id: tasks
124 +Button {
125 + text: "Add"
126 + onClicked: tasks.append({ title: "New task", done: false })
129 +ListView {
130 + model: tasks
131 + delegate: CheckBox { text: title; checked: done }
133 +```
135 +The view re-renders when the model changes. No manual refresh needed.
137 +## C++ models (the high-performance path)
139 +```cpp
140 +class TaskList : public QAbstractListModel {
141 + Q_OBJECT
142 + QML_ELEMENT
143 +public:
144 + enum Roles { TitleRole = Qt::UserRole + 1, DoneRole };
145 + int rowCount(...) const override;
146 + QVariant data(...) const override;
147 + QHash<int, QByteArray> roleNames() const override;
148 + // ...
150 +```
152 +Register with `qmlRegisterType` or `QML_ELEMENT` macro. From QML:
154 +```qml
155 +import MyApp
157 +TaskList { id: tasks }
158 +ListView { model: tasks }
159 +```
161 +`roleNames()` exposes role names to QML (`title`, `done` in this example). The view's `dataChanged` signal drives the re-render.
163 +## Common mistakes
165 +- **Modifying the underlying array while a `ListView` is showing it** — JavaScript arrays passed as models are not observed. Use `ListModel` for observable lists.
166 +- **Setting delegate size to fixed `width`/`height`** — use `ListView.view.width` so the delegate matches the view.
167 +- **Putting `Repeater` outside a layout** — Repeater creates children of its parent, but if the parent is not a layout, the children's positions won't be managed.
168 +- **Forgetting `clip: true` on a ListView** — content drawn outside the view bounds will leak.
170 +## See also
172 +- `examples/02-repeater/` — `Repeater` over a JS array
173 +- `examples/04-listview/` — `ListView` with a `ListModel`
174 +- `examples/05-form/` — `GridLayout` form with bindings

skills/qml/references/signals.md

Added
new file mode 100644
1 +# Signals
3 +Signals are QML's event mechanism. Objects emit them; other objects listen via handlers.
5 +## Declaring a signal
7 +```qml
8 +Item {
9 + signal activated(string from, int level)
10 + signal clicked() // no args
11 + signal valueChanged(real newValue) // conventional name for property change
13 + MouseArea {
14 + anchors.fill: parent
15 + onClicked: parent.activated("click", 42)
16 + }
18 +```
20 +The signal declaration is part of the type. To emit, just call it like a function: `myObj.activated("hi", 1)`.
22 +## Property change signals
24 +Every property has an auto-generated change signal named `on<Property>Changed`:
26 +```qml
27 +Item {
28 + property int level: 0
29 + onLevelChanged: console.log("level is now", level)
31 +```
33 +You don't declare these — they exist for every property. The signal is emitted after the property's value changes.
35 +## Signal handlers
37 +`on<SignalName>` is the handler naming convention:
39 +```qml
40 +Item {
41 + onClicked: doSomething()
42 + onSomeLongName: doAnotherThing()
44 +```
46 +For signals with arguments, you can name them:
48 +```qml
49 +Item {
50 + signal activated(string from)
52 + onActivated: (from) => console.log("from", from)
54 +```
56 +Or use the auto-bound `signalNameArgs` array:
58 +```qml
59 +Item {
60 + signal activated(string from, int level)
62 + onActivated: console.log(activatedArgs) // ["hi", 42]
64 +```
66 +## Connections to other objects
68 +`Connections` listens to a target's signals:
70 +```qml
71 +Item {
72 + Slider {
73 + id: slider
74 + from: 0; to: 100
75 + }
77 + Connections {
78 + target: slider
79 + function onValueChanged() {
80 + console.log("slider value:", slider.value)
81 + }
82 + }
84 +```
86 +`function on<Signal>` is the modern form (C++-side signal name → handler). The old form `on<Signal>: ...` works too.
88 +`target` can be a binding: `target: someObj?.child` — the connection follows changes.
90 +## Property change tracking
92 +For any object's properties:
94 +```qml
95 +Item {
96 + property int count: 0
98 + onCountChanged: console.log("now", count)
100 + // For a property on another object:
101 + Connections {
102 + target: counter
103 + function onValueChanged() { ... }
106 +```
108 +`Component.onCompleted` and `Component.onDestruction` are attached signals on the object itself — they fire once at creation/destruction.
110 +## Forwarding signals
112 +To re-emit a signal from a parent:
114 +```qml
115 +// MyCard.qml
116 +Rectangle {
117 + property alias source: inner
118 + default property alias body: inner.data
119 + signal activated()
121 + Item {
122 + id: inner
123 + // ...
127 +// Consumer
128 +MyCard {
129 + onActivated: console.log("card activated")
131 +```
133 +Or use a property alias to expose a child and let the consumer connect directly.
135 +## Connections in C++
137 +```cpp
138 +class Counter : public QObject {
139 + Q_OBJECT
140 + Q_PROPERTY(int value READ value NOTIFY valueChanged)
141 +public:
142 + int value() const { return m_value; }
143 + void setValue(int v);
144 +signals:
145 + void valueChanged();
146 +private:
147 + int m_value = 0;
149 +```
151 +The `NOTIFY` in `Q_PROPERTY` declares the change signal. From QML, `counter.onValueChanged: ...` works.
153 +## Common patterns
155 +### Debounce
157 +```qml
158 +TextField {
159 + id: input
160 + onTextChanged: debounceTimer.restart()
162 +Timer {
163 + id: debounceTimer
164 + interval: 300
165 + repeat: false
166 + onTriggered: console.log("done typing:", input.text)
168 +```
170 +The timer restarts on every keystroke; only fires after 300ms of quiet.
172 +### One-shot at creation
174 +```qml
175 +Item {
176 + Component.onCompleted: {
177 + console.log("ready")
178 + doExpensiveSetup()
180 + Component.onDestruction: cleanup()
182 +```
184 +### Throttle
186 +```qml
187 +Timer {
188 + id: throttle
189 + interval: 100
190 + repeat: false
192 +onValueChanged: { throttle.restart(); doWork() }
193 +// doWork() called at most every 100ms, with the latest value
194 +```
196 +## Common mistakes
198 +- **Forgetting `on<Signal>` capitalization** — handlers are `onClicked`, not `onclicked`. Signals are `clicked`, not `Clicked`.
199 +- **Connecting to `target: null`** — the connection silently no-ops. Use `?.` on the target.
200 +- **Listening for property changes that don't actually fire** — re-assigning the same value doesn't emit `onChanged`. Use `Qt.callLater` to defer if you need to compare.
201 +- **Connecting in a tight loop** — `Repeater { delegate: Connections { ... } }` creates a Connections per delegate. OK for small counts, problematic for thousands.
202 +- **Emitting a signal that the consumer hasn't imported** — signals are scoped to the type; you can't `emit` a signal you didn't declare.
204 +## See also
206 +- `examples/01-hello/` — `MouseArea.onClicked`
207 +- `examples/05-form/` — `TextField.onTextChanged` + button `onClicked`
208 +- `references/components.md` — `signal` declaration on custom types

skills/qml/references/syntax.md

Added
new file mode 100644
1 +# QML Syntax
3 +The full QML language reference lives at <https://doc.qt.io/qt-6/qtqml-index.html>. This file is the working shortlist.
5 +## File shape
7 +```qml
8 +import QtQuick
9 +import QtQuick.Controls 6.0
11 +// Single root object. Top-level file is loaded by the engine.
12 +Item {
13 + id: root
14 + property int n: 0
15 + Text { text: "n = " + n }
17 +```
19 +A `.qml` file is exactly one root object + nested children. Comments are `//` (line) and `/* */` (block). Semicolons are optional but recommended in functions.
21 +## Imports
23 +| Form | Use |
24 +| --- | --- |
25 +| `import QtQuick` | A Qt module. Optional major.minor version. |
26 +| `import QtQuick 6.5` | Pin a version for stability. |
27 +| `import QtQuick as Q` | Namespace prefix. Use `Q.Item`. |
28 +| `import "my.js" as MyJs` | JavaScript file as namespace. |
29 +| `import "subfolder"` | Relative-path folder import. |
30 +| `import "subfolder" as Sub` | Same, namespaced. |
32 +**Module and namespace names** must start with an uppercase letter. `import qtquick` is an error.
34 +## Object literal
36 +```qml
37 +Name {
38 + id: foo
39 + property int bar: 5
40 + signal didSomething()
41 + function help(): void { ... }
43 + onSomeSignal: doSomething()
44 + onBarChanged: console.log(bar)
46 + // child object
47 + AnotherName { ... }
49 +```
51 +- Object names start with **uppercase**. Properties/functions/signals start with **lowercase**.
52 +- This distinction lets the parser disambiguate `Foo { ... }` (object literal) from `bar: foo` (property binding to variable `foo`).
54 +## Property types
56 +The QML value types, with QML-side aliases:
58 +| Type | Example | Notes |
59 +| --- | --- | --- |
60 +| `int` | `0`, `-1` | |
61 +| `real` | `0.5`, `1e-3` | QML's float = double. |
62 +| `double` | (rare) | |
63 +| `string` | `"hello"` | |
64 +| `bool` | `true` | |
65 +| `color` | `"red"`, `"#ff0000"`, `Qt.rgba(1, 0, 0, 1)` | |
66 +| `url` | `"https://..."` | Resolved against the QML file's URL. |
67 +| `var` | `[1, "x"]`, `{a: 1}` | Untyped. Use sparingly. |
68 +| `date` | `new Date()` | JS Date. |
69 +| `point` | `Qt.point(0, 0)` | `{x, y}`. |
70 +| `size` | `Qt.size(100, 50)` | `{width, height}`. |
71 +| `rect` | `Qt.rect(0, 0, 100, 50)` | `{x, y, width, height}`. |
72 +| `vector2d`, `vector3d`, `vector4d` | `Qt.vector2d(0, 0)` | |
73 +| `quaternion` | `Qt.quaternion(0, 0, 0, 1)` | |
74 +| `matrix4x4` | `Qt.matrix4x4(...)` | |
75 +| `font` | `font.family: "Inter"` | Structured type. |
76 +| `enumeration` | `Text.AlignLeft` | Object's enums. |
78 +## Property modifiers
80 +| Modifier | Effect |
81 +| --- | --- |
82 +| `readonly` | Can be assigned in the initial binding only. |
83 +| `default` | This is the default property — child objects go into it. |
84 +| `required` | The user must set this property. `qmllint` enforces. |
85 +| `property` (alone) | The default — a normal reactive property. |
87 +```qml
88 +Item {
89 + default property Item body // the consumer can write: MyItem { Rectangle {} }
90 + required property var modelData // forces consumer to pass it
91 + readonly property int version: 1
93 +```
95 +## Property bindings
97 +```qml
98 +// binding (re-evaluates)
99 +height: parent.width / 2
101 +// multi-line binding (JS expression)
102 +color: {
103 + if (level > 100) return "red"
104 + if (level > 50) return "yellow"
105 + return "green"
108 +// assignment (one-shot, breaks binding)
109 +Component.onCompleted: height = 200
111 +// imperative assignment
112 +onClicked: count = count + 1
113 +```
115 +**Important:** assigning to a property *breaks* any active binding. After `height = 200`, the `height: parent.width / 2` binding is gone forever.
117 +## Common patterns
119 +```qml
120 +// ternary in a binding
121 +visible: enabled ? "visible" : "hidden" // NB: visible is a bool; use true/false
123 +// null check
124 +text: name ?? "anonymous"
126 +// optional chain
127 +text: user?.profile?.name ?? "n/a"
129 +// string interpolation
130 +greeting: `Hello, ${name}!`
132 +// array spread
133 +items: [...listA, ...listB]
134 +```
136 +## Object id
138 +```qml
139 +Item {
140 + id: root
141 + Text {
142 + id: label
143 + text: root.someProperty // `root.` is a scope qualifier
146 +```
148 +`id` provides a scope — anywhere inside the same component, you can refer to it by name. For files, the id is invisible to other files (it's a local scope).
150 +## When bindings don't update
152 +A binding re-evaluates when **any property it depends on** changes. Watch for:
154 +1. **Read once in a function:** `Component.onCompleted: x = compute(value)` reads `value` once; the binding doesn't react to later changes.
155 +2. **JavaScript objects:** the binding tracks property accesses via the meta-object system; if you put a plain JS object as a property value, deep changes don't trigger re-eval.
156 +3. **Detached sub-objects:** a binding inside a `Loader { sourceComponent: ... }` source isn't connected to the parent's properties.
158 +## Comments
160 +```qml
161 +// line comment
164 + block comment
167 +// documentation comment (parsed by qmldoc if you add @ annotations)
168 +/// A short summary.
169 +/// @param x the x coordinate
170 +```
172 +Doc comments are `///` or `//!`. `qmldoc` parses them to generate docs.
174 +## Reserved words to avoid as ids
176 +`id`, `property`, `signal`, `function`, `readonly`, `default`, `required`, `signal`, `on`, `import`, `as`, `component`, `pragma`, `Component.onCompleted`, `Component.onDestruction`. These all start with lowercase, so they don't conflict with PascalCase object names.
178 +## Useful singletons
180 +| Singleton | What |
181 +| --- | --- |
182 +| `Qt` | Format functions, point/size/rect, `Qt.callLater(fn)`, `Qt.platform`, `Qt.application`. |
183 +| `Application` | `Application.name`, `Application.version`, `Application.organization`. |
184 +| `Settings` (from `Qt.labs.settings`) | Persist properties to QSettings. |
185 +| `Workspace` (in Qt 6) | Mutex for app-wide locks. |
187 +For more, see the Qt documentation linked in `SKILL.md`.