Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
Layout.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
9#include "phosphorzones_export.h"
10#include <QObject>
11#include <QVariantMap>
12#include <QVector>
13#include <QUuid>
14#include <QString>
15#include <QJsonArray>
16#include <QJsonObject>
17#include <functional>
18#include <memory>
19
20namespace PhosphorZones {
21
33
41class PHOSPHORZONES_EXPORT Layout : public QObject
42{
43 Q_OBJECT
44
45 Q_PROPERTY(QUuid id READ id CONSTANT)
46 Q_PROPERTY(QString name READ name WRITE setName NOTIFY nameChanged)
47 Q_PROPERTY(QString description READ description WRITE setDescription NOTIFY descriptionChanged)
48 Q_PROPERTY(int zonePadding READ zonePadding WRITE setZonePadding NOTIFY zonePaddingChanged)
49 Q_PROPERTY(int outerGap READ outerGap WRITE setOuterGap NOTIFY outerGapChanged)
53 Q_PROPERTY(int outerGapTop READ outerGapTop WRITE setOuterGapTop NOTIFY outerGapChanged)
54 Q_PROPERTY(int outerGapBottom READ outerGapBottom WRITE setOuterGapBottom NOTIFY outerGapChanged)
55 Q_PROPERTY(int outerGapLeft READ outerGapLeft WRITE setOuterGapLeft NOTIFY outerGapChanged)
56 Q_PROPERTY(int outerGapRight READ outerGapRight WRITE setOuterGapRight NOTIFY outerGapChanged)
59 Q_PROPERTY(
62 Q_PROPERTY(int zoneCount READ zoneCount NOTIFY zonesChanged)
63 Q_PROPERTY(QString sourcePath READ sourcePath WRITE setSourcePath NOTIFY sourcePathChanged)
64 Q_PROPERTY(bool isSystemLayout READ isSystemLayout NOTIFY sourcePathChanged)
65
66 // Auto-assign: new windows fill first empty zone
67 Q_PROPERTY(bool autoAssign READ autoAssign WRITE setAutoAssign NOTIFY autoAssignChanged)
68
69 // Geometry mode: use full screen or available (panel-excluded) geometry
72
73 // Aspect ratio classification
74 Q_PROPERTY(
78
79 // Visibility filtering
80 Q_PROPERTY(
82 Q_PROPERTY(QStringList allowedScreens READ allowedScreens WRITE setAllowedScreens NOTIFY allowedScreensChanged)
83 Q_PROPERTY(QList<int> allowedDesktops READ allowedDesktops WRITE setAllowedDesktops NOTIFY allowedDesktopsChanged)
84 Q_PROPERTY(
86
87 // Unit of fixed-geometry zones: device pixels (true) or logical ones (false).
88 // Last in the list so every older property keeps its metaobject index.
91
92public:
93 explicit Layout(QObject* parent = nullptr);
94 explicit Layout(const QString& name, QObject* parent = nullptr);
95 ~Layout() override;
96
97 // A Layout is a QObject, so it is never copied or assigned. Duplication
98 // goes through clone(), which returns a heap object with an explicit owner
99 // the way every other Layout in the codebase is created.
100 Layout(const Layout&) = delete;
101 Layout& operator=(const Layout&) = delete;
102
118 Layout* clone(QObject* parent = nullptr) const;
119
120 // Identification
121 QUuid id() const
122 {
123 return m_id;
124 }
125 QString name() const
126 {
127 return m_name;
128 }
129 void setName(const QString& name);
130
131 QString description() const
132 {
133 return m_description;
134 }
135 void setDescription(const QString& description);
136
137 // Layout settings (per-layout gap overrides, -1 = use global setting)
138 int zonePadding() const
139 {
140 return m_zonePadding;
141 }
142 void setZonePadding(int padding);
144 {
145 return m_zonePadding >= 0;
146 }
148
149 int outerGap() const
150 {
151 return m_outerGap;
152 }
153 void setOuterGap(int gap);
155 {
156 return m_outerGap >= 0;
157 }
159
160 // Per-side outer gap overrides (-1 = use global setting)
162 {
163 return m_usePerSideOuterGap;
164 }
165 void setUsePerSideOuterGap(bool enabled);
166 int outerGapTop() const
167 {
168 return m_outerGapTop;
169 }
170 void setOuterGapTop(int gap);
171 int outerGapBottom() const
172 {
173 return m_outerGapBottom;
174 }
175 void setOuterGapBottom(int gap);
176 int outerGapLeft() const
177 {
178 return m_outerGapLeft;
179 }
180 void setOuterGapLeft(int gap);
181 int outerGapRight() const
182 {
183 return m_outerGapRight;
184 }
185 void setOuterGapRight(int gap);
187 {
188 return m_usePerSideOuterGap
189 && (m_outerGapTop >= 0 || m_outerGapBottom >= 0 || m_outerGapLeft >= 0 || m_outerGapRight >= 0);
190 }
191
197 {
198 return {m_outerGapTop, m_outerGapBottom, m_outerGapLeft, m_outerGapRight};
199 }
200
201 bool showZoneNumbers() const
202 {
203 return m_showZoneNumbers;
204 }
205 void setShowZoneNumbers(bool show);
206
208 {
209 return m_overlayDisplayMode;
210 }
211 void setOverlayDisplayMode(int mode);
213 {
214 return m_overlayDisplayMode >= 0;
215 }
217
218 // Source path tracking - determines if layout is from system or user directory
219 QString sourcePath() const
220 {
221 return m_sourcePath;
222 }
223 void setSourcePath(const QString& path);
224
225 // Returns true if layout was loaded from a system directory (not user's .local)
226 // This determines whether the layout can be edited/deleted in place
227 bool isSystemLayout() const;
228
229 // Original system layout path — set when a user override replaces a system layout.
230 // Persisted in user JSON so deletion can restore the system original without scanning.
231 QString systemSourcePath() const
232 {
233 return m_systemSourcePath;
234 }
235 void setSystemSourcePath(const QString& path)
236 {
237 m_systemSourcePath = path;
238 }
239 bool hasSystemOrigin() const
240 {
241 return !m_systemSourcePath.isEmpty();
242 }
243
244 // Aspect ratio classification
246 {
247 return m_aspectRatioClass;
248 }
251 {
252 return static_cast<int>(m_aspectRatioClass);
253 }
255 qreal minAspectRatio() const
256 {
257 return m_minAspectRatio;
258 }
259 void setMinAspectRatio(qreal ratio);
260 qreal maxAspectRatio() const
261 {
262 return m_maxAspectRatio;
263 }
264 void setMaxAspectRatio(qreal ratio);
265
271 bool matchesAspectRatio(qreal screenAspectRatio) const;
272
273 // Visibility filtering
275 {
276 return m_hiddenFromSelector;
277 }
278 void setHiddenFromSelector(bool hidden);
279 QStringList allowedScreens() const
280 {
281 return m_allowedScreens;
282 }
283 void setAllowedScreens(const QStringList& screens);
284 QList<int> allowedDesktops() const
285 {
286 return m_allowedDesktops;
287 }
288 void setAllowedDesktops(const QList<int>& desktops);
289 QStringList allowedActivities() const
290 {
291 return m_allowedActivities;
292 }
293 void setAllowedActivities(const QStringList& activities);
294
295 // Auto-assign: new windows fill first empty zone
296 bool autoAssign() const
297 {
298 return m_autoAssign;
299 }
300 void setAutoAssign(bool enabled);
301
302 // Geometry mode: when true, zones span the full screen including panel/taskbar areas
304 {
305 return m_useFullScreenGeometry;
306 }
307 void setUseFullScreenGeometry(bool enabled);
308
316 {
317 return m_fixedGeometryInDevicePixels;
318 }
320
331 qreal fixedGeometryDivisor(qreal screenScale) const
332 {
333 return (m_fixedGeometryInDevicePixels && screenScale > 0.0) ? screenScale : 1.0;
334 }
335
338
343 QRectF fixedZoneBoundingBox() const;
344
355
362 static constexpr int DefaultOrderUnset = 999;
363
364 // Optional load order for "default" layout when defaultLayoutId is not set (lower = first)
365 int defaultOrder() const
366 {
367 return m_defaultOrder;
368 }
369 void setDefaultOrder(int order)
370 {
371 m_defaultOrder = order;
372 }
373
374 // Zone management
375 int zoneCount() const
376 {
377 return m_zones.size();
378 }
379 QVector<Zone*> zones() const
380 {
381 return m_zones;
382 }
383 Zone* zone(int index) const;
384 Zone* zoneById(const QUuid& id) const;
385 Zone* zoneByNumber(int number) const;
390 Zone* zoneByName(const QString& name) const;
391
392 Q_INVOKABLE void addZone(Zone* zone);
393 Q_INVOKABLE void removeZone(Zone* zone);
394 Q_INVOKABLE void removeZoneAt(int index);
395 Q_INVOKABLE void clearZones();
396 Q_INVOKABLE void moveZone(int fromIndex, int toIndex);
397
398 // Zone detection
399 Q_INVOKABLE Zone* zoneAtPoint(const QPointF& point) const;
400 Q_INVOKABLE Zone* nearestZone(const QPointF& point, qreal maxDistance = -1) const;
401 Q_INVOKABLE QVector<Zone*> zonesInRect(const QRectF& rect) const;
402 Q_INVOKABLE QVector<Zone*> adjacentZones(const QPointF& point, qreal threshold = 20) const;
403
404 // Geometry calculations
405 Q_INVOKABLE void renumberZones();
406 QRectF lastRecalcGeometry() const
407 {
408 return m_lastRecalcGeometry;
409 }
410
411 void setLastRecalcGeometry(const QRectF& geom, qreal screenScale = 0.0)
412 {
413 m_lastRecalcGeometry = geom;
414 if (screenScale > 0.0) {
415 m_lastRecalcScale = screenScale;
416 }
417 }
418
433 bool needsRecalc(const QRectF& screenGeometry, qreal screenScale = 0.0) const
434 {
435 return screenGeometry != m_lastRecalcGeometry || m_zoneGeometryDirty
436 || (screenScale > 0.0 && fixedGeometryDivisor(screenScale) != fixedGeometryDivisor(m_lastRecalcScale)
438 }
439
446 qreal lastRecalcScale() const
447 {
448 return m_lastRecalcScale;
449 }
450
456 quint64 zoneGeometryEpoch() const
457 {
458 return m_zoneGeometryEpoch;
459 }
460
464 quint64 syncRecalcEpoch() const
465 {
466 return m_syncRecalcEpoch;
467 }
468
474 void markRecalculated(const QRectF& geom, qreal screenScale = 0.0)
475 {
476 m_lastRecalcGeometry = geom;
477 m_zoneGeometryDirty = false;
478 if (screenScale > 0.0) {
479 m_lastRecalcScale = screenScale;
480 }
481 }
482
483 // Serialization
484 QJsonObject toJson() const;
485 static Layout* fromJson(const QJsonObject& json, QObject* parent = nullptr);
486
499 using ScreenIdResolver = std::function<QString(const QString&)>;
507
508 // Predefined layouts (templates)
509 static Layout* createColumnsLayout(int columns, QObject* parent = nullptr);
510 static Layout* createRowsLayout(int rows, QObject* parent = nullptr);
511 static Layout* createGridLayout(int columns, int rows, QObject* parent = nullptr);
512 static Layout* createPriorityGridLayout(QObject* parent = nullptr);
513 static Layout* createFocusLayout(QObject* parent = nullptr);
514
515 // Dirty tracking for copy-on-write saving
516 bool isDirty() const
517 {
518 return m_dirty;
519 }
521 {
522 m_dirty = true;
523 }
525 {
526 m_dirty = false;
527 }
530
531Q_SIGNALS:
551
552public:
566 void recalculateZoneGeometries(const QRectF& screenGeometry, qreal screenScale = 0.0);
567
568private:
569 void emitModifiedIfNotBatched();
573 void markZoneGeometryDirty()
574 {
575 m_zoneGeometryDirty = true;
576 ++m_zoneGeometryEpoch;
577 }
578
585 void initFromJson(const QJsonObject& json);
586
587 QUuid m_id;
588 QString m_name;
589 QString m_description;
590 int m_zonePadding = -1; // -1 = use global setting
591 int m_outerGap = -1; // -1 = use global setting
592 bool m_usePerSideOuterGap = false;
593 int m_outerGapTop = -1; // -1 = use global setting
594 int m_outerGapBottom = -1;
595 int m_outerGapLeft = -1;
596 int m_outerGapRight = -1;
597 bool m_showZoneNumbers = true;
598 int m_overlayDisplayMode = -1; // -1 = use global setting
599 QString m_sourcePath; // Path where layout was loaded from (empty for new layouts)
600 QString m_systemSourcePath; // Original system path if this is a user override of a system layout
601 int m_defaultOrder = DefaultOrderUnset; // Optional: lower values appear first when choosing default
602 QVector<Zone*> m_zones;
603
604 // Auto-assign: new windows fill first empty zone
605 bool m_autoAssign = false;
606
607 // Geometry mode: zones use full screen (true) or available area excluding panels (false)
608 bool m_useFullScreenGeometry = false;
609
610 // Aspect ratio classification
612 qreal m_minAspectRatio = 0.0; // 0 = not set (use class matching)
613 qreal m_maxAspectRatio = 0.0; // 0 = not set (use class matching)
614
615 // Visibility filtering
616 bool m_hiddenFromSelector = false;
617 QStringList m_allowedScreens; // empty = all screens
618 QList<int> m_allowedDesktops; // empty = all desktops
619 QStringList m_allowedActivities; // empty = all activities
620
621 // Screen rect the zone geometries were last recalculated against. Empty
622 // means "no screen known yet". Doubles as the reference frame the derived
623 // relativeGeometry is defined over — see fixedZoneReferenceGeometry.
624 QRectF m_lastRecalcGeometry;
625
626 // Set when the zone geometry inputs change under an unchanged screen: the
627 // zone SET (add / remove / clear) or the fixed-geometry unit. Either edit
628 // leaves the recalculated absolute geometries stale, but it does not move
629 // the layout to another screen, so the rect above stays valid as a
630 // reference and only the recompute is owed. Keeping these two facts apart
631 // is what lets a serialization that follows a zone swap still normalize
632 // against the screen instead of silently falling back to the fixed-zone
633 // bounding box. Written through markZoneGeometryDirty, which also bumps
634 // m_zoneGeometryEpoch.
635 bool m_zoneGeometryDirty = false;
636
637 // Cached classification derived from m_sourcePath. Recomputed in
638 // setSourcePath so isSystemLayout() is O(1) — QStandardPaths lookups add
639 // up on hot paths like QML preview rebuilds.
640 bool m_isSystemLayout = false;
641
642 // Dirty tracking for copy-on-write saving
643 bool m_dirty = false;
644 int m_batchModifyDepth = 0;
645
646 // Fixed-geometry unit: device pixels (true) or logical pixels (false).
647 bool m_fixedGeometryInDevicePixels = false;
648
649 // The newest output scale a recalculation was asked for, the other half of
650 // the reference frame a device-pixel layout's fixed geometry resolves in.
651 qreal m_lastRecalcScale = 1.0;
652
653 // See zoneGeometryEpoch() and syncRecalcEpoch().
654 quint64 m_zoneGeometryEpoch = 0;
655 quint64 m_syncRecalcEpoch = 0;
656
657 // Whether anything inside the current outermost batch marked the layout
658 // modified, so endBatchModify emits layoutModified for an edit made in
659 // that batch and not for a dirty bit left by an earlier, unsaved one.
660 bool m_batchModified = false;
661};
662
663} // namespace PhosphorZones
bool hasOuterGapOverride() const
Definition Layout.h:154
bool needsRecalc(const QRectF &screenGeometry, qreal screenScale=0.0) const
The complete staleness predicate recalculateZoneGeometries() gates on: the screen rect changed OR the...
Definition Layout.h:433
int overlayDisplayMode() const
Definition Layout.h:207
qreal lastRecalcScale() const
The newest output scale a recalculation was asked for (1.0 until a scale is known).
Definition Layout.h:446
Zone * nearestZone(const QPointF &point, qreal maxDistance=-1) const
int zonePadding() const
Definition Layout.h:138
void markRecalculated(const QRectF &geom, qreal screenScale=0.0)
Full-recalc bookkeeping for external appliers (the async worker path): stamps the rect AND clears the...
Definition Layout.h:474
QList< int > allowedDesktops() const
Definition Layout.h:284
int outerGapLeft() const
Definition Layout.h:176
::PhosphorLayout::EdgeGaps rawOuterGaps() const
Raw per-side gap overrides.
Definition Layout.h:196
void addZone(Zone *zone)
bool usePerSideOuterGap() const
Definition Layout.h:161
bool isSystemLayout() const
bool isDirty() const
Definition Layout.h:516
void moveZone(int fromIndex, int toIndex)
Zone * zoneById(const QUuid &id) const
void setSourcePath(const QString &path)
void setAllowedActivities(const QStringList &activities)
qreal fixedGeometryDivisor(qreal screenScale) const
What a fixed geometry is divided by on an output whose logical scale is screenScale: that scale when ...
Definition Layout.h:331
QString systemSourcePath() const
Definition Layout.h:231
int defaultOrder() const
Definition Layout.h:365
void zoneRemoved(Zone *zone)
static Layout * createPriorityGridLayout(QObject *parent=nullptr)
int outerGapTop() const
Definition Layout.h:166
void setDefaultOrder(int order)
Definition Layout.h:369
bool hasFixedGeometryZones() const
Returns true if any zone uses fixed (pixel) geometry mode.
void setAspectRatioClass(::PhosphorLayout::AspectRatioClass cls)
void setOuterGapTop(int gap)
void setUseFullScreenGeometry(bool enabled)
void setHiddenFromSelector(bool hidden)
qreal maxAspectRatio() const
Definition Layout.h:260
QRectF fixedZoneBoundingBox() const
Bounding box of all fixed-geometry zones, anchored at (0, 0), in the LOGICAL units of the last recalc...
void markDirty()
Definition Layout.h:520
void overlayDisplayModeChanged()
QRectF fixedZoneReferenceGeometry() const
Reference geometry suitable for normalizing fixed-pixel zones to 0–1 relative coordinates.
void setOuterGap(int gap)
bool matchesAspectRatio(qreal screenAspectRatio) const
Check if this layout is suitable for a screen with the given aspect ratio.
void setUsePerSideOuterGap(bool enabled)
bool hasZonePaddingOverride() const
Definition Layout.h:143
Layout(const QString &name, QObject *parent=nullptr)
void setZonePadding(int padding)
QString sourcePath() const
Definition Layout.h:219
void setAutoAssign(bool enabled)
void setLastRecalcGeometry(const QRectF &geom, qreal screenScale=0.0)
Stamps the rect, and a positive screenScale as the scale with it.
Definition Layout.h:411
Layout(const Layout &)=delete
QVector< Zone * > adjacentZones(const QPointF &point, qreal threshold=20) const
bool hasSystemOrigin() const
Definition Layout.h:239
static void setScreenIdResolver(ScreenIdResolver resolver)
int zoneCount() const
Definition Layout.h:375
QJsonObject toJson() const
Zone * zoneByNumber(int number) const
void hiddenFromSelectorChanged()
bool hasPerSideOuterGapOverride() const
Definition Layout.h:186
bool hasOverlayDisplayModeOverride() const
Definition Layout.h:212
void fixedGeometryInDevicePixelsChanged()
Zone * zone(int index) const
std::function< QString(const QString &)> ScreenIdResolver
Screen-id resolver.
Definition Layout.h:499
QStringList allowedActivities() const
Definition Layout.h:289
void setOverlayDisplayMode(int mode)
int outerGapRight() const
Definition Layout.h:181
quint64 syncRecalcEpoch() const
Bumped by every recalculateZoneGeometries() call, including one that finds nothing to recompute,...
Definition Layout.h:464
int outerGap() const
Definition Layout.h:149
static Layout * createGridLayout(int columns, int rows, QObject *parent=nullptr)
QVector< Zone * > zonesInRect(const QRectF &rect) const
static Layout * createFocusLayout(QObject *parent=nullptr)
Layout(QObject *parent=nullptr)
bool useFullScreenGeometry() const
Definition Layout.h:303
void setDescription(const QString &description)
void setFixedGeometryInDevicePixels(bool enabled)
bool hiddenFromSelector() const
Definition Layout.h:274
::PhosphorLayout::AspectRatioClass aspectRatioClass() const
Definition Layout.h:245
void setMinAspectRatio(qreal ratio)
Layout & operator=(const Layout &)=delete
QRectF lastRecalcGeometry() const
Definition Layout.h:406
void setSystemSourcePath(const QString &path)
Definition Layout.h:235
Zone * zoneAtPoint(const QPointF &point) const
QStringList allowedScreens() const
Definition Layout.h:279
bool showZoneNumbers() const
Definition Layout.h:201
void setAspectRatioClassInt(int cls)
void removeZone(Zone *zone)
void setAllowedScreens(const QStringList &screens)
Zone * zoneByName(const QString &name) const
First zone (in zone-number order) whose name equals name after trimming, compared case-insensitively.
static constexpr int DefaultOrderUnset
Sentinel for "no explicit default order set" on defaultOrder.
Definition Layout.h:362
bool fixedGeometryInDevicePixels() const
Whether this layout's fixed-geometry zones count DEVICE pixels.
Definition Layout.h:315
static ScreenIdResolver screenIdResolver()
Returns a copy of the currently-installed resolver (empty if none).
void recalculateZoneGeometries(const QRectF &screenGeometry, qreal screenScale=0.0)
Recalculate every zone's absolute geometry against screenGeometry.
void setName(const QString &name)
void setOuterGapRight(int gap)
void clearOverlayDisplayModeOverride()
void setOuterGapBottom(int gap)
void setOuterGapLeft(int gap)
quint64 zoneGeometryEpoch() const
Bumped when the zone set changes (a zone added, removed or replaced) or the fixed-geometry unit flips...
Definition Layout.h:456
void removeZoneAt(int index)
QString name() const
Definition Layout.h:125
QUuid id() const
Definition Layout.h:121
Layout * clone(QObject *parent=nullptr) const
Deep-copy this layout into a new, independently owned Layout.
void setMaxAspectRatio(qreal ratio)
QString description() const
Definition Layout.h:131
qreal minAspectRatio() const
Definition Layout.h:255
void useFullScreenGeometryChanged()
void setAllowedDesktops(const QList< int > &desktops)
static Layout * fromJson(const QJsonObject &json, QObject *parent=nullptr)
static Layout * createRowsLayout(int rows, QObject *parent=nullptr)
QVector< Zone * > zones() const
Definition Layout.h:379
int outerGapBottom() const
Definition Layout.h:171
bool autoAssign() const
Definition Layout.h:296
void zoneAdded(Zone *zone)
void setShowZoneNumbers(bool show)
int aspectRatioClassInt() const
Definition Layout.h:250
static Layout * createColumnsLayout(int columns, QObject *parent=nullptr)
void clearDirty()
Definition Layout.h:524
A scrolling screen's first-class sizing template.
Definition ScrollingTemplate.h:128
Represents a single zone within a layout.
Definition Zone.h:47
AspectRatioClass
Screen aspect-ratio classification.
Definition AspectRatioClass.h:22
@ Any
Suitable for all aspect ratios (default).
Definition AspectRatioClass.h:23
Definition IWindowTrackingService.h:24
LayoutCategory
Category for layout type.
Definition Layout.h:28
@ Autotile
Dynamic auto-tiling algorithm.
Definition Layout.h:30
@ Manual
Traditional zone-based layout.
Definition Layout.h:29
Per-side edge gap values (resolved, non-negative pixel values).
Definition EdgeGaps.h:27