Scene.h

Go to the documentation of this file.

// Copyright 2015 - 2026, GIBIS-UNIFESP and the wiRedPanda contributors
// SPDX-License-Identifier: GPL-3.0-or-later

 
#pragma once
 
#include <optional>
 
#include <QElapsedTimer>
#include <QGraphicsScene>
#include <QHash>
#include <QMap>
#include <QMimeData>
#include <QPoint>
#include <QTimer>
#include <QUndoCommand>
#include <QVersionNumber>
 
#include "App/Core/ContextDirProvider.h"
#include "App/Core/SimulationHost.h"
#include "App/Scene/ClipboardManager.h"
#include "App/Scene/ConnectionManager.h"
#include "App/Scene/ICRegistry.h"
#include "App/Scene/InlineLabelEditor.h"
#include "App/Scene/PropertyShortcutHandler.h"
#include "App/Scene/SceneDropHandler.h"
#include "App/Scene/SceneInteraction.h"
#include "App/Scene/SceneItemRegistry.h"
#include "App/Scene/VisibilityManager.h"
#include "App/Simulation/Simulation.h"
#include "App/Wiring/Port.h"
 
class GraphicElement;
class GraphicsView;
class IC;
class ItemWithId;
class Connection;
class QPainter;
struct SerializationContext;
enum class SerializationPurpose;

class Scene : public QGraphicsScene, public ContextDirProvider, public SimulationHost
{
    Q_OBJECT
 
    // Ctrl-modifier QGraphicsSceneMouseEvents synthesized via QTest don't reliably carry
    // the modifier through this sandbox's event pipeline (see the coverage tracking doc's
    // "recurring exclusion patterns" #22) -- lets tests call the protected mouse handlers
    // directly with a hand-built event instead of chasing unreliable synthetic input.
    friend class TestScene;
 
public:
    void addItem(QGraphicsItem *item);

    void removeItem(QGraphicsItem *item);

    void resizeScene();

    [[nodiscard]] QRectF cachedItemsBoundingRect() const;
 
    // --- Adaptive wire antialiasing ---
    //
    // Antialiased wire strokes cost ~5x the raster time of plain ones, and on a large clocked
    // circuit the simulation recolours wires across the whole viewport continuously -- each
    // repaint pass re-strokes every visible wire, pinning the GUI thread. Quality adapts with
    // the standard split used for binary quality knobs elsewhere (game-engine dynamic
    // resolution scaling degrades on the measured frame-time budget; browsers, GIS canvases
    // and EDA tools restore full quality when the activity causing the load stops):
    //
    //  1. Degrade: wire antialiasing turns off when the measured pass time stays over budget
    //     (debounced, so a one-off compositor stall or load spike never triggers).
    //  2. Restore on idle: antialiasing returns (plus one refinement repaint, free by
    //     definition on an idle view) once BOTH activity streams have gone quiet -- paint
    //     passes for a short window (an interaction gesture ended), and wire status flips
    //     for a longer window (clock-driven flips arrive in bursts at each clock edge, so
    //     the window must span inter-edge gaps -- seconds for slow educational clocks --
    //     or the restore fires inside a gap and quality oscillates with the clock).
    //     Neither stream alone suffices: pass cadence is bursty mid-storm, and flips stop
    //     entirely on combinational circuits whose simulation still runs.
    //  3. Restore on sustained deep headroom: a light workload that never goes idle (small
    //     region in view while the simulation runs) restores once passes stay under
    //     budget / worst-case-AA-ratio, which bounds the restored antialiased pass to within
    //     budget by construction.
    //
    // Restoration deliberately never keys on the degraded renderer merely being "fast enough":
    // with a binary knob that measured speed is a consequence of the decision itself and
    // oscillates quality at the pass rate. Only wires change quality -- elements, ports and
    // text keep the view's render hints.

    [[nodiscard]] bool wireAntialiasingEnabled() const;

    void recordWirePaintPass(qint64 elapsedNs);

    void noteWireActivity();

    void restoreWireAntialiasing();
 
    // --- Per-Scene Element Registry ---

    [[nodiscard]] ItemWithId *itemById(int id) const;

    [[nodiscard]] bool contains(int id) const;

    int lastId() const;

    void setLastId(int newLastId);

    int nextId();

    void updateItemId(ItemWithId *item, int newId);

    void forgetItemId(int id);
 
    // --- Lifecycle ---

    explicit Scene(QObject *parent = nullptr);
 
    // --- View / Display Management ---

    GraphicsView *view() const;
    void setView(GraphicsView *view);

    void showGates(bool checked);

    void showWires(bool checked);

    VisibilityManager *visibilityManager() { return &m_visibilityManager; }
 
    // --- Element Access / Queries ---

    QList<QGraphicsItem *> items(Qt::SortOrder order = Qt::AscendingOrder) const;
    QList<QGraphicsItem *> items(QPointF pos, Qt::ItemSelectionMode mode = Qt::IntersectsItemShape, Qt::SortOrder order = Qt::AscendingOrder, const QTransform &deviceTransform = QTransform()) const;
    QList<QGraphicsItem *> items(const QRectF &rect, Qt::ItemSelectionMode mode = Qt::IntersectsItemShape, Qt::SortOrder order = Qt::AscendingOrder, const QTransform &deviceTransform = QTransform()) const;
    const QList<GraphicElement *> selectedElements() const;
    const QVector<GraphicElement *> elements() const;
    const QVector<GraphicElement *> elements(const QRectF &rect) const;
    static QString droppedPandaFile(const QMimeData *mimeData);
    const QVector<GraphicElement *> unsortedElements() const;
    static QVector<GraphicElement *> sortByTopology(QVector<GraphicElement *> elements);
    static QHash<QString, InputPort *> wirelessTxInputPorts(const QVector<GraphicElement *> &elements);
    const QVector<GraphicElement *> visibleElements() const;

    static bool isConnectionAllowed(OutputPort *startPort, InputPort *endPort);

    void showStatusMessage(const QString &message);
 
    // --- Connection Manager ---

    ConnectionManager *connectionManager() { return &m_connectionManager; }
 
    // --- Clipboard Manager ---

    ClipboardManager *clipboardManager() { return &m_clipboardManager; }
 
    // --- Property Shortcut Handler ---

    PropertyShortcutHandler *propertyShortcutHandler() { return &m_propertyShortcutHandler; }
 
    // --- Hit-testing ---

    QGraphicsItem *itemAt(QPointF pos) const;

    [[nodiscard]] Port *portAt(QPointF pos) const;

    [[nodiscard]] QPointF mousePos() const { return m_interaction.lastMousePos(); }

    void contextMenu(const QPoint screenPos);
 
    // --- Adding Items ---

    void addItem(QMimeData *mimeData, std::optional<QPointF> scenePos = std::nullopt);
 
    // --- Clipboard (Copy / Cut / Paste) ---

    void copyAction();
    void cutAction();
    void pasteAction();
    void duplicateAction();
 
    // --- Element Operations (Rotate / Flip / Delete / Mute) ---

    void deleteAction();
    void rotateRight();
    void rotateLeft();
    void flipHorizontally();
    void flipVertically();
 
    // --- Element Operations (Align / Distribute) ---

    void alignLeft();
    void alignRight();
    void alignTop();
    void alignBottom();
    void alignHorizontalCenter();
    void alignVerticalCenter();
    void distributeHorizontally();
    void distributeVertically();

    void mute(const bool mute = true);
    void selectAll();
 
    // --- Element Property Cycling ---

    void nextElm();
    void prevElm();
    void nextMainPropShortcut();
    void prevMainPropShortcut();
    void nextSecndPropShortcut();
    void prevSecndPropShortcut();
 
    // --- Undo / Redo ---

    QUndoStack *undoStack();
    QAction *redoAction() const;
    QAction *undoAction() const;
    void receiveCommand(QUndoCommand *cmd);
 
    // --- Simulation ---

    Simulation *simulation();
    void setCircuitUpdateRequired();
    void setPropertyUpdateRequired();

    QList<QGraphicsItem *> simulationItems() const override { return items(); }
    void setMuted(const bool muted) override { mute(muted); }
 
    // --- Context Directory ---

    QString contextDir() const override { return m_contextDir; }
    void setContextDir(const QString &dir) { m_contextDir = dir; }
 
    // --- IC Registry ---

    ICRegistry *icRegistry() { return &m_icRegistry; }

    SerializationContext deserializationContext(QHash<quint64, Port *> &portMap, const QVersionNumber &version, SerializationPurpose purpose);
 
    // --- Autosave ---

    void setAutosaveRequired();
 
    // --- Theme ---

    void updateTheme();
 
    // --- Retranslation ---

    void retranslateUi();
 
    // --- Event Filter ---

    bool eventFilter(QObject *watched, QEvent *event) override;
 
signals:
    // --- Signals ---

    void circuitHasChanged();

    void contextMenuPos(QPoint screenPos, QGraphicsItem *itemAtMouse);

    void truthTableElementChanged(GraphicElement *element);

    void icOpenRequested(int elementId, const QString &blobName, const QString &filePath);

    void fileDropRequested(const QString &filePath);

    void showStatusMessageRequested(const QString &message);
 
    // --- IC hover-preview lifecycle (re-emitted from IC; see SceneUiBinder) ---
    void icPreviewRequested(IC *ic, const QPoint &screenPos);
    void icPreviewMoved(IC *ic, const QPoint &screenPos);
    void icPreviewHideRequested();
    void icPreviewCancelRequested(IC *ic);

    void openTruthTableRequested();
 
protected:
    // --- Qt event overrides ---

    void dragEnterEvent(QGraphicsSceneDragDropEvent *event) override;
    void dragMoveEvent(QGraphicsSceneDragDropEvent *event) override;
    void dropEvent(QGraphicsSceneDragDropEvent *event) override;
    void keyPressEvent(QKeyEvent *event) override;
    void keyReleaseEvent(QKeyEvent *event) override;
    void mouseDoubleClickEvent(QGraphicsSceneMouseEvent *event) override;
    void mouseMoveEvent(QGraphicsSceneMouseEvent *event) override;
    void mousePressEvent(QGraphicsSceneMouseEvent *event) override;
    void mouseReleaseEvent(QGraphicsSceneMouseEvent *event) override;
    void helpEvent(QGraphicsSceneHelpEvent *event) override;
 
private:
    // --- Helpers ---

    bool nudgeSelection(QKeyEvent *event);
    QList<QGraphicsItem *> itemsAt(const QPointF pos) const;
    const QVector<Connection *> connections() const;
    void checkUpdateRequest();
    void updateUndoText(const QString &text);
    void updateRedoText(const QString &text);
    void drawBackground(QPainter *painter, const QRectF &rect) override;
    void rotate(const int angle);
    void setDots(const QPen &dots);

    void registerItem(ItemWithId *item);
    void unregisterItem(ItemWithId *item);
 
    // --- Members ---
 
    // View
    GraphicsView *m_view = nullptr;
 
    // Undo/redo
    QUndoStack m_undoStack;
    QAction *m_redoAction;
    QAction *m_undoAction;
 
    // Simulation
    Simulation m_simulation;
 
    // Per-scene element registry (delegated to SceneItemRegistry)
    SceneItemRegistry m_itemRegistry;
 
    // Rendering
    QPen m_dots;
 
    // Mouse-move re-entrancy guard. Stays on Scene (not SceneInteraction) because it
    // must wrap the base QGraphicsScene::mouseMoveEvent call, where the re-entrancy
    // (ensureVisible → replayLastMouseEvent → mouseMoveEvent) actually originates.
    bool m_handlingMouseMove = false;
 
    // Context directory (directory of the .panda file owning this scene)
    QString m_contextDir;
 
    // IC definition registry (caches definitions, manages file watching)
    ICRegistry m_icRegistry = ICRegistry(this);
 
    // Autosave
    bool m_autosaveRequired = false;
 
    // Connection editing (delegated to ConnectionManager)
    ConnectionManager m_connectionManager = ConnectionManager(this);
 
    // Clipboard operations (delegated to ClipboardManager)
    ClipboardManager m_clipboardManager = ClipboardManager(this);
 
    // Property shortcut dispatch (delegated to PropertyShortcutHandler)
    PropertyShortcutHandler m_propertyShortcutHandler = PropertyShortcutHandler(this);
 
    // Visibility control (delegated to VisibilityManager)
    VisibilityManager m_visibilityManager = VisibilityManager(this);
 
    // Set by setPropertyUpdateRequired() whenever a structural edit may have left some
    // item's visibility out of sync with the current show-wires/show-gates toggles;
    // reapplied lazily in drawBackground() (see its comment) rather than eagerly.
    bool m_visibilityDirty = false;
 
    // Backing cache for cachedItemsBoundingRect(); mutable since the accessor is const.
    // Set dirty by setPropertyUpdateRequired(), the same chokepoint every structural/
    // positional edit already funnels through.
    mutable QRectF m_cachedItemsBoundingRect;
    mutable bool m_itemsBoundingRectDirty = true;
 
    // Adaptive wire antialiasing (see the public accessors' comment): consecutive-pass
    // counters for the debounced degrade and the sustained-headroom restore; the idle
    // timer's timeout re-checks m_wireActivityTimer (deadline pattern) and either
    // restores or re-arms for the remaining window, so per-flip timer restarts are
    // never needed.
    bool m_wireAntialiasing = true;
    int m_wireAaSlowPasses = 0;
    int m_wireAaHeadroomPasses = 0;
    QTimer m_wireAaIdleTimer;
    QElapsedTimer m_wireFlipTimer;
    QElapsedTimer m_wirePassTimer;

    void checkWireIdleRestore();
 
    // Drag-and-drop payload decoding (delegated to SceneDropHandler)
    SceneDropHandler m_dropHandler = SceneDropHandler(this);
 
    // On-canvas inline label rename/edit (delegated to InlineLabelEditor)
    InlineLabelEditor m_inlineLabelEditor = InlineLabelEditor(this);
 
    // Mouse-driven editing gestures + rubber-band selection (delegated to SceneInteraction)
    SceneInteraction m_interaction{this};
};