PhosphorMotionAnimation.h

Go to the documentation of this file.

// SPDX-FileCopyrightText: 2026 fuddlesworth
// SPDX-License-Identifier: LGPL-2.1-or-later
 
#pragma once
 
#include <PhosphorAnimation/PhosphorProfileRegistry.h>
#include <PhosphorAnimation/Profile.h>
#include <PhosphorAnimation/phosphoranimation_export.h>
#include <PhosphorAnimation/PhosphorProfile.h>
 
#include <QtCore/QMetaObject>
#include <QtCore/QPointer>
#include <QtCore/QVariant>
#include <QtQml/qqmlregistration.h>
// Private Qt header — DELIBERATE dependency, not incidental. The
// `QQuickPropertyAnimation` base class lives under `QtQuick/private/*`
// upstream; no public alias exists. This is the same header every
// `Behavior`-wired property-animation subclass in Qt Quick uses
// internally, so its shape is far more stable than a typical private
// header — but Qt does not guarantee source-compat across MINOR Qt
// versions.
//
// Supported Qt range for this library:
//   - Minimum:   Qt 6.10, matching the `find_package(Qt6 6.10 REQUIRED)`
//                in libs/phosphor-animation/CMakeLists.txt. (The
//                `QQuickPropertyAnimation` shape we rely on has been
//                stable since 6.5, but the build does not configure
//                below 6.10.)
//   - Tested:    Qt 6.10, 6.11 (the segment cap at
//                `kBezierSplineSegments` specifically guards 6.11;
//                older versions don't heap-corrupt on the 11+
//                segment boundary, but the cap is harmless there).
//   - Known-bad: Qt 6.11.0-6.11.x pre-patch — `QQuickPropertyAnimation::
//                setEasing` heap-corrupts on `QEasingCurve::BezierSpline`
//                curves with >=11 segments. Workaround in-library; no
//                fix required at the consumer site.
//
// Packaging notes: on Fedora, `qt6-qtdeclarative-devel` pulls the
// private headers via `-devel`. On Debian/Ubuntu the headers live
// under `qt6-declarative-private-dev`. Arch ships them in
// `qt6-declarative`. Distributions that split out private headers
// into a separate package (some openSUSE layouts) need the explicit
// `-private-devel` install.
//
// When bumping the Qt minimum: re-verify the `setEasing` boundary
// and update both `kBezierSplineSegments` and this comment if Qt's
// behaviour changes.
#include <QtQuick/private/qquickanimation_p.h>
 
namespace PhosphorAnimation {
 
class PHOSPHORANIMATION_EXPORT PhosphorMotionAnimation : public QQuickPropertyAnimation
{
    Q_OBJECT
    QML_NAMED_ELEMENT(PhosphorMotionAnimation)
 
    
    Q_PROPERTY(QVariant profile READ profile WRITE setProfile NOTIFY profileChanged)
 
    
    Q_PROPERTY(int durationOverride READ durationOverride WRITE setDurationOverride NOTIFY durationOverrideChanged)
 
public:
    static constexpr int kBezierSplineSegments = 8;
 
    explicit PhosphorMotionAnimation(QObject* parent = nullptr);
    ~PhosphorMotionAnimation() override;
 
    QVariant profile() const;
    void setProfile(const QVariant& p);
 
    int durationOverride() const;
    void setDurationOverride(int ms);
 
    const Profile& resolvedProfile() const;
 
Q_SIGNALS:
    void profileChanged();
    void durationOverrideChanged();
 
private:
    int effectiveDurationMs() const;
 
    void resolveFromVariant(const QVariant& p);
    void rebindToRegistryPath(const QString& path);
    void disconnectRegistrySignal();
    void applyResolvedProfile(const Profile& p);
 
    static bool isAncestorOrSelf(const QString& candidate, const QString& descendant);
 
    void applyResolvedEasing();
 
    QVariant m_profile; 
    Profile m_resolvedProfile; 
    QString m_boundPath; 
    int m_durationOverride = -1; 
    QMetaObject::Connection m_registryChangedConnection;
    QMetaObject::Connection m_registryReloadedConnection;
};
 
} // namespace PhosphorAnimation