quickshell-popup-menu

name	quickshell-popup-menu
description	Use when creating anchored popup menus, flyouts, tooltip-like panels, or transient menu surfaces in Quickshell.
source_examples	["examples/quickshell/standalone/popup-menu-panel.qml"]
source_docs	["https://quickshell.org/docs/v0.3.0/types/Quickshell/PopupWindow/","https://doc.qt.io/qt-6/qml-qtquick-mousearea.html"]

Quickshell Popup Menu

When to use

Use this for anchored menus, flyouts, tooltips, quick settings, inventory menus, or context panels attached to a shell widget.

Steps

1. Create the owner as a PanelWindow and put PopupWindow inside that owner scope.
2. Set anchor.window: <panel id>.
3. Position with anchor.rect.x and anchor.rect.y; avoid deprecated relativeX, relativeY, and parentWindow.
4. Bind visible to explicit menu state, but remember the popup is shown only when both visible and the anchor are valid.
5. Use grabFocus: true if outside click should close/dismiss the popup.
6. Give each row/control a MouseArea with hover feedback and validator markers.

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

• PopupWindow has anchor.window and anchor.rect coordinates.
• Toggle button and popup rows have explicit hitboxes.
• No popup writes to live Quickshell config.