#include <PhosphorShell/PanelWindow.h>
Public Types | |
| enum | Edge { Top , Bottom , Left , Right } |
| Additional surface pixels rendered BEYOND the visible panel thickness, intended for the shell to draw a drop-shadow into. More... | |
| enum | Layer { LayerBackground , LayerBottom , LayerTop , LayerOverlay } |
| enum | Alignment { Fill , Start , Center , End } |
| enum | KeyboardFocus { None , OnDemand , Exclusive } |
Signals | |
| void | edgeChanged () |
| void | thicknessChanged () |
| void | shadowSizeChanged () |
| void | interactiveThicknessChanged () |
| void | inputRegionChanged () |
| void | cornerCarveRadiusChanged () |
| void | screenChanged () |
| void | panelLayerChanged () |
| void | exclusiveZoneChanged () |
| void | exclusiveZoneEnabledChanged () |
| void | alignmentChanged () |
| void | panelLengthChanged () |
| void | marginsChanged () |
| void | keyboardFocusChanged () |
Public Member Functions | |
| PanelWindow (QQuickItem *parent=nullptr) | |
| ~PanelWindow () override | |
| Edge | edge () const |
| void | setEdge (Edge edge) |
| int | thickness () const |
| void | setThickness (int thickness) |
| int | shadowSize () const |
| void | setShadowSize (int size) |
| int | interactiveThickness () const |
| void | setInteractiveThickness (int thickness) |
| int | effectiveInputThickness () const |
| The input-region depth to actually apply: interactiveThickness when set, otherwise thickness. | |
| QVariant | inputRegion () const |
| void | setInputRegion (const QVariant ®ion) |
| bool | hasExplicitInputRegion () const |
| Whether inputRegion is set, so the explicit region replaces the band rule. | |
| int | cornerCarveRadius () const |
| void | setCornerCarveRadius (int radius) |
| QScreen * | screen () const |
| void | setScreen (QScreen *screen) |
| Layer | panelLayer () const |
| void | setPanelLayer (Layer layer) |
| int | exclusiveZone () const |
| void | setExclusiveZone (int zone) |
| bool | exclusiveZoneEnabled () const |
| void | setExclusiveZoneEnabled (bool enabled) |
| Alignment | alignment () const |
| void | setAlignment (Alignment alignment) |
| int | panelLength () const |
| void | setPanelLength (int length) |
| QMargins | margins () const |
| void | setMargins (const QMargins &margins) |
| KeyboardFocus | keyboardFocus () const |
| void | setKeyboardFocus (KeyboardFocus focus) |
Static Public Member Functions | |
| static QRect | visibleBand (Edge edge, int thickness, QSize surfaceSize) |
| The painted band of a panel surface of surfaceSize, in surface-local device-independent coordinates: the thickness slice anchored to edge, excluding the shadowSize strip beyond it. | |
| static QRegion | explicitInputRegion (const QVariant ®ion, QSize surfaceSize) |
| The explicit region as a QRegion in surface-local coordinates, clamped to surfaceSize. | |
Additional surface pixels rendered BEYOND the visible panel thickness, intended for the shell to draw a drop-shadow into.
The layer-shell surface size = thickness + shadowSize on the edge-perpendicular axis; the exclusiveZone advertised to the compositor stays at thickness so other windows don't reserve the shadow area. The shader is responsible for actually rendering the shadow in that extra strip — PanelWindow only hands it the surface space. Depth of the surface's INPUT REGION, when it should differ from thickness. 0 (the default) means "follow thickness", which is what every panel wants at rest.
This exists for a surface that paints into its shadow strip and needs clicks there: a bar with a popout growing out of it into the space shadowSize reserved. The pocket is painted, so it must also be clickable, but only while it is open.
Unlike thickness, this IS sampled live: ShellEngine re-applies the input region whenever it changes. That is deliberately the one post-materialization geometry write a panel may make. It is safe precisely because it moves nothing else — the surface size, the anchors and the exclusive zone all stay frozen at their materialization values, so a window tiled below the bar does not shift when a popout opens. Widening thickness instead would move the exclusive zone and shove every tiled window down the screen.
Clamped by visibleBand() to the surface, so a value past thickness + shadowSize simply makes the whole surface interactive rather than producing a region that overhangs it. An EXPLICIT input region, replacing the band rule above. Unset (an invalid QVariant, the default) means the band rule applies. Set to a list of rects (surface-local device-independent coordinates, as QML Qt.rect values) and the surface accepts pointer input in exactly their union, clamped to the surface. An EMPTY list makes the whole surface click-through.
This is what a full-screen overlay wants: an OSD surface that must reach every screen edge but never take a click ([]), or a toast surface whose cards need hover and a close button while everything around them stays click-through (the cards' rects). A band cannot express either, since a band is one edge-anchored slice and its empty case means "the whole surface", not "nothing".
Like interactiveThickness, this is sampled LIVE: ShellEngine re-applies the region whenever it changes, and it moves nothing but the input region. Radius (logical pixels) of the concave quarter-arc carved into each corner of the visible panel where the panel meets the desktop area. 0 disables the carve. Larger values eat further into the panel, so reasonable choices are roughly 1/4 .. 1/3 of thickness. The carve is rendered by the shader as an alpha cutout — the panel's wl_surface remains rectangular and the compositor blends whatever's behind the carved region (wallpaper / other windows) into the cutout pixels, giving the "desktop flows around the panel" look popularised by Quickshell/Noctalia shells. Which corners are carved depends on the panel's edge: Top → bottom-left + bottom-right; the shader is responsible for matching the panel's orientation.
The carve is VISUAL ONLY. visibleBand — and therefore the surface's input region — is the full rectangle, so a carved corner shows the wallpaper or window behind it while still consuming clicks. Sharpening the region to match would mean subtracting an ellipse quadrant per carved corner; it is not done because the region is also what makes the shadow strip click-through, and the two carve quadrants sit inside the exclusive zone where no window is placed. A consumer that carves aggressively enough for that to matter should expect clicks in the carve to hit the panel. The output this panel wants. Null means the primary.
READ ONCE, at materialization. The notify fires on an explicit write, but the member is a guarded pointer and an unplugged output clears it silently, so a binding on this property can go stale. Nothing observes that today because a topology change rebuilds the whole shell, which is the supported way this value ever changes.
| Enumerator | |
|---|---|
| Top | |
| Bottom | |
| Left | |
| Right | |
|
explicit |
|
override |
|
nodiscard |
|
signal |
|
nodiscard |
|
signal |
|
nodiscard |
|
signal |
|
nodiscard |
The input-region depth to actually apply: interactiveThickness when set, otherwise thickness.
One place so the "0 means follow thickness" rule cannot be spelled differently by two callers.
Note WHICH of the two inputs a caller should expect to be live. interactiveThickness is designed to change after materialization (the bar's socket animates it) and ShellEngine re-applies the input region when it does. thickness is not: the surface size, anchors and exclusive zone are all fixed at materialization, so a panel that changes thickness afterwards is already inconsistent with its own surface, and the depth this returns will follow the new value on the next re-apply. Treat a post-materialization thickness write as unsupported rather than as a supported live property.
|
nodiscard |
|
signal |
|
nodiscard |
|
signal |
|
staticnodiscard |
The explicit region as a QRegion in surface-local coordinates, clamped to surfaceSize.
Empty when the region is unset, when the list is empty, or when every rect falls outside the surface. Static and pure, like visibleBand, so the parsing and the clamp can be tested without a live surface.
|
nodiscard |
Whether inputRegion is set, so the explicit region replaces the band rule.
Same shape as effectiveInputThickness: one place for the "unset means band" rule.
|
nodiscard |
|
signal |
|
nodiscard |
|
signal |
|
nodiscard |
|
signal |
|
nodiscard |
|
signal |
|
nodiscard |
|
signal |
|
nodiscard |
|
signal |
|
nodiscard |
|
signal |
| void PhosphorShell::PanelWindow::setAlignment | ( | Alignment | alignment | ) |
| void PhosphorShell::PanelWindow::setCornerCarveRadius | ( | int | radius | ) |
| void PhosphorShell::PanelWindow::setEdge | ( | Edge | edge | ) |
| void PhosphorShell::PanelWindow::setExclusiveZone | ( | int | zone | ) |
| void PhosphorShell::PanelWindow::setExclusiveZoneEnabled | ( | bool | enabled | ) |
| void PhosphorShell::PanelWindow::setInputRegion | ( | const QVariant & | region | ) |
| void PhosphorShell::PanelWindow::setInteractiveThickness | ( | int | thickness | ) |
| void PhosphorShell::PanelWindow::setKeyboardFocus | ( | KeyboardFocus | focus | ) |
| void PhosphorShell::PanelWindow::setMargins | ( | const QMargins & | margins | ) |
| void PhosphorShell::PanelWindow::setPanelLayer | ( | Layer | layer | ) |
| void PhosphorShell::PanelWindow::setPanelLength | ( | int | length | ) |
| void PhosphorShell::PanelWindow::setScreen | ( | QScreen * | screen | ) |
| void PhosphorShell::PanelWindow::setShadowSize | ( | int | size | ) |
| void PhosphorShell::PanelWindow::setThickness | ( | int | thickness | ) |
|
nodiscard |
|
signal |
|
nodiscard |
|
signal |
|
staticnodiscard |
The painted band of a panel surface of surfaceSize, in surface-local device-independent coordinates: the thickness slice anchored to edge, excluding the shadowSize strip beyond it.
This is what the surface's input region should be set to. Without one the shadow strip is transparent but still accepts pointer events, so it swallows clicks along the edge of whatever tiles beneath the panel — and because the advertised exclusiveZone is thickness, windows land exactly where the strip overlaps them.
Static and pure so the arithmetic can be tested without a live Wayland surface: which edge anchors where, and what happens when thickness meets or exceeds the surface depth, is the part that can be wrong. Returns a null QRect for a degenerate surface or a non-positive thickness, which callers treat as "apply nothing".