# Windowing

Read the installed-version type page for each window and attached property before coding.

## PanelWindow

Use `PanelWindow` for a decorationless surface attached to screen edges.
It can be the root object of `shell.qml`.

```qml
import Quickshell

PanelWindow {
    anchors { top: true; left: true; right: true }
    implicitHeight: 30
    margins { top: 4; left: 4; right: 4 }
}
```

Opposite anchors force the corresponding dimension to span the screen between margins.
The exclusion zone only takes effect with the anchor combinations documented by the installed `PanelWindow` type page.

For click-through rendering:

```qml
PanelWindow {
    color: "transparent"
    mask: Region {}
}
```

## FloatingWindow

Use `FloatingWindow` for an ordinary desktop window controlled by the window manager.
Do not use panel anchors or `WlrLayershell` on it.

```qml
import Quickshell

FloatingWindow {
    width: 600
    height: 400
}
```

## PopupWindow

Use `PopupWindow` only when the popup is anchored to another Quickshell window.
Its anchor API is version-sensitive, so read the installed `PopupWindow` and `PopupAnchor` pages rather than copying a recipe from this skill.

## Layer shell

`WlrLayershell` is an attached object on `PanelWindow`.
It is not attached to `FloatingWindow`.

```qml
import Quickshell
import Quickshell.Wayland

PanelWindow {
    WlrLayershell.layer: WlrLayer.Overlay
    WlrLayershell.namespace: "my-osd"
}
```

Layer-shell support depends on the compositor protocol, not on a blanket "Wayland" or "wlroots" label.
Niri is not wlroots-based.
i3 is an X11 window manager; Sway is its Wayland counterpart.
Verify the target compositor's protocol support independently.

## Session lock

`WlSessionLock` and `WlSessionLockSurface` are security-sensitive protocol objects.
Do not derive a lockscreen from an abbreviated recipe.
Use the official example matching the installed Quickshell version and review the complete PAM conversation.

Never launch a lockscreen or authentication flow on the real session during routine validation.
Use a nested compositor and isolated authentication setup with an explicit recovery path.