PhosphorProfile.h

Go to the documentation of this file.

// SPDX-FileCopyrightText: 2026 fuddlesworth
// SPDX-License-Identifier: LGPL-2.1-or-later
 
#pragma once
 
#include <PhosphorAnimation/CurveRegistry.h>
#include <PhosphorAnimation/PhosphorCurve.h>
#include <PhosphorAnimation/Profile.h>
#include <PhosphorAnimation/phosphoranimation_export.h>
 
#include <QtCore/QJsonObject>
#include <QtCore/QObject>
#include <QtCore/QString>
#include <QtCore/QtMath>
#include <QtQml/qqmlregistration.h>
 
#include <cmath>
 
namespace PhosphorAnimation {
 
class PHOSPHORANIMATION_EXPORT PhosphorProfile
{
    Q_GADGET
    QML_VALUE_TYPE(phosphorProfile)
    QML_STRUCTURED_VALUE
 
    Q_PROPERTY(PhosphorCurve curve READ curve WRITE setCurve)
    Q_PROPERTY(qreal duration READ duration WRITE setDuration)
    Q_PROPERTY(int minDistance READ minDistance WRITE setMinDistance)
    Q_PROPERTY(SequenceMode sequenceMode READ sequenceMode WRITE setSequenceMode)
    Q_PROPERTY(int staggerInterval READ staggerInterval WRITE setStaggerInterval)
    Q_PROPERTY(QString presetName READ presetName WRITE setPresetName)
 
public:
    // Parallel to `PhosphorAnimation::SequenceMode` so QML enum
    // references work without touching the C++ scope. Integer values
    // match for `static_cast` round-trip — matches decision O's "do
    // not rename enum values" convention used by `PhosphorEasing::Type`.
    enum class SequenceMode : int {
        AllAtOnce = int(PhosphorAnimation::SequenceMode::AllAtOnce),
        Cascade = int(PhosphorAnimation::SequenceMode::Cascade),
    };
    Q_ENUM(SequenceMode)
 
    PhosphorProfile() = default;
    explicit PhosphorProfile(const Profile& value)
        : m_value(value)
    {
    }
 
    const Profile& value() const
    {
        return m_value;
    }
 
    // ─── Property delegates ───
    //
    // Setters apply the same validation as `Profile::fromJson`: NaN/inf and
    // out-of-range values are rejected, so `effective*()` substitutes the
    // library default and a QML script that passes garbage gets the same
    // fault-tolerant behaviour as a malformed profile JSON file rather than
    // landing pathological values into a QQuickPropertyAnimation downstream.
    //
    // Two deliberate differences from `fromJson`. A rejection here leaves the
    // field UNSET rather than substituting an engaged default, including for
    // `sequenceMode` — this value type is a plugin-facing handle, not a node in
    // the ProfileTree, so nothing inherits through it and there is no
    // inheritance to block. And a rejection here is silent: the JSON path warns
    // with the offending value because it is parsing a file a user hand-edited,
    // whereas this is a programming error in the calling script and the value
    // is visible in the script itself.
    //
    // `setCurve` is outside all of the above: a `PhosphorCurve` is either a
    // valid curve handle or null, so there is nothing to range-check. Assigning
    // a null one DISENGAGES the field rather than rejecting anything.
 
    PhosphorCurve curve() const
    {
        return PhosphorCurve(m_value.curve);
    }
    void setCurve(const PhosphorCurve& c)
    {
        m_value.curve = c.curve();
    }
 
    qreal duration() const
    {
        return m_value.effectiveDuration();
    }
    void setDuration(qreal ms)
    {
        if (!std::isfinite(ms) || ms <= 0.0 || ms > Profile::MaxDurationMs) {
            m_value.duration.reset();
            return;
        }
        m_value.duration = ms;
    }
 
    int minDistance() const
    {
        return m_value.effectiveMinDistance();
    }
    void setMinDistance(int px)
    {
        if (px < 0 || px > Profile::MaxMinDistancePx) {
            m_value.minDistance.reset();
            return;
        }
        m_value.minDistance = px;
    }
 
    SequenceMode sequenceMode() const
    {
        return static_cast<SequenceMode>(static_cast<int>(m_value.effectiveSequenceMode()));
    }
    void setSequenceMode(SequenceMode mode)
    {
        // Validated like its scalar siblings, and like them a rejection leaves
        // the field unset rather than substituting an engaged default the way
        // `Profile::fromJson` does (see the block comment above for why the two
        // differ). A QML script can assign any int to a Q_ENUM property, and an
        // unknown enumerator stored here would be returned verbatim by
        // `effectiveSequenceMode()` and serialized by `toJson()`, so the wrapper
        // would emit a blob its own `fromJson` rejects on the next read.
        const int raw = static_cast<int>(mode);
        if (raw != static_cast<int>(PhosphorAnimation::SequenceMode::AllAtOnce)
            && raw != static_cast<int>(PhosphorAnimation::SequenceMode::Cascade)) {
            m_value.sequenceMode.reset();
            return;
        }
        m_value.sequenceMode = static_cast<PhosphorAnimation::SequenceMode>(raw);
    }
 
    int staggerInterval() const
    {
        return m_value.effectiveStaggerInterval();
    }
    void setStaggerInterval(int ms)
    {
        if (ms < 0 || ms > Profile::MaxStaggerIntervalMs) {
            m_value.staggerInterval.reset();
            return;
        }
        m_value.staggerInterval = ms;
    }
 
    QString presetName() const
    {
        return m_value.presetName.value_or(QString());
    }
    void setPresetName(const QString& name)
    {
        m_value.presetName = name;
    }
 
    // ─── Serialization ───
 
    Q_INVOKABLE QJsonObject toJson() const
    {
        return m_value.toJson();
    }
 
    Q_INVOKABLE static PhosphorProfile fromJson(const QJsonObject& obj)
    {
        static CurveRegistry sFallback;
        CurveRegistry* registry = PhosphorCurve::defaultRegistry();
        return PhosphorProfile(Profile::fromJson(obj, registry ? *registry : sFallback));
    }
 
    // ─── Equality ───
 
    bool operator==(const PhosphorProfile& other) const
    {
        return m_value == other.m_value;
    }
    bool operator!=(const PhosphorProfile& other) const
    {
        return !(*this == other);
    }
 
private:
    Profile m_value;
};
 
} // namespace PhosphorAnimation
 
Q_DECLARE_METATYPE(PhosphorAnimation::PhosphorProfile)