Manager.h

Go to the documentation of this file.

// SPDX-FileCopyrightText: 2026 fuddlesworth
// SPDX-License-Identifier: LGPL-2.1-or-later
 
#pragma once
 
#include "PhosphorScreens/PhysicalScreen.h"
#include "VirtualScreen.h"
#include "phosphorscreenscore_export.h"
 
#include <QHash>
#include <QMap>
#include <QObject>
#include <QPointer>
#include <QSet>
#include <QTimer>
#include <QVector>
 
class QScreen;
class QWindow;
 
namespace Phosphor::Screens {
 
class IConfigStore;
class IPanelSource;
class IScreenProvider;
 
struct ScreenManagerConfig
{
    IScreenProvider* screenProvider = nullptr;
    IPanelSource* panelSource = nullptr;
    IConfigStore* configStore = nullptr;
    bool useGeometrySensors = true;
    int maxVirtualScreensPerPhysical = 8;
};
 
class PHOSPHORSCREENSCORE_EXPORT ScreenManager : public QObject
{
    Q_OBJECT
public:
    using Config = ScreenManagerConfig;
 
    explicit ScreenManager(ScreenManagerConfig cfg = ScreenManagerConfig{}, QObject* parent = nullptr);
    ~ScreenManager() override;
 
    void start();
 
    void stop();
 
    // ─── Physical screen queries ─────────────────────────────────────────
    //
    // screens() / primaryScreen() / screenByName() reflect the screen
    // provider's LIVE output set. physicalScreenFor() and the
    // screenGeometry() / screenAvailableGeometry() resolvers below instead
    // read the TRACKED snapshot refreshed on each lifecycle signal — the two
    // agree except transiently, inside a lifecycle slot mid-resync. Prefer
    // the tracked resolvers for geometry work so a query stays consistent
    // with the available-geometry cache.
 
    QVector<PhysicalScreen> screens() const;
    PhysicalScreen primaryScreen() const;
    PhysicalScreen screenByName(const QString& name) const;
 
    int maxVirtualScreensPerPhysical() const
    {
        return m_cfg.maxVirtualScreensPerPhysical;
    }
 
    QRect actualAvailableGeometry(const PhysicalScreen& screen) const;
 
    QRect actualAvailableGeometry(QScreen* screen) const;
 
    bool isPanelGeometryReady() const;
 
    // ─── Virtual screen management ───────────────────────────────────────
 
    bool setVirtualScreenConfig(const QString& physicalScreenId, const VirtualScreenConfig& config);
 
    void refreshVirtualConfigs(const QHash<QString, VirtualScreenConfig>& configs);
 
    VirtualScreenConfig virtualScreenConfig(const QString& physicalScreenId) const;
    bool hasVirtualScreens(const QString& physicalScreenId) const;
 
    // ─── Effective-screen queries ────────────────────────────────────────
 
    QStringList effectiveScreenIds() const;
    QStringList virtualScreenIdsFor(const QString& physicalScreenId) const;
 
    QRect screenGeometry(const QString& screenId) const;
    QRect screenAvailableGeometry(const QString& screenId) const;
 
    PhysicalScreen physicalScreenFor(const QString& screenId) const;
    VirtualScreenDef::PhysicalEdges physicalEdgesFor(const QString& screenId) const;
 
    QString virtualScreenAt(const QPoint& globalPos, const QString& physicalScreenId) const;
    QString effectiveScreenAt(const QPoint& globalPos) const;
 
    // ─── Panel re-query control ──────────────────────────────────────────
 
    void scheduleDelayedPanelRequery(int delayMs);
 
    // ─── Compositor-reported available geometry ──────────────────────────
 
    void setCompositorAvailableGeometry(const QString& screenName, const QRect& available);
 
Q_SIGNALS:
    void screenAdded(const PhysicalScreen& screen);
    void screenRemoved(const PhysicalScreen& screen);
    void screenGeometryChanged(const PhysicalScreen& screen);
    void availableGeometryChanged(const PhysicalScreen& screen, const QRect& availableGeometry);
 
    void panelGeometryReady();
 
    void delayedPanelRequeryCompleted();
 
    void virtualScreensChanged(const QString& physicalScreenId);
 
    void virtualScreenRegionsChanged(const QString& physicalScreenId);
 
    void screenIdentifierChanged(const QString& oldId, const QString& newId);
 
private Q_SLOTS:
    void onProviderScreenAdded(const PhysicalScreen& screen);
    void onProviderScreenRemoved(const PhysicalScreen& screen);
    void onProviderScreenGeometryChanged(const PhysicalScreen& screen);
 
private:
    // Rebuild m_trackedScreens from the provider's current output set.
    // The provider is the single source of truth — every lifecycle slot
    // resyncs through this rather than mutating the vector incrementally.
    void syncTrackedScreens();
 
    // Tracked-screen lookups. Return a copy of the matching tracked screen,
    // or an invalid PhysicalScreen when nothing matches. By value rather
    // than a pointer-into-m_trackedScreens so a caller cannot dangle it
    // across a syncTrackedScreens that re-assigns the vector.
    PhysicalScreen trackedScreenByName(const QString& name) const;
    PhysicalScreen trackedScreenFor(const QString& screenId) const;
 
    // Geometry sensor (layer-shell) lifecycle. Keyed by connector name.
    void createGeometrySensor(const PhysicalScreen& screen);
    void destroyGeometrySensor(const QString& screenName);
    void onSensorGeometryChanged(const QString& screenName);
 
    // Reads sensor + IPanelSource offsets for @p screen, updates
    // m_availableGeometryCache, fires availableGeometryChanged on diff.
    void calculateAvailableGeometry(const PhysicalScreen& screen);
 
    void onPanelOffsetsChanged(QScreen* screen);
    void onPanelRequeryCompleted();
 
    void onConfigStoreChanged();
 
    Config m_cfg;
 
    // The effective screen provider — either the injected one or a
    // QtScreenProvider the manager constructed (parented to `this`) when
    // the config left it null.
    IScreenProvider* m_screenProvider = nullptr;
 
    bool m_running = false;
    bool m_panelGeometryReadyEmitted = false;
 
    QVector<PhysicalScreen> m_trackedScreens;
 
    // Layer-shell sensor windows (one per screen, keyed by connector name)
    // — track live available area size from the compositor.
    QHash<QString, QPointer<QWindow>> m_geometrySensors;
 
    // Per-screen-name available-geometry cache (was file-static in
    // pre-extraction class — instance state now to avoid singleton coupling).
    //
    // NOTE on the `mutable` accessor caches below (this one, the
    // effective-ID cache, and the virtual-geometry cache): they're
    // populated lazily by nominally-const accessors and not protected by
    // any synchronisation. The class contract is GUI-thread-only (see
    // class-level doc and ScreenIdentity.h for the same constraint) —
    // callers on worker threads will race these caches. Don't add locks
    // here without also re-auditing every const accessor to make sure
    // the mutation isn't leaked via returned QString&/QRect& references.
    mutable QHash<QString, QRect> m_availableGeometryCache;
 
    // Authoritative per-screen available geometry pushed by the compositor
    // bridge (the KWin effect's clientArea/MaximizeArea query). Keyed by
    // connector name. When an entry exists for a screen it overrides the
    // sensor/D-Bus heuristic entirely in calculateAvailableGeometry — see
    // setCompositorAvailableGeometry. Cleared per-screen on screen removal
    // (destroyGeometrySensor) and wholesale on stop().
    QHash<QString, QRect> m_compositorAvailableGeometry;
 
    // Virtual screen configurations, keyed by physical screen ID.
    QHash<QString, VirtualScreenConfig> m_virtualConfigs;
 
    mutable QStringList m_cachedEffectiveScreenIds;
    mutable bool m_effectiveScreenIdsDirty = true;
 
    mutable QHash<QString, QRect> m_virtualGeometryCache;
 
    // Warn-once set for screenGeometry() virtual-screen cache misses. A stale
    // "physId/vs:N" id that survives a VS-config change gets queried
    // repeatedly (per cursor move, per snap commit) — warn once per id rather
    // than flooding the journal. Pruned by invalidateVirtualGeometryCache and
    // cleared on a successful resolve so a genuinely-new miss after a
    // reconfigure still surfaces.
    mutable QSet<QString> m_warnedVirtualGeometryMisses;
 
    void invalidateVirtualGeometryCache(const QString& physicalScreenId = {}) const;
    void rebuildVirtualGeometryCache(const QString& physicalScreenId) const;
 
    QString virtualScreenAtWithScreen(const QPoint& globalPos, const QString& physicalScreenId,
                                      const PhysicalScreen& screen) const;
 
    void propagateIdentifierDrift(const QHash<QString, QString>& oldIds);
};
 
} // namespace Phosphor::Screens