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 <QtQml/qqmlproperty.h>
#include <QtQuick/qquickitem.h>
#include <QtQuick/private/qquickanimation_p.h>
#include <algorithm>
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.
LottieVectorImageController's \l target property specifies the VectorImage to be controlled. It
is set by default if the LottieVectorImageController is created as a child or property of a
VectorImage. 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), QQmlParserStatus()
{
}
/*!
\internal
*/
void QLottieVectorImageController::classBegin()
{
}
/*!
\internal
*/
void QLottieVectorImageController::componentComplete()
{
if (!m_target) {
if (auto *p = qobject_cast<QQuickVectorImage *>(parent()))
setTarget(p);
}
}
/*!
\qmlproperty VectorImage LottieVectorImageController::target
This property specifies the VectorImage to be controlled.
If the LottieVectorImageController is created as a child or property of a VectorImage, that
will be the default target. Otherwise, the target must be set explicitly.
*/
QQuickVectorImage *QLottieVectorImageController::target() const
{
return m_target;
}
void QLottieVectorImageController::setTarget(QQuickVectorImage *newTarget)
{
if (m_target == newTarget)
return;
if (m_target)
disconnect(m_target, &QQuickVectorImage::generatedItemChanged, this, &QLottieVectorImageController::onGeneratedItemChanged);
m_target = newTarget;
if (m_target)
connect(m_target, &QQuickVectorImage::generatedItemChanged, this, &QLottieVectorImageController::onGeneratedItemChanged);
onGeneratedItemChanged();
emit targetChanged();
}
void QLottieVectorImageController::onGeneratedItemChanged()
{
clearMarkerPlayback();
if (m_generatedItem)
QObject::disconnect(m_generatedItem, nullptr, this, nullptr);
const qreal oldStartFrame = startFrame();
const qreal oldEndFrame = endFrame();
const qreal oldFrameRate = frameRate();
const qreal oldCurrentFrame = currentFrame();
const QStringList oldMarkers = markers();
m_generatedItem = m_target ? m_target->generatedItem() : nullptr;
m_animFrameRate = frameRate();
m_markers.clear();
if (m_generatedItem) {
const QQmlProperty prop(m_generatedItem, QStringLiteral("frameCounter"));
if (prop.isValid())
prop.connectNotifySignal(this, SIGNAL(currentFrameChanged()));
const QVariantMap markersMap = m_generatedItem->property("markers").toMap();
for (auto it = markersMap.cbegin(); it != markersMap.cend(); ++it) {
const QVariantList data = it.value().toList();
m_markers.append({ it.key(), data.value(0).toInt(), data.value(1).toInt() });
}
std::sort(m_markers.begin(), m_markers.end(),
[](const QLottieRoot::Marker &a, const QLottieRoot::Marker &b) {
return a.frame < b.frame;
});
}
if (startFrame() != oldStartFrame)
emit startFrameChanged();
if (endFrame() != oldEndFrame)
emit endFrameChanged();
if (m_animFrameRate != oldFrameRate)
emit frameRateChanged();
if (currentFrame() != oldCurrentFrame)
emit currentFrameChanged();
if (markers() != oldMarkers)
emit markersChanged();
}
/*!
\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 rate 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
{
return m_generatedItem ? m_generatedItem->property("frameRate").toReal() : 30;
}
void QLottieVectorImageController::setFrameRate(qreal newFrameRate)
{
QQuickItem *item = m_generatedItem;
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 && m_target) {
// 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
{
return m_generatedItem ? m_generatedItem->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
{
return m_generatedItem ? m_generatedItem->property("endFrame").toReal() : 0;
}
/*!
\qmlproperty real LottieVectorImageController::currentFrame
\readonly
The number of the currently displayed animation frame.
*/
qreal QLottieVectorImageController::currentFrame() const
{
return m_generatedItem ? m_generatedItem->property("frameCounter").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::start()
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)
{
clearMarkerPlayback();
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)
{
clearMarkerPlayback();
pause();
gotoFrame(frame);
}
/*!
\qmlproperty list<string> LottieVectorImageController::markers
\readonly
\since 6.13
Names of the markers defined in the Lottie animation file. The list
is available after the target VectorImage has loaded and is ready.
Markers can be used with \l gotoAndPlay() and \l gotoAndStop() to
jump to a named position in the animation. If a marker has a non-zero
duration, \l gotoAndPlay() will stop playback automatically at the end
of the marked segment.
*/
QStringList QLottieVectorImageController::markers() const
{
QStringList names;
names.reserve(m_markers.size());
for (const QLottieRoot::Marker &marker : m_markers)
names.append(marker.name);
return names;
}
/*!
\qmlmethod bool LottieVectorImageController::gotoAndPlay(string markerName)
\since 6.13
Moves the playback to the frame that has a marker with the given \a markerName and plays it.
If the marker has a non-zero duration, playback stops automatically at the end of the segment.
Returns \c true if the marker was found, \c false otherwise.
*/
bool QLottieVectorImageController::gotoAndPlay(const QString &markerName)
{
const auto it = std::find_if(
m_markers.cbegin(), m_markers.cend(),
[&markerName](const QLottieRoot::Marker &m) { return m.name == markerName; });
if (it == m_markers.cend())
return false;
clearMarkerPlayback();
if (it->duration > 0) {
m_markerEndFrame = it->frame + it->duration;
m_markerEndConnection =
connect(this, &QLottieVectorImageController::currentFrameChanged, this, [this]() {
if (currentFrame() >= m_markerEndFrame) {
clearMarkerPlayback();
pause();
emit finished();
}
});
}
gotoFrame(it->frame);
play();
return true;
}
/*!
\qmlmethod bool LottieVectorImageController::gotoAndStop(string markerName)
\since 6.13
Moves the playback to the frame that has a marker with the given \a markerName and pauses it.
Returns \c true if the marker was found, \c false otherwise.
*/
bool QLottieVectorImageController::gotoAndStop(const QString &markerName)
{
const auto it = std::find_if(
m_markers.cbegin(), m_markers.cend(),
[&markerName](const QLottieRoot::Marker &m) { return m.name == markerName; });
if (it == m_markers.cend())
return false;
gotoAndStop(it->frame);
return true;
}
void QLottieVectorImageController::clearMarkerPlayback()
{
m_markerEndFrame = -1;
QObject::disconnect(m_markerEndConnection);
}
void QLottieVectorImageController::gotoFrame(qreal frame)
{
if (m_generatedItem) {
auto *anim = m_generatedItem->findChild<QQuickNumberAnimation *>("_qt_frameCounterAnimation",
Qt::FindDirectChildrenOnly);
if (anim) {
const qreal from = anim->from();
const qreal to = anim->to();
const qreal rawProgress = (frame - from) / (to - from);
if (qIsFinite(rawProgress)) {
const qreal progress = qBound(qreal(0), rawProgress, qreal(1));
anim->setCurrentTime(qRound(progress * anim->duration()));
}
}
}
}
QT_END_NAMESPACE