Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
PanelWindow.h
Go to the documentation of this file.
1// SPDX-FileCopyrightText: 2026 fuddlesworth
2// SPDX-License-Identifier: LGPL-2.1-or-later
3
4#pragma once
5
6#include <PhosphorShell/phosphorshell_export.h>
7
8#include <QMargins>
9#include <QPointer>
10#include <QQuickItem>
11#include <QRect>
12#include <QRegion>
13#include <QSize>
14#include <QVariant>
15
16QT_BEGIN_NAMESPACE
17class QScreen;
18QT_END_NAMESPACE
19
20namespace PhosphorShell {
21
22class PHOSPHORSHELL_EXPORT PanelWindow : public QQuickItem
23{
24 Q_OBJECT
25
26 Q_PROPERTY(Edge edge READ edge WRITE setEdge NOTIFY edgeChanged)
27 Q_PROPERTY(int thickness READ thickness WRITE setThickness NOTIFY thicknessChanged)
36 Q_PROPERTY(int shadowSize READ shadowSize WRITE setShadowSize NOTIFY shadowSizeChanged)
77 Q_PROPERTY(QVariant inputRegion READ inputRegion WRITE setInputRegion NOTIFY inputRegionChanged)
108 Q_PROPERTY(QScreen* screen READ screen WRITE setScreen NOTIFY screenChanged)
109 // `panelLayer` rather than `layer` — QQuickItem already exposes a
110 // FINAL `layer` group property (the cached-rendering layer accessed
111 // as `Item.layer.enabled`), and shadowing it triggered a
112 // `qt.qml.propertyCache: Final member layer is overridden` warning
113 // on every panel construction. Renaming avoids the collision.
114 Q_PROPERTY(Layer panelLayer READ panelLayer WRITE setPanelLayer NOTIFY panelLayerChanged)
115 Q_PROPERTY(int exclusiveZone READ exclusiveZone WRITE setExclusiveZone NOTIFY exclusiveZoneChanged)
118 Q_PROPERTY(Alignment alignment READ alignment WRITE setAlignment NOTIFY alignmentChanged)
119 Q_PROPERTY(int panelLength READ panelLength WRITE setPanelLength NOTIFY panelLengthChanged)
120 Q_PROPERTY(QMargins margins READ margins WRITE setMargins NOTIFY marginsChanged)
121 // Layer-shell keyboard_interactivity. Default `None` matches what
122 // Plasma's panel ships with: panels grab pointer events for their
123 // own widgets but never keyboard focus from other windows. Clicking
124 // a tray icon shouldn't steal focus from the user's terminal /
125 // editor / browser. Set to `OnDemand` when the panel hosts an
126 // input field (search launcher etc.) that needs key events; set
127 // to `Exclusive` for shell-modal surfaces like a lock screen.
128 // Popups attached to the panel get their own xdg_popup grab and
129 // can receive keyboard input independently of this setting.
131
132public:
139 Q_ENUM(Edge)
140
147 Q_ENUM(Layer)
148
155 Q_ENUM(Alignment)
156
157 // Mirror of PhosphorLayer::KeyboardInteractivity. Kept in this
158 // namespace so QML doesn't need to import PhosphorLayer just to
159 // name the enumerators. ShellEngine maps these to the layer
160 // library's enum at surface-creation time.
166 Q_ENUM(KeyboardFocus)
167
168 explicit PanelWindow(QQuickItem* parent = nullptr);
169 ~PanelWindow() override;
170
186 [[nodiscard]] static QRect visibleBand(Edge edge, int thickness, QSize surfaceSize);
187
188 [[nodiscard]] Edge edge() const;
190
191 [[nodiscard]] int thickness() const;
193
194 [[nodiscard]] int shadowSize() const;
195 void setShadowSize(int size);
196
197 [[nodiscard]] int interactiveThickness() const;
199
213 [[nodiscard]] int effectiveInputThickness() const;
214
215 [[nodiscard]] QVariant inputRegion() const;
216 void setInputRegion(const QVariant& region);
217
221 [[nodiscard]] bool hasExplicitInputRegion() const;
222
228 [[nodiscard]] static QRegion explicitInputRegion(const QVariant& region, QSize surfaceSize);
229
230 [[nodiscard]] int cornerCarveRadius() const;
231 void setCornerCarveRadius(int radius);
232
233 [[nodiscard]] QScreen* screen() const;
234 void setScreen(QScreen* screen);
235
236 [[nodiscard]] Layer panelLayer() const;
237 void setPanelLayer(Layer layer);
238
239 [[nodiscard]] int exclusiveZone() const;
240 void setExclusiveZone(int zone);
241
242 [[nodiscard]] bool exclusiveZoneEnabled() const;
243 void setExclusiveZoneEnabled(bool enabled);
244
245 [[nodiscard]] Alignment alignment() const;
247
248 [[nodiscard]] int panelLength() const;
249 void setPanelLength(int length);
250
251 [[nodiscard]] QMargins margins() const;
252 void setMargins(const QMargins& margins);
253
254 [[nodiscard]] KeyboardFocus keyboardFocus() const;
256
257Q_SIGNALS:
272
273private:
274 Edge m_edge = Top;
275 int m_thickness = 32;
276 int m_shadowSize = 0;
277 // 0 = follow m_thickness. See the property docs above.
278 int m_interactiveThickness = 0;
279 // Invalid = unset (the band rule applies). See the property docs.
280 QVariant m_inputRegion;
281 int m_cornerCarveRadius = 0;
282 // QPointer so monitor hot-unplug doesn't leave us with a dangling
283 // QScreen pointer. ScreenManager owns QScreen lifetimes externally.
284 QPointer<QScreen> m_screen;
285 Layer m_layer = LayerTop;
286 // -1 sentinel: "no explicit override, derive from alignment"
287 // 0 sentinel: "auto-fit to content via implicitWidth/Height"
288 // >0: "explicit pin in screen-axis pixels"
289 int m_exclusiveZone = -1;
290 bool m_exclusiveZoneEnabled = true;
291 Alignment m_alignment = Fill;
292 // -1 sentinel: "fill the screen-aligned axis (Fill alignment)"
293 // 0 sentinel: "auto-fit to root item's implicitWidth/Height"
294 // >0: "explicit pin in screen-axis pixels"
295 int m_panelLength = -1;
296 QMargins m_margins;
297 KeyboardFocus m_keyboardFocus = None;
298};
299
300} // namespace PhosphorShell
Alignment
Definition PanelWindow.h:149
@ Fill
Definition PanelWindow.h:150
@ Center
Definition PanelWindow.h:152
@ Start
Definition PanelWindow.h:151
@ End
Definition PanelWindow.h:153
void setShadowSize(int size)
bool exclusiveZoneEnabled() const
bool hasExplicitInputRegion() const
Whether inputRegion is set, so the explicit region replaces the band rule.
QVariant inputRegion() const
Edge
Additional surface pixels rendered BEYOND the visible panel thickness, intended for the shell to draw...
Definition PanelWindow.h:133
@ Left
Definition PanelWindow.h:136
@ Right
Definition PanelWindow.h:137
@ Top
Definition PanelWindow.h:134
@ Bottom
Definition PanelWindow.h:135
PanelWindow(QQuickItem *parent=nullptr)
void setInteractiveThickness(int thickness)
void setExclusiveZone(int zone)
QMargins margins() const
static QRegion explicitInputRegion(const QVariant &region, QSize surfaceSize)
The explicit region as a QRegion in surface-local coordinates, clamped to surfaceSize.
void setInputRegion(const QVariant &region)
int effectiveInputThickness() const
The input-region depth to actually apply: interactiveThickness when set, otherwise thickness.
void setScreen(QScreen *screen)
KeyboardFocus
Definition PanelWindow.h:161
@ Exclusive
Holds focus exclusively; for lock screens etc.
Definition PanelWindow.h:164
@ None
Never receives keyboard focus (default — typical panel).
Definition PanelWindow.h:162
@ OnDemand
Receives focus when the user clicks the surface.
Definition PanelWindow.h:163
void setExclusiveZoneEnabled(bool enabled)
void setAlignment(Alignment alignment)
void setKeyboardFocus(KeyboardFocus focus)
static QRect visibleBand(Edge edge, int thickness, QSize surfaceSize)
The painted band of a panel surface of surfaceSize, in surface-local device-independent coordinates: ...
int interactiveThickness() const
Alignment alignment() const
KeyboardFocus keyboardFocus() const
Layer
Definition PanelWindow.h:141
@ LayerOverlay
Definition PanelWindow.h:145
@ LayerTop
Definition PanelWindow.h:144
@ LayerBottom
Definition PanelWindow.h:143
@ LayerBackground
Definition PanelWindow.h:142
void setThickness(int thickness)
void setCornerCarveRadius(int radius)
QScreen * screen() const
void setPanelLength(int length)
void setPanelLayer(Layer layer)
void setMargins(const QMargins &margins)
Definition Environment.h:11