Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
PhosphorShell::PanelWindow Class Reference

#include <PhosphorShell/PanelWindow.h>

Inheritance diagram for PhosphorShell::PanelWindow:
[legend]

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 &region)
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 &region, QSize surfaceSize)
 The explicit region as a QRegion in surface-local coordinates, clamped to surfaceSize.

Member Enumeration Documentation

◆ Alignment

Enumerator
Fill 
Start 
Center 
End 

◆ Edge

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 

◆ KeyboardFocus

Enumerator
None 

Never receives keyboard focus (default — typical panel).

OnDemand 

Receives focus when the user clicks the surface.

Exclusive 

Holds focus exclusively; for lock screens etc.

◆ Layer

Enumerator
LayerBackground 
LayerBottom 
LayerTop 
LayerOverlay 

Constructor & Destructor Documentation

◆ PanelWindow()

PhosphorShell::PanelWindow::PanelWindow ( QQuickItem * parent = nullptr)
explicit

◆ ~PanelWindow()

PhosphorShell::PanelWindow::~PanelWindow ( )
override

Member Function Documentation

◆ alignment()

Alignment PhosphorShell::PanelWindow::alignment ( ) const
nodiscard

◆ alignmentChanged

void PhosphorShell::PanelWindow::alignmentChanged ( )
signal

◆ cornerCarveRadius()

int PhosphorShell::PanelWindow::cornerCarveRadius ( ) const
nodiscard

◆ cornerCarveRadiusChanged

void PhosphorShell::PanelWindow::cornerCarveRadiusChanged ( )
signal

◆ edge()

Edge PhosphorShell::PanelWindow::edge ( ) const
nodiscard

◆ edgeChanged

void PhosphorShell::PanelWindow::edgeChanged ( )
signal

◆ effectiveInputThickness()

int PhosphorShell::PanelWindow::effectiveInputThickness ( ) const
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.

◆ exclusiveZone()

int PhosphorShell::PanelWindow::exclusiveZone ( ) const
nodiscard

◆ exclusiveZoneChanged

void PhosphorShell::PanelWindow::exclusiveZoneChanged ( )
signal

◆ exclusiveZoneEnabled()

bool PhosphorShell::PanelWindow::exclusiveZoneEnabled ( ) const
nodiscard

◆ exclusiveZoneEnabledChanged

void PhosphorShell::PanelWindow::exclusiveZoneEnabledChanged ( )
signal

◆ explicitInputRegion()

QRegion PhosphorShell::PanelWindow::explicitInputRegion ( const QVariant & region,
QSize surfaceSize )
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.

◆ hasExplicitInputRegion()

bool PhosphorShell::PanelWindow::hasExplicitInputRegion ( ) const
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.

◆ inputRegion()

QVariant PhosphorShell::PanelWindow::inputRegion ( ) const
nodiscard

◆ inputRegionChanged

void PhosphorShell::PanelWindow::inputRegionChanged ( )
signal

◆ interactiveThickness()

int PhosphorShell::PanelWindow::interactiveThickness ( ) const
nodiscard

◆ interactiveThicknessChanged

void PhosphorShell::PanelWindow::interactiveThicknessChanged ( )
signal

◆ keyboardFocus()

KeyboardFocus PhosphorShell::PanelWindow::keyboardFocus ( ) const
nodiscard

◆ keyboardFocusChanged

void PhosphorShell::PanelWindow::keyboardFocusChanged ( )
signal

◆ margins()

QMargins PhosphorShell::PanelWindow::margins ( ) const
nodiscard

◆ marginsChanged

void PhosphorShell::PanelWindow::marginsChanged ( )
signal

◆ panelLayer()

Layer PhosphorShell::PanelWindow::panelLayer ( ) const
nodiscard

◆ panelLayerChanged

void PhosphorShell::PanelWindow::panelLayerChanged ( )
signal

◆ panelLength()

int PhosphorShell::PanelWindow::panelLength ( ) const
nodiscard

◆ panelLengthChanged

void PhosphorShell::PanelWindow::panelLengthChanged ( )
signal

◆ screen()

QScreen * PhosphorShell::PanelWindow::screen ( ) const
nodiscard

◆ screenChanged

void PhosphorShell::PanelWindow::screenChanged ( )
signal

◆ setAlignment()

void PhosphorShell::PanelWindow::setAlignment ( Alignment alignment)

◆ setCornerCarveRadius()

void PhosphorShell::PanelWindow::setCornerCarveRadius ( int radius)

◆ setEdge()

void PhosphorShell::PanelWindow::setEdge ( Edge edge)

◆ setExclusiveZone()

void PhosphorShell::PanelWindow::setExclusiveZone ( int zone)

◆ setExclusiveZoneEnabled()

void PhosphorShell::PanelWindow::setExclusiveZoneEnabled ( bool enabled)

◆ setInputRegion()

void PhosphorShell::PanelWindow::setInputRegion ( const QVariant & region)

◆ setInteractiveThickness()

void PhosphorShell::PanelWindow::setInteractiveThickness ( int thickness)

◆ setKeyboardFocus()

void PhosphorShell::PanelWindow::setKeyboardFocus ( KeyboardFocus focus)

◆ setMargins()

void PhosphorShell::PanelWindow::setMargins ( const QMargins & margins)

◆ setPanelLayer()

void PhosphorShell::PanelWindow::setPanelLayer ( Layer layer)

◆ setPanelLength()

void PhosphorShell::PanelWindow::setPanelLength ( int length)

◆ setScreen()

void PhosphorShell::PanelWindow::setScreen ( QScreen * screen)

◆ setShadowSize()

void PhosphorShell::PanelWindow::setShadowSize ( int size)

◆ setThickness()

void PhosphorShell::PanelWindow::setThickness ( int thickness)

◆ shadowSize()

int PhosphorShell::PanelWindow::shadowSize ( ) const
nodiscard

◆ shadowSizeChanged

void PhosphorShell::PanelWindow::shadowSizeChanged ( )
signal

◆ thickness()

int PhosphorShell::PanelWindow::thickness ( ) const
nodiscard

◆ thicknessChanged

void PhosphorShell::PanelWindow::thicknessChanged ( )
signal

◆ visibleBand()

QRect PhosphorShell::PanelWindow::visibleBand ( Edge edge,
int thickness,
QSize surfaceSize )
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".


The documentation for this class was generated from the following file: