FrameAnimation QML Type | Qt Quick | Qt 6.11.2
Description: Triggers a handler at every animation frame update.

- Qt 6.11
- Qt Quick
- QML Types
- FrameAnimation
- Qt 6.11.2 Reference Documentation

# FrameAnimation QML Type

Triggers a handler at every animation frame update. More...

Import Statement: | `import QtQuick`
Since: | Qt 6.4

- List of all members, including inherited members

## Properties

- currentFrame : int
- elapsedTime : real
- frameTime : real
- paused : bool
- running : bool
- smoothFrameTime : real

## Signals

- triggered()

## Methods

- void pause()
- void reset()
- void restart()
- void resume()
- void start()
- void stop()

## Detailed Description

A FrameAnimation can be used to trigger an action every time animations have progressed and an animation frame has been rendered. See the documentation about the Scene Graph for in-depth information about the threaded and basic render loops.

For general animations, prefer using `NumberAnimation` and other `Animation` elements as those provide declarative way to describe the animations.

FrameAnimation on the other hand should be used for custom imperative animations and in use-cases like these:

- When you need to run some code on every frame update. Or e.g. every other frame, maybe using progressive rendering.
- When the speed / target is changing during the animation, normal QML animations can be too limiting.
- When more accurate frame update time is needed, e.g. for fps counter.

Compared to `Timer` which allows to set the `interval` time, FrameAnimation runs always in synchronization with the animation updates. If you have used `Timer` with a short interval for custom animations like below, please consider switching to use FrameAnimation instead for smoother animations.

     // BAD
     Timer {
         interval: 16
         repeat: true
         running: true
         onTriggered: {
             // Animate something
         }
     }

     // GOOD
     FrameAnimation {
         running: true
         onTriggered: {
             // Animate something
         }
     }

## Property Documentation

### currentFrame : int `[read-only]`

This property holds the number of frame updates since the start. When the frame animation is restarted, currentFrame starts from `0`.

The following example shows how to react on frame updates.

     FrameAnimation {
         running: true
         onTriggered: {
             // Run code on every frame update.
         }
     }

This property can also be used for rendering only every nth frame. Consider an advanced usage where the UI contains two heavy elements and to reach smooth 60fps overall frame rate, you decide to render these heavy elements at 30fps, first one on every even frames and second one on every odd frames:

     FrameAnimation {
         running: true
         onTriggered: {
             if (currentFrame % 2 == 0)
                 updateUIElement1();
             else
                 updateUIElement2();
        }
     }

By default, `frame` is 0.

### elapsedTime : real `[read-only]`

This property holds the time (in seconds) since the previous start.

By default, `elapsedTime` is 0.

### frameTime : real `[read-only]`

This property holds the time (in seconds) since the previous frame update.

The following example shows how to use frameTime to animate item with varying speed, adjusting to screen refresh rates and possible fps drops.

     Rectangle {
         id: rect
         property real speed: 90
         width: 100
         height: 100
         color: "red"
         anchors.centerIn: parent
     }

     FrameAnimation {
         id: frameAnimation
         running: true
         onTriggered: {
             // Rotate the item speed-degrees / second.
             rect.rotation += rect.speed * frameTime
         }
     }

By default, `frameTime` is 0.

### paused : bool

If set to true, pauses the frame animation; otherwise resumes it.

paused defaults to false.

See also pause() and resume().

### running : bool

If set to true, starts the frame animation; otherwise stops it.

running defaults to false.

See also stop(), start(), and restart().

### smoothFrameTime : real `[read-only]`

This property holds the smoothed time (in seconds) since the previous frame update.

The following example shows how to use smoothFrameTime to show average fps.

     Text {
         text: "fps: " + frameAnimation.fps.toFixed(0)
     }

     FrameAnimation {
         id: frameAnimation
         property real fps: smoothFrameTime > 0 ? (1.0 / smoothFrameTime) : 0
         running: true
     }

By default, `smoothFrameTime` is 0.

## Signal Documentation

### triggered()

This signal is emitted when the FrameAnimation has progressed to a new frame.

Note: The corresponding handler is `onTriggered`.

## Method Documentation

### void pause()

Pauses the frame animation.

If the frame animation is already paused or not `running`, calling this method has no effect. The `paused` property will be true following a call to `pause()`.

### void reset()

Resets the frame animation properties.

Calling this method resets the `frame` and `elapsedTime` to their initial values (0). This method has no effect on `running` or `paused` properties and can be called while they are true or false.

The difference between calling `reset()` and `restart()` is that `reset()` will always initialize the properties while `restart()` initializes them only at the next frame update which doesn't happen e.g. if `restart()` is immediately followed by `pause()`.

### void restart()

Restarts the frame animation.

If the FrameAnimation is not running it will be started, otherwise it will be stopped, reset to initial state and started. The `running` property will be true following a call to `restart()`.

### void resume()

Resumes a paused frame animation.

If the frame animation is not paused or not `running`, calling this method has no effect. The `paused` property will be false following a call to `resume()`.

### void start()

Starts the frame animation.

If the frame animation is already running, calling this method has no effect. The `running` property will be true following a call to `start()`.

### void stop()

Stops the frame animation.

If the frame animation is not running, calling this method has no effect. Both the `running` and `paused` properties will be false following a call to `stop()`.