LottieAnimation QML Type | Qt Lottie Animation 6.1.3

- Qt 6.1
- Qt Lottie Animation
- QML Types
- LottieAnimation QML Type
- Qt Lottie Animation | Commercial or GPLv3

# LottieAnimation QML Type

A Bodymovin player for Qt. More...

Import Statement: | import Qt.labs.lottieqt 1.0
Since: | Qt 5.13
Inherits: | Item

- List of all members, including inherited members

## Properties

- autoPlay : bool
- direction : enumeration
- endFrame : int
- frameRate : int
- loops : int
- quality : enumeration
- source : url
- startFrame : int
- status : enumeration

## Signals

- finished()

## Methods

- double getDuration(bool inFrames)
- bool gotoAndPlay(string frameMarker)
- void gotoAndPlay(int frame)
- bool gotoAndStop(string frameMarker)
- void gotoAndStop(int frame)
- void pause()
- void play()
- void start()
- void stop()
- void togglePause()

## Detailed Description

The LottieAnimation type shows Bodymovin format files.

LottieAnimation is used to load and render Bodymovin files exported from Adobe After Effects. Currently, only subset of the full Bodymovin specification is supported. Most notable deviations are:

- Only Shape layer supported
- Only integer frame-mode of a timeline supported (real frame numbers and time are rounded to the nearest integer)
- Expressions are not supported

For the full list of devations, please refer to the file `unsupported_features.txt` in the source code.

## Example Usage

The following example shows a simple usage of the LottieAnimation type

     LottieAnimation {
         loops: 2
         quality: LottieAnimation.MediumQuality
         source: "animation.json"
         autoPlay: false
         onStatusChanged: {
             if (status === LottieAnimation.Ready) {
                 // any acvities needed before
                 // playing starts go here
                 gotoAndPlay(startFrame);
             }
         }
         onFinished: {
             console.log("Finished playing")
         }
     }

Note: Changing width or height of the element does not change the size of the animation within. Also, it is not possible to align the the content inside of a `LottieAnimation` element. To achieve this, position the animation inside e.g. an `Item`.

## Rendering Performance

Internally, the rendered frame data is cached to improve performance. You can control the memory usage by setting the QLOTTIE_RENDER_CACHE_SIZE environment variable (default value is 2).

You can monitor the rendering performance by turning on two logging categories:

- `qt.lottieqt.bodymovin.render` - Provides information how the animation is rendered
- `qt.lottieqt.bodymovin.render.thread` - Provides information how the rendering process proceeds.

Specifically, you can monitor does the frame cache gets constantly full, or does the rendering process have to wait for frames to become ready. The first case implies that the animation is too complex, and the rendering cannot keep up the pace. Try making the animation simpler, or optimize the QML scene.

## Property Documentation

autoPlay : bool

Defines whether the player will start playing animation automatically after the animation file has been loaded.

The default value is `true`.

direction : enumeration

This property holds the direction of rendering.

Constant | Description
--- | ---
`LottieAnimation.Forward` | Forward direction (Default)
`LottieAnimation.Reverse` | Reverse direction

[read-only] endFrame : int

Frame number of the end of the animation. The value is available after the animation has been loaded and ready to play.

frameRate : int

This property holds the frame rate value of the Bodymovin animation.

`frameRate` changes after the asset has been loaded. Changing the frame rate does not have effect before that, as the value defined in the asset overrides the value. To change the frame rate, you can write:

     LottieAnimation {
         source: "animation.json"
         onStatusChanged: {
             if (status === LottieAnimation.Ready)
                 frameRate = 60;
         }

loops : int

This property holds the number of loops the player will repeat. The value `LottieAnimation.Infinite` means that the the player repeats the animation continuously.

The default value is `1`.

quality : enumeration

Speficies the rendering quality of the bodymovin player. If `LowQuality` is selected the rendering will happen into a frame buffer object, whereas with other options, the rendering will be done onto `QImage` (which in turn will be rendered on the screen).

Constant | Description
--- | ---
`LottieAnimation.LowQuality` | Antialiasing or a smooth pixmap transformation algorithm are not used
`LottieAnimation.MediumQuality` | Smooth pixmap transformation algorithm is used but no antialiasing (Default)
`LottieAnimation.HighQuality` | Antialiasing and a smooth pixmap tranformation algorithm are both used

source : url

The source of the Bodymovin asset that LottieAnimation plays.

LottieAnimation can handle any URL scheme supported by Qt. The URL may be absolute, or relative to the URL of the component.

Setting the source property starts loading the animation asynchronously. To monitor progress of loading, connect to the status change signal.

[read-only] startFrame : int

Frame number of the start of the animation. The value is available after the animation has been loaded and ready to play.

status : enumeration

This property holds the current status of the LottieAnimation element.

Constant | Description
--- | ---
`LottieAnimation.Null` | An initial value that is used when the source is not defined (Default)
`LottieAnimation.Loading` | The player is loading a Bodymovin file
`LottieAnimation.Ready` | Loading has finished successfully and the player is ready to play the animation
`LottieAnimation.Error` | An error occurred while loading the animation

For example, you could implement `onStatusChanged` signal handler to monitor progress of loading an animation as follows:

     LottieAnimation {
         source: "animation.json"
         autoPlay: false
         onStatusChanged: {
             if (status === LottieAnimation.Ready)
                 start();
         }

## Signal Documentation

finished()

This signal is emitted when the player has finished playing. In case of looping, the signal is emitted when the last loop has been finished.

Note: The corresponding handler is `onFinished`.

## Method Documentation

double getDuration(bool inFrames)

Returns the duration of the currently playing asset.

If a given inFrames is `true`, the return value is the duration in number of frames. Otherwise, returns the duration in seconds.

bool gotoAndPlay(string frameMarker)

Plays the asset from the frame that has a marker with the given frameMarker. Returns `true` if the frameMarker was found, `false` otherwise.

void gotoAndPlay(int frame)

Plays the asset from the given frame.

bool gotoAndStop(string frameMarker)

Moves the playhead to the given marker and stops. Returns `true` if frameMarker was found, `false` otherwise.

void gotoAndStop(int frame)

Moves the playhead to the given frame and stops.

void pause()

Pauses the playback.

void play()

Starts or continues playing from the current position.

void start()

Starts playing the animation from the beginning.

void stop()

Stops the playback and returns to startFrame.

void togglePause()

Toggles the status of player between playing and paused states.