| name | quickshell-game-button |
| description | Use when creating clickable QML buttons with explicit default, hover, pressed, active, and disabled states. |
| source_examples | ["examples/quickshell/components/GameButton.qml"] |
| source_docs | ["https://doc.qt.io/qt-6/qml-qtquick-mousearea.html","https://doc.qt.io/qt-6/qtquick-statesanimations-states.html"] |
Quickshell Game Button
When to use
Use this for gothic menu buttons, action buttons, inventory-slot buttons, AI-icon buttons, or any user-facing clickable control.
Steps
- Use a visible item (
Rectangle, framed Item, or image-backed frame) plus an explicit MouseArea hitbox.
- Set
hoverEnabled: true; otherwise hover state may not update until a mouse button is pressed.
- Expose or encode all five states:
default, hover, pressed, active, disabled.
- Use
State + PropertyChanges when state logic gets larger than one color expression.
- Include an
action-hitbox:<id> marker comment for validator-friendly same-artifact review.
- If the button is decorative, label it decorative in the contract. If it is functional, wire a real signal/action in the same artifact.
Safety baseline
- Keep work in the project sandbox unless explicitly asked to edit source.
- Do not write to
~/.config/quickshell.
- Do not launch a live persistent widget from a skill; generate/static-review first.
- Keep KDE/Wayland examples free of
hyprctl and FloatingWindow.
Verification
MouseArea, hoverEnabled, containsMouse, and pressed appear in the same artifact as the visible control.
- All required states are represented in QML, not just prose.
- Functional controls have a real binding/action or are explicitly decorative.