FrameAnimation QML Type
Triggers a handler at every animation frame update. More...
Import Statement: | import QtQuick |
Since: | Qt 6.4 |
Properties
- currentFrame : int
- elapsedTime : qreal
- frameTime : qreal
- paused : bool
- running : bool
- smoothFrameTime : qreal
Signals
Methods
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
[read-only] currentFrame : int |
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.
[read-only] elapsedTime : qreal |
This property holds the time (in seconds) since the previous start.
By default, elapsedTime
is 0.
[read-only] frameTime : qreal |
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 |
running : bool |
[read-only] smoothFrameTime : qreal |
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
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()
.
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()
.
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()
.
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()
.
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()
.
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()
.
© 2024 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.