PanelWindow.h

Go to the documentation of this file.

// SPDX-FileCopyrightText: 2026 fuddlesworth
// SPDX-License-Identifier: LGPL-2.1-or-later
 
#pragma once
 
#include <PhosphorShell/phosphorshell_export.h>
 
#include <QMargins>
#include <QPointer>
#include <QQuickItem>
 
QT_BEGIN_NAMESPACE
class QScreen;
QT_END_NAMESPACE
 
namespace PhosphorShell {
 
class PHOSPHORSHELL_EXPORT PanelWindow : public QQuickItem
{
    Q_OBJECT
 
    Q_PROPERTY(Edge edge READ edge WRITE setEdge NOTIFY edgeChanged)
    Q_PROPERTY(int thickness READ thickness WRITE setThickness NOTIFY thicknessChanged)
    Q_PROPERTY(int shadowSize READ shadowSize WRITE setShadowSize NOTIFY shadowSizeChanged)
    Q_PROPERTY(int cornerCarveRadius READ cornerCarveRadius WRITE setCornerCarveRadius NOTIFY cornerCarveRadiusChanged)
    Q_PROPERTY(QScreen* screen READ screen WRITE setScreen NOTIFY screenChanged)
    // `panelLayer` rather than `layer` — QQuickItem already exposes a
    // FINAL `layer` group property (the cached-rendering layer accessed
    // as `Item.layer.enabled`), and shadowing it triggered a
    // `qt.qml.propertyCache: Final member layer is overridden` warning
    // on every panel construction. Renaming avoids the collision.
    Q_PROPERTY(Layer panelLayer READ panelLayer WRITE setPanelLayer NOTIFY panelLayerChanged)
    Q_PROPERTY(int exclusiveZone READ exclusiveZone WRITE setExclusiveZone NOTIFY exclusiveZoneChanged)
    Q_PROPERTY(bool exclusiveZoneEnabled READ exclusiveZoneEnabled WRITE setExclusiveZoneEnabled NOTIFY
                   exclusiveZoneEnabledChanged)
    Q_PROPERTY(Alignment alignment READ alignment WRITE setAlignment NOTIFY alignmentChanged)
    Q_PROPERTY(int panelLength READ panelLength WRITE setPanelLength NOTIFY panelLengthChanged)
    Q_PROPERTY(QMargins margins READ margins WRITE setMargins NOTIFY marginsChanged)
    // Layer-shell keyboard_interactivity. Default `None` matches what
    // Plasma's panel ships with: panels grab pointer events for their
    // own widgets but never keyboard focus from other windows. Clicking
    // a tray icon shouldn't steal focus from the user's terminal /
    // editor / browser. Set to `OnDemand` when the panel hosts an
    // input field (search launcher etc.) that needs key events; set
    // to `Exclusive` for shell-modal surfaces like a lock screen.
    // Popups attached to the panel get their own xdg_popup grab and
    // can receive keyboard input independently of this setting.
    Q_PROPERTY(KeyboardFocus keyboardFocus READ keyboardFocus WRITE setKeyboardFocus NOTIFY keyboardFocusChanged)
 
public:
    enum Edge {
        Top,
        Bottom,
        Left,
        Right,
    };
    Q_ENUM(Edge)
 
    enum Layer {
        LayerBackground,
        LayerBottom,
        LayerTop,
        LayerOverlay,
    };
    Q_ENUM(Layer)
 
    enum Alignment {
        Fill,
        Start,
        Center,
        End,
    };
    Q_ENUM(Alignment)
 
    // Mirror of PhosphorLayer::KeyboardInteractivity. Kept in this
    // namespace so QML doesn't need to import PhosphorLayer just to
    // name the enumerators. ShellEngine maps these to the layer
    // library's enum at surface-creation time.
    enum KeyboardFocus {
        None, 
        OnDemand, 
        Exclusive 
    };
    Q_ENUM(KeyboardFocus)
 
    explicit PanelWindow(QQuickItem* parent = nullptr);
    ~PanelWindow() override;
 
    [[nodiscard]] Edge edge() const;
    void setEdge(Edge edge);
 
    [[nodiscard]] int thickness() const;
    void setThickness(int thickness);
 
    [[nodiscard]] int shadowSize() const;
    void setShadowSize(int size);
 
    [[nodiscard]] int cornerCarveRadius() const;
    void setCornerCarveRadius(int radius);
 
    [[nodiscard]] QScreen* screen() const;
    void setScreen(QScreen* screen);
 
    [[nodiscard]] Layer panelLayer() const;
    void setPanelLayer(Layer layer);
 
    [[nodiscard]] int exclusiveZone() const;
    void setExclusiveZone(int zone);
 
    [[nodiscard]] bool exclusiveZoneEnabled() const;
    void setExclusiveZoneEnabled(bool enabled);
 
    [[nodiscard]] Alignment alignment() const;
    void setAlignment(Alignment alignment);
 
    [[nodiscard]] int panelLength() const;
    void setPanelLength(int length);
 
    [[nodiscard]] QMargins margins() const;
    void setMargins(const QMargins& margins);
 
    [[nodiscard]] KeyboardFocus keyboardFocus() const;
    void setKeyboardFocus(KeyboardFocus focus);
 
Q_SIGNALS:
    void edgeChanged();
    void thicknessChanged();
    void shadowSizeChanged();
    void cornerCarveRadiusChanged();
    void screenChanged();
    void panelLayerChanged();
    void exclusiveZoneChanged();
    void exclusiveZoneEnabledChanged();
    void alignmentChanged();
    void panelLengthChanged();
    void marginsChanged();
    void keyboardFocusChanged();
 
private:
    Edge m_edge = Top;
    int m_thickness = 32;
    int m_shadowSize = 0;
    int m_cornerCarveRadius = 0;
    // QPointer so monitor hot-unplug doesn't leave us with a dangling
    // QScreen pointer. ScreenManager owns QScreen lifetimes externally.
    QPointer<QScreen> m_screen;
    Layer m_layer = LayerTop;
    // -1 sentinel: "no explicit override, derive from alignment"
    //  0 sentinel: "auto-fit to content via implicitWidth/Height"
    // >0:         "explicit pin in screen-axis pixels"
    int m_exclusiveZone = -1;
    bool m_exclusiveZoneEnabled = true;
    Alignment m_alignment = Fill;
    // -1 sentinel: "fill the screen-aligned axis (Fill alignment)"
    //  0 sentinel: "auto-fit to root item's implicitWidth/Height"
    // >0:         "explicit pin in screen-axis pixels"
    int m_panelLength = -1;
    QMargins m_margins;
    KeyboardFocus m_keyboardFocus = None;
};
 
} // namespace PhosphorShell