Revision control

Copy as Markdown

// Copyright (C) 2026 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GPL-3.0-only
// Qt-Security score:significant reason:default
#include "qlottievectorimagecontroller_p.h"
#include <QtQml/private/qqmlbuiltins_p.h>
#include <QtQuick/qquickitem.h>
#include <QtQuick/private/qquickanimation_p.h>
QT_BEGIN_NAMESPACE
/*!
\qmltype LottieVectorImageController
\inqmlmodule Qt.labs.lottieqt
\inherits QtObject
\since 6.12
\brief Provides animation control for a VectorImage that is displaying a Lottie file.
VectorImage can display and play Lottie animations, but by itself it provides only rudimentary
functionality for controlling the playback. LottieVectorImageController extends VectorImage
with more powerful API for querying and controlling the animation.
A LottieVectorImageController is connected to a VectorImage item by assigning the latter to the
controller's target property. When the VectorImage has loaded a Lottie file, and its \l
{VectorImage::status} {status} is \c Ready, the LottieVectorImageController's properties can be
read and written, and its functions called, to control the playback.
Taken together with VectorImage, LottieVectorImageController mimics the API of the existing
LottieAnimation item, so they are typically interchangeable with little effort. (The \c
getDuration() function is not provided, since it can be trivially replaced by a simple
expression using the endFrame, startFrame and optionally frameRate properties.)
\sa VectorImage, {qtlottieviewer Example}
*/
QLottieVectorImageController::QLottieVectorImageController(QObject *parent)
: QObject(parent)
{
}
/*!
\qmlproperty VectorImage LottieVectorImageController::target
This property must be set to the VectorImage to be controlled.
*/
QQuickVectorImage *QLottieVectorImageController::target() const
{
return m_target;
}
void QLottieVectorImageController::setTarget(QQuickVectorImage *newTarget)
{
if (m_target == newTarget)
return;
const qreal oldStartFrame = startFrame();
const qreal oldEndFrame = endFrame();
const qreal oldFrameRate = frameRate();
if (m_target) {
disconnect(m_target, &QQuickVectorImage::generatedItemChanged, this, &QLottieVectorImageController::frameRateChanged);
disconnect(m_target, &QQuickVectorImage::generatedItemChanged, this, &QLottieVectorImageController::startFrameChanged);
disconnect(m_target, &QQuickVectorImage::generatedItemChanged, this, &QLottieVectorImageController::endFrameChanged);
}
m_target = newTarget;
if (m_target) {
connect(m_target, &QQuickVectorImage::generatedItemChanged, this, &QLottieVectorImageController::frameRateChanged);
connect(m_target, &QQuickVectorImage::generatedItemChanged, this, &QLottieVectorImageController::startFrameChanged);
connect(m_target, &QQuickVectorImage::generatedItemChanged, this, &QLottieVectorImageController::endFrameChanged);
}
m_animFrameRate = frameRate();
emit targetChanged();
if (m_animFrameRate != oldFrameRate)
emit frameRateChanged();
if (startFrame() != oldStartFrame)
emit startFrameChanged();
if (endFrame() != oldEndFrame)
emit endFrameChanged();
}
/*!
\qmlproperty real LottieVectorImageController::frameRate
This property holds the animation playback speed in frames per second.
When the vector image is loaded, this property is set to the frame rqate value specified in the
source file.
After loading, frameRate can be modified to change the playback speed. Assigning an empty
value to it will reset it to the source file value.
*/
qreal QLottieVectorImageController::frameRate() const
{
const QQuickItem *item = m_target ? m_target->generatedItem() : nullptr;
return item ? item->property("frameRate").toReal() : m_animFrameRate;
}
void QLottieVectorImageController::setFrameRate(qreal newFrameRate)
{
QQuickItem *item = m_target ? m_target->generatedItem() : nullptr;
if (item && item->property("frameRate").toReal() != newFrameRate) {
const qreal currentFrame = item->property("frameCounter").toReal();
item->setProperty("frameRate", QVariant(newFrameRate));
auto *anim = item->findChild<QQuickNumberAnimation *>("_qt_frameCounterAnimation", Qt::FindDirectChildrenOnly);
if (anim) {
// Force the NumberAnimation to change speed now, then restore pause state & frame
anim->restart();
anim->setPaused(m_target->animations()->paused());
gotoFrame(currentFrame);
}
emit frameRateChanged();
}
}
void QLottieVectorImageController::resetFrameRate()
{
setFrameRate(m_animFrameRate);
}
/*!
\qmlproperty real LottieVectorImageController::startFrame
\readonly
The animation's starting frame number ("in-frame"), as specified in the source file.
*/
qreal QLottieVectorImageController::startFrame() const
{
const QQuickItem *item = m_target ? m_target->generatedItem() : nullptr;
return item ? item->property("startFrame").toReal() : 0;
}
/*!
\qmlproperty real LottieVectorImageController::endFrame
\readonly
The animation's ending frame number ("out-frame"), as specified in the source file.
*/
qreal QLottieVectorImageController::endFrame() const
{
const QQuickItem *item = m_target ? m_target->generatedItem() : nullptr;
return item ? item->property("endFrame").toReal() : 0;
}
/*!
\qmlmethod void LottieVectorImageController::play()
Starts (un-pauses) the playback.
*/
void QLottieVectorImageController::play()
{
if (m_target)
m_target->animations()->setPaused(false);
}
/*!
\qmlmethod void LottieVectorImageController::pause()
Pauses the playback.
*/
void QLottieVectorImageController::pause()
{
if (m_target)
m_target->animations()->setPaused(true);
}
/*!
\qmlmethod void LottieVectorImageController::togglePause()
Toggles the \l target VectorImage between playing and paused modes.
*/
void QLottieVectorImageController::togglePause()
{
if (m_target) {
const bool isPaused = m_target->animations()->paused();
m_target->animations()->setPaused(!isPaused);
}
}
/*!
\qmlmethod void LottieVectorImageController::play()
Restarts the playback from the startFrame.
*/
void QLottieVectorImageController::start()
{
gotoAndPlay(startFrame());
}
/*!
\qmlmethod void LottieVectorImageController::stop()
Resets the playback to the startFrame and pauses it.
*/
void QLottieVectorImageController::stop()
{
gotoAndStop(startFrame());
}
/*!
\qmlmethod void LottieVectorImageController::gotoAndPlay(real frame)
Moves the playback to Lottie frame number \a frame and plays it.
\a frame will be clamped between startFrame and endFrame.
*/
void QLottieVectorImageController::gotoAndPlay(qreal frame)
{
gotoFrame(frame);
play();
}
/*!
\qmlmethod void LottieVectorImageController::gotoAndStop(real frame)
Moves the playback to Lottie frame number \a frame and pauses it.
\a frame will be clamped between startFrame and endFrame.
*/
void QLottieVectorImageController::gotoAndStop(qreal frame)
{
pause();
gotoFrame(frame);
}
void QLottieVectorImageController::gotoFrame(qreal frame)
{
QQuickItem *item = m_target ? m_target->generatedItem() : nullptr;
if (item) {
auto *anim = item->findChild<QQuickNumberAnimation *>("_qt_frameCounterAnimation", Qt::FindDirectChildrenOnly);
if (anim) {
const qreal from = anim->from();
const qreal to = anim->to();
const qreal progress = qBound(qreal(0), (frame - from) / (to - from), qreal(1));
anim->setCurrentTime(qRound(progress * anim->duration()));
}
}
}
QT_END_NAMESPACE