GraphicElement.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 <memory>
#include <utility>
 
#include <QBitArray>
#include <QGraphicsItem>
#include <QKeySequence>
#include <QList>
 
#include "App/Core/Enums.h"
#include "App/Core/ItemWithId.h"
#include "App/Element/ElementAppearance.h"
#include "App/Element/ElementMetadata.h"
#include "App/Element/ElementOrientation.h"
#include "App/Element/ElementPorts.h"
#include "App/Element/ElementSimState.h"
#include "App/Element/PropertyDescriptor.h"
 
struct SerializationContext;
struct SerializationOptions;
 
class GraphicElement;
class InputPort;
class OutputPort;
class Port;
class QPainter;
class QStyleOptionGraphicsItem;
class QSvgRenderer;
class QWidget;

class GraphicElement : public QGraphicsObject, public ItemWithId
{
    Q_OBJECT
public:
    // --- Type Info ---
 
    enum { Type = QGraphicsItem::UserType + 3 };

    int type() const override { return Type; }
 
    // --- Lifecycle ---

    explicit GraphicElement(ElementType type, QGraphicsItem *parent = nullptr);

    ~GraphicElement() override;
 
signals:
    void inlineEditRequested(GraphicElement *element);
 
public:
    // --- External file dependencies ---

    virtual QStringList externalFiles() const;
 
    // --- Serialization ---

    virtual void save(QDataStream &stream, SerializationOptions options) const;

    virtual void load(QDataStream &stream, SerializationContext &context);
 
    // --- Port Management ---

    virtual void updatePortsProperties();

    virtual WirelessMode wirelessMode() const;

    virtual bool hasWirelessMode() const;
 
    // --- Element Type & Identity ---

    ElementGroup elementGroup() const;

    ElementType elementType() const;
 
    // --- Port Access ---

    InputPort *inputPort(const int index = 0) const;

    OutputPort *outputPort(const int index = 0) const;

    const QVector<InputPort *> &inputs() const;

    const QVector<OutputPort *> &outputs() const;

    QVector<Port *> allPorts() const;

    int inputSize() const;

    int outputSize() const;
 
    // --- Port Size Constraints ---

    int maxInputSize() const;

    int minInputSize() const;

    int maxOutputSize() const;

    int minOutputSize() const;
 
    // --- Labeling ---

    QString label() const;

    void setLabel(const QString &label);

    void updateLabel();

    bool hasLabel() const;

    QRectF labelSceneBoundingRect() const;
 
    // --- Embedded IC ---

    virtual bool isEmbedded() const { return false; }

    virtual const QString &blobName() const { static const QString empty; return empty; }
 
    // --- Trigger Control ---

    QKeySequence trigger() const;

    void setTrigger(const QKeySequence &trigger);

    bool hasTrigger() const;
 
    // --- Audio Properties ---

    virtual QString audio() const;

    virtual void setAudio(const QString &audio);

    bool hasAudio() const;

    bool hasAudioBox() const;

    bool hasVolume() const;

    virtual float volume() const;

    virtual void setVolume(float vol);
 
    // --- Color Properties ---

    virtual QString color() const;

    virtual void setColor(const QString &color);

    bool hasColors() const;

    static int colorNameToIndex(const QString &color);

    QString nextColor() const;

    QString previousColor() const;
 
    // --- Frequency & Delay ---

    virtual double frequency() const;

    virtual double delay() const;

    bool hasFrequency() const;

    bool hasDelay() const;

    virtual void setFrequency(const double freq);

    virtual void setDelay(const double delay);

    QList<PropertyDescriptor> editableProperties() const;
 
    // --- Appearance Management ---

    bool canChangeAppearance() const;

    virtual void setAppearance(const bool defaultAppearance, const QString &fileName);

    void setAppearanceAt(const int index, const QString &fileName);

    virtual QList<std::pair<int, QString>> appearanceStates() const;

    QPixmap appearancePreviewPixmap(const int index, const QSize &size) const;

    void setPixmap(const QString &pixmapPath);

    void setPixmap(const int index);
 
    // --- Truth Table ---

    bool hasTruthTable() const;
 
    // --- Rotation ---

    qreal rotation() const;

    void setRotation(const qreal angle);

    bool rotatesGraphic() const;

    void rotatePorts();

    void reapplyAppearanceOrientation() { m_appearance.applyOrientation(); updateLabelOrientation(); }
 
    // --- Flip / Mirror ---

    bool isFlippedX() const { return m_orientation.isFlippedX(); }

    bool isFlippedY() const { return m_orientation.isFlippedY(); }

    void setFlippedX(bool flipped);

    void setFlippedY(bool flipped);
 
    // --- Geometric Properties ---

    QPointF pixmapCenter() const;

    QRectF boundingRect() const override;
 
    // --- State Queries ---

    bool isValid();
 
    // --- Direct Simulation Interface ---

    virtual void updateLogic();

    virtual void resetSimState();

    virtual void resettleCombinational() { updateLogic(); }

    virtual void saveSimState(QVector<Status> &out) const;

    virtual void restoreSimState(const QVector<Status> &in, int &cursor);

    inline Status outputValue(const int index = 0) const { return m_sim.outputValue(index); }

    qsizetype simOutputSize() const { return m_sim.outputSize(); }

    inline void setOutputValue(const int index, const Status value) { m_sim.setOutputValue(index, value); }

    inline void setOutputValue(const Status value) { m_sim.setOutputValue(0, value); }

    void setOutputValue(const int index, const bool value) { m_sim.setOutputValue(index, value ? Status::Active : Status::Inactive); }

    void setOutputValue(const bool value) { m_sim.setOutputValue(0, value ? Status::Active : Status::Inactive); }

    void connectPredecessor(const int inputIndex, GraphicElement *source, const int outputPort);

    bool outputChanged() const { return m_sim.outputChanged(); }

    void clearOutputChanged() { m_sim.clearOutputChanged(); }

    void beginDeferredCommit() { m_sim.beginDeferredCommit(); }

    void commitDeferredOutputs() { m_sim.commitDeferredOutputs(); }

    void initSimulationVectors(const int inputCount, const int outputCount);

    virtual void loadFromDrop(const QString &fileName, const QString &contextDir);
 
    // --- Virtual Methods ---

    virtual QString genericProperties();

    virtual void refresh();
 
    // --- Qt Graphics & Display ---

    void paint(QPainter *painter, const QStyleOptionGraphicsItem *option, QWidget *widget) override;

    void retranslate();
 
    // --- Setters (Port & Logic Configuration) ---

    virtual void setInputSize(const int size);

    virtual void setOutputSize(const int size);

    void setInputs(const QVector<InputPort *> &inputs);

    void setPortName(const QString &name);

    const QVector<Status> &simInputs() const { return m_sim.inputs(); }

    const QVector<Status> &simOutputs() const { return m_sim.outputs(); }
 
    // --- Theme ---

    virtual void updateTheme();
 
protected:
    // --- Graphics & Rendering ---

    QPixmap pixmap() const;

    QRectF portsBoundingRect() const;

    QRectF renderBodyBounds() const;

    void setLabelAnchor(const QPointF &pos);

    virtual void labelContentChanged() {}
 
    // --- Qt Event Handling ---

    QVariant itemChange(GraphicsItemChange change, const QVariant &value) override;

    void mouseDoubleClickEvent(QGraphicsSceneMouseEvent *event) override;

    bool sceneEvent(QEvent *event) override;
 
    // --- Capability Setters ---

    void setHasColors(const bool hasColors);
 
    // --- Port Size Constraint Setters ---

    void setMaxInputSize(const int maxInputSize);

    void setMinInputSize(const int minInputSize);

    void setMaxOutputSize(const int maxOutputSize);

    void setMinOutputSize(const int minOutputSize);

    ElementPorts m_ports{this};

    ElementAppearance m_appearance{this};
 
    QGraphicsSimpleTextItem *m_label = new QGraphicsSimpleTextItem(this); 
    QPointF m_labelAnchor; 
 
    // --- Members: Metadata ---
 
    QString m_titleText;      
    QString m_translatedName; 
 
    // --- Direct Simulation Helpers ---

    bool simUpdateInputs() { return m_sim.updateInputs(false, m_ports.inputs()); }

    bool simUpdateInputsAllowUnknown() { return m_sim.updateInputs(true, m_ports.inputs()); }

    int decodeSelectValue(int offset, int count) const { return m_sim.decodeSelectValue(offset, count); }
 
private:
    Q_DISABLE_COPY_MOVE(GraphicElement)
 
    
    friend class GraphicElementSerializer;

    friend class ElementAppearance;

    friend class TestGraphicElement;

    void invalidateRenderCache();
 
    // --- Port Management Helpers ---

    void setPortSize(const int size, const bool isInput);
 
    // --- Display & Interaction ---

    void highlight(const bool isSelected);

    void updateLabelOrientation();
 
    // --- Members: Element Type & Identity ---
 
    ElementGroup m_elementGroup = ElementGroup::Unknown;
    ElementType m_elementType = ElementType::Unknown;

    const ElementMetadata &m_metadata;
 
    // --- Members: Direct Simulation ---

    ElementSimState m_sim;
 
    // --- Members: Trigger & Label ---
 
    QKeySequence m_trigger;
    QString m_labelText;
 
    // --- Members: Capabilities & Display State ---
 
    bool m_hasColors = false;
    bool m_selected = false;

    ElementOrientation m_orientation{this};
 
    // --- Members: Port Size Constraints ---
 
    quint64 m_minInputSize = 0;
    quint64 m_maxInputSize = 0;
    quint64 m_minOutputSize = 0;
    quint64 m_maxOutputSize = 0;
};