Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
Manager.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
7#include "VirtualScreen.h"
8#include "phosphorscreensruntime_export.h"
9
10#include <QHash>
11#include <QMap>
12#include <QObject>
13#include <QPointer>
14#include <QSet>
15#include <QSize>
16#include <QTimer>
17#include <QVector>
18
19#include <optional>
20
21class QEvent;
22class QScreen;
23class QWindow;
24
25namespace PhosphorScreens {
26
27class IConfigStore;
28class IPanelSource;
30
61
85class PHOSPHORSCREENSRUNTIME_EXPORT ScreenManager : public QObject
86{
87 Q_OBJECT
88public:
90
91 explicit ScreenManager(ScreenManagerConfig cfg = ScreenManagerConfig{}, QObject* parent = nullptr);
92 ~ScreenManager() override;
93
102 void start();
103
105 void stop();
106
107 // ─── Physical screen queries ─────────────────────────────────────────
108 //
109 // screens() / primaryScreen() / screenByName() reflect the screen
110 // source's LIVE output set. physicalScreenFor() and the
111 // screenGeometry() / screenAvailableGeometry() resolvers below instead
112 // read the TRACKED snapshot refreshed on each lifecycle signal — the two
113 // agree except transiently, inside a lifecycle slot mid-resync. Prefer
114 // the tracked resolvers for geometry work so a query stays consistent
115 // with the available-geometry cache.
116
117 QVector<PhysicalScreen> screens() const;
119 PhysicalScreen screenByName(const QString& name) const;
120
127 {
128 return m_cfg.maxVirtualScreensPerPhysical;
129 }
130
143 QRect actualAvailableGeometry(const PhysicalScreen& screen) const;
144
158 QRect actualAvailableGeometry(QScreen* screen) const;
159
196 qreal logicalScale(const PhysicalScreen& screen) const;
197
207 qreal logicalScale(QScreen* screen) const;
208
218
219 // ─── Virtual screen management ───────────────────────────────────────
220
225 bool setVirtualScreenConfig(const QString& physicalScreenId, const VirtualScreenConfig& config);
226
230 void refreshVirtualConfigs(const QHash<QString, VirtualScreenConfig>& configs);
231
232 VirtualScreenConfig virtualScreenConfig(const QString& physicalScreenId) const;
233 bool hasVirtualScreens(const QString& physicalScreenId) const;
234
235 // ─── Effective-screen queries ────────────────────────────────────────
236
237 QStringList effectiveScreenIds() const;
238 QStringList virtualScreenIdsFor(const QString& physicalScreenId) const;
239
240 QRect screenGeometry(const QString& screenId) const;
241 QRect screenAvailableGeometry(const QString& screenId) const;
242
245 PhysicalScreen physicalScreenFor(const QString& screenId) const;
246 VirtualScreenDef::PhysicalEdges physicalEdgesFor(const QString& screenId) const;
247
248 QString virtualScreenAt(const QPoint& globalPos, const QString& physicalScreenId) const;
249 QString effectiveScreenAt(const QPoint& globalPos) const;
250
251 // ─── Panel re-query control ──────────────────────────────────────────
252
259
260 // ─── Compositor-reported available geometry ──────────────────────────
261
282 void setCompositorAvailableGeometry(const QString& screenName, const QRect& available);
283
284 // ─── Screen size in device pixels ────────────────────────────────────
285
325 void setCompositorPixelSize(const QString& connectorName, const QSize& pixelSize);
326
343 void seedPixelSize(const QString& physicalScreenId, const QSize& pixelSize);
344
359 std::optional<QSize> pixelSize(const QString& screenId) const;
360
363 bool isPixelSizeReported(const QString& screenId) const;
364
383 void acceptCompositorPixelSize(const QString& connectorName);
384
389 std::optional<QSize> pendingPixelSize(const QString& connectorName) const;
390
403 bool hasLogicalScaleSensor(const PhysicalScreen& screen) const;
404
420
421Q_SIGNALS:
422 void screenAdded(const PhysicalScreen& screen);
423 void screenRemoved(const PhysicalScreen& screen);
425 void availableGeometryChanged(const PhysicalScreen& screen, const QRect& availableGeometry);
426
436
442
447
450 void virtualScreensChanged(const QString& physicalScreenId);
451
456 void virtualScreenRegionsChanged(const QString& physicalScreenId);
457
466 void screenIdentifierChanged(const QString& oldId, const QString& newId);
467
474 void compositorPixelSizeChanged(const QString& connectorName);
475
481 void acceptedPixelSizeChanged(const QString& connectorName);
482
490
491protected:
497 bool eventFilter(QObject* watched, QEvent* event) override;
498
499private Q_SLOTS:
500 void onSourceScreenAdded(const PhysicalScreen& screen);
501 void onSourceScreenRemoved(const PhysicalScreen& screen);
502 void onSourceScreenGeometryChanged(const PhysicalScreen& screen);
503
504private:
505 // Rebuild m_trackedScreens from the source's current output set.
506 // The source is authoritative — every lifecycle slot
507 // resyncs through this rather than mutating the vector incrementally.
508 void syncTrackedScreens();
509
510 // Tracked-screen lookups. Return a copy of the matching tracked screen,
511 // or an invalid PhysicalScreen when nothing matches. By value rather
512 // than a pointer-into-m_trackedScreens so a caller cannot dangle it
513 // across a syncTrackedScreens that re-assigns the vector.
514 PhysicalScreen trackedScreenByName(const QString& name) const;
515 PhysicalScreen trackedScreenFor(const QString& screenId) const;
516
517 // Geometry sensor (layer-shell) lifecycle. Keyed by connector name.
518 void createGeometrySensor(const PhysicalScreen& screen);
519 void destroyGeometrySensor(const QString& screenName);
520 void onSensorGeometryChanged(const QString& screenName);
521
522 // Reads sensor + IPanelSource offsets for @p screen, updates
523 // m_availableGeometryCache, fires availableGeometryChanged on diff.
524 void calculateAvailableGeometry(const PhysicalScreen& screen);
525
526 void onPanelOffsetsChanged(QScreen* screen);
527 void onPanelRequeryCompleted();
528
529 void onConfigStoreChanged();
530
531 Config m_cfg;
532
533 // The effective screen source — either the injected one or a
534 // QtPhysicalScreenSource the manager constructed (parented to `this`) when
535 // the config left it null.
536 IPhysicalScreenSource* m_physicalScreenSource = nullptr;
537
538 bool m_running = false;
539 bool m_panelGeometryReadyEmitted = false;
540
541 QVector<PhysicalScreen> m_trackedScreens;
542
543 // Layer-shell sensor windows (one per screen, keyed by connector name)
544 // — track live available area size from the compositor.
545 QHash<QString, QPointer<QWindow>> m_geometrySensors;
546
547 // Per-screen-name available-geometry cache (was file-static in
548 // pre-extraction class — instance state now to avoid singleton coupling).
549 //
550 // NOTE on the `mutable` accessor caches below (this one, the
551 // effective-ID cache, and the virtual-geometry cache): they're
552 // populated lazily by nominally-const accessors and not protected by
553 // any synchronisation. The class contract is GUI-thread-only (see
554 // class-level doc and ScreenIdentity.h for the same constraint) —
555 // callers on worker threads will race these caches. Don't add locks
556 // here without also re-auditing every const accessor to make sure
557 // the mutation isn't leaked via returned QString&/QRect& references.
558 mutable QHash<QString, QRect> m_availableGeometryCache;
559
560 // Authoritative per-screen available geometry pushed by the compositor
561 // bridge (the KWin effect's clientArea/MaximizeArea query). Keyed by
562 // connector name. When an entry exists for a screen it overrides the
563 // sensor/D-Bus heuristic entirely in calculateAvailableGeometry — see
564 // setCompositorAvailableGeometry. Cleared per-screen on screen removal
565 // (destroyGeometrySensor) and wholesale on stop().
566 QHash<QString, QRect> m_compositorAvailableGeometry;
567
568 // Virtual screen configurations, keyed by physical screen ID.
569 QHash<QString, VirtualScreenConfig> m_virtualConfigs;
570
571 mutable QStringList m_cachedEffectiveScreenIds;
572 mutable bool m_effectiveScreenIdsDirty = true;
573
574 mutable QHash<QString, QRect> m_virtualGeometryCache;
575
576 // Warn-once set for screenGeometry() virtual-screen cache misses. A stale
577 // "physId/vs:N" id that survives a VS-config change gets queried
578 // repeatedly (per cursor move, per snap commit) — warn once per id rather
579 // than flooding the journal. Pruned by invalidateVirtualGeometryCache and
580 // cleared on a successful resolve so a genuinely-new miss after a
581 // reconfigure still surfaces.
582 mutable QSet<QString> m_warnedVirtualGeometryMisses;
583
584 void invalidateVirtualGeometryCache(const QString& physicalScreenId = {}) const;
585 void rebuildVirtualGeometryCache(const QString& physicalScreenId) const;
586
587 QString virtualScreenAtWithScreen(const QPoint& globalPos, const QString& physicalScreenId,
588 const PhysicalScreen& screen) const;
589
595 void propagateIdentifierDrift(const QHash<QString, QString>& oldIds);
596
600 std::optional<QSize> resolvePixelSize(const QString& screenId, bool* reported) const;
601
602 // Compositor-reported output sizes in device pixels still PENDING the
603 // host's accept, keyed by connector name. See setCompositorPixelSize for
604 // why the manager's own screen removal does not drop an entry. Cleared
605 // wholesale on stop().
606 QHash<QString, QSize> m_compositorPixelSizes;
607
608 // Host-provided last-session sizes, keyed by physical screen identifier.
609 // Re-keyed on identifier drift like m_virtualConfigs, and kept across
610 // stop()/start() for the same reason: the host's record is the source.
611 QHash<QString, QSize> m_seededPixelSizes;
612
613 // The compositor reports the host accepted (acceptCompositorPixelSize),
614 // keyed by connector name: what pixelSize answers ahead of a seed.
615 // Dropped per connector on the manager's own screen removal
616 // (destroyGeometrySensor) and wholesale on stop().
617 QHash<QString, QSize> m_acceptedPixelSizes;
618
619 // Connector names whose geometry sensor has mapped
620 // (isLogicalScaleSensorMapped). Set by eventFilter on the sensor's first
621 // expose, dropped with the sensor in destroyGeometrySensor.
622 QSet<QString> m_mappedScaleSensors;
623};
624
625} // namespace PhosphorScreens
Pluggable persistence for virtual-screen configurations.
Definition IConfigStore.h:37
Pluggable producer of panel-reservation offsets per screen.
Definition IPanelSource.h:33
Pluggable source of the connected-output set and its lifecycle.
Definition IPhysicalScreenSource.h:43
void scheduleDelayedPanelRequery(int delayMs)
Schedule a one-shot panel re-query after delayMs.
void refreshVirtualConfigs(const QHash< QString, VirtualScreenConfig > &configs)
Diff configs against the current cache and apply the delta.
bool isPixelSizeReported(const QString &screenId) const
True only when pixelSize answers screenId from an accepted compositor report rather than from a seed ...
void virtualScreenRegionsChanged(const QString &physicalScreenId)
VS regions changed but the VS ID set is unchanged (swap, rotate, boundary resize).
ScreenManagerConfig Config
Definition Manager.h:89
void setCompositorAvailableGeometry(const QString &screenName, const QRect &available)
Record the authoritative per-screen available geometry as reported by the compositor.
QRect screenGeometry(const QString &screenId) const
QRect actualAvailableGeometry(const PhysicalScreen &screen) const
Per-screen panel-aware available geometry.
QRect screenAvailableGeometry(const QString &screenId) const
void screenRemoved(const PhysicalScreen &screen)
QStringList effectiveScreenIds() const
bool isLogicalScaleSensorMapped(const PhysicalScreen &screen) const
Whether screen's geometry sensor has mapped, so logicalScale answers the compositor's own scale for i...
bool hasVirtualScreens(const QString &physicalScreenId) const
void screenIdentifierChanged(const QString &oldId, const QString &newId)
Emitted when a connected screen's identifier flips — e.g.
void screenAdded(const PhysicalScreen &screen)
QStringList virtualScreenIdsFor(const QString &physicalScreenId) const
QString effectiveScreenAt(const QPoint &globalPos) const
void stop()
Tear down everything start() set up. Idempotent.
bool isPanelGeometryReady() const
Has the panel source produced its first reading?
bool setVirtualScreenConfig(const QString &physicalScreenId, const VirtualScreenConfig &config)
Apply a single VS subdivision config.
PhysicalScreen primaryScreen() const
void acceptedPixelSizeChanged(const QString &connectorName)
What pixelSize answers for connectorName's screen changed: an accept moved the accepted report (accep...
PhysicalScreen physicalScreenFor(const QString &screenId) const
The physical output a (physical or virtual) screen ID resolves to.
void availableGeometryChanged(const PhysicalScreen &screen, const QRect &availableGeometry)
void panelGeometryReady()
Fired once when isPanelGeometryReady transitions to true.
std::optional< QSize > pendingPixelSize(const QString &connectorName) const
The report pending for connectorName (setCompositorPixelSize), for a host deciding whether to accept ...
void delayedPanelRequeryCompleted()
Fired when a delayed panel re-query (scheduleDelayedPanelRequery) has settled.
QString virtualScreenAt(const QPoint &globalPos, const QString &physicalScreenId) const
qreal logicalScale(QScreen *screen) const
Bridge overload for consumers holding a live QScreen*.
void logicalScaleSensorMapped(const PhysicalScreen &screen)
screen's geometry sensor mapped (isLogicalScaleSensorMapped): from now on logicalScale answers the co...
ScreenManager(ScreenManagerConfig cfg=ScreenManagerConfig{}, QObject *parent=nullptr)
VirtualScreenDef::PhysicalEdges physicalEdgesFor(const QString &screenId) const
VirtualScreenConfig virtualScreenConfig(const QString &physicalScreenId) const
void virtualScreensChanged(const QString &physicalScreenId)
VS topology changed (added, removed, renamed).
int maxVirtualScreensPerPhysical() const
Maximum number of virtual screens per physical monitor this manager will admit.
Definition Manager.h:126
void acceptCompositorPixelSize(const QString &connectorName)
Promote connectorName's pending report to the accepted one.
void setCompositorPixelSize(const QString &connectorName, const QSize &pixelSize)
Record an output's exact size in device pixels as reported by the compositor, PENDING until the host ...
void compositorPixelSizeChanged(const QString &connectorName)
The report pending for connectorName was recorded, changed or cleared (setCompositorPixelSize),...
void seedPixelSize(const QString &physicalScreenId, const QSize &pixelSize)
Seed a monitor's size in device pixels from the host's own record, for use until a compositor report ...
QVector< PhysicalScreen > screens() const
bool hasLogicalScaleSensor(const PhysicalScreen &screen) const
Whether screen has a geometry sensor, so logicalScale answers the compositor's fractional scale,...
PhysicalScreen screenByName(const QString &name) const
bool eventFilter(QObject *watched, QEvent *event) override
Watches the geometry sensors for QEvent::DevicePixelRatioChange, which is the only notice Qt gives th...
std::optional< QSize > pixelSize(const QString &screenId) const
A screen's size in device pixels, the one answer every reader uses.
qreal logicalScale(const PhysicalScreen &screen) const
The compositor's LOGICAL scale for screen (1.15, 1.5, 2.0…).
QRect actualAvailableGeometry(QScreen *screen) const
Bridge overload for consumers that still hold a live QScreen*.
void screenGeometryChanged(const PhysicalScreen &screen)
void start()
Begin tracking screens.
void logicalScaleChanged(const PhysicalScreen &screen)
logicalScale has a different answer for screen than it did.
Definition IWindowTrackingService.h:28
A physical output as ScreenManager sees it — decoupled from QScreen.
Definition PhysicalScreen.h:37
Construction-time wiring for ScreenManager.
Definition Manager.h:54
int maxVirtualScreensPerPhysical
Definition Manager.h:59
IConfigStore * configStore
Definition Manager.h:57
IPanelSource * panelSource
Definition Manager.h:56
bool useGeometrySensors
Definition Manager.h:58
IPhysicalScreenSource * physicalScreenSource
Definition Manager.h:55
Configuration for how a physical screen is subdivided into virtual screens.
Definition VirtualScreen.h:124
Check which edges of this virtual screen are at the physical screen boundary (vs internal edges share...
Definition VirtualScreen.h:103