RiveQtQuickItem Class Reference

#include <riveqtquickitem.h>

Inherits QQuickItem.

Public Types
enum	LoadingStatus

Properties
QString	fileSource
LoadingStatus	loadingStatus
QVector< ArtBoardInfo >	artboards
QVector< AnimationInfo >	animations
QVector< StateMachineInfo >	stateMachines
int	currentArtboardIndex
int	currentAnimationIndex
int	currentStateMachineIndex
bool	interactive
RiveStateMachineInput *	stateMachineInterface
RiveRenderSettings::RenderQuality	renderQuality
RiveRenderSettings::PostprocessingMode	postprocessingMode
RiveRenderSettings::FillMode	fillMode
int	frameRate

Detailed Description

A quick item for Rive-based animations.

This class represents a QQuickItem that provides functionalities to work with Rive animations.

Author

Jeremias Bosch, Jonas Kalinka, basysKom GmbH

Date

2023/08/01

Property Documentation

animations

RiveQtQuickItem::animations

read

Contains a list of available animations.

This property holds a list of animations present in the loaded Rive file. Each animation entry, as defined by the AnimationInfo struct, provides meta information like the animation's name, duration, frame rate, and ID.

Structure Details:

The AnimationInfo struct contains the following properties:

• id: A unique identifier for the animation.
• name: The name of the animation.
• duration: The total duration of the animation in seconds.
• fps: The frame rate at which the animation should be played, expressed in frames per second.

Example:

RiveQtQuickItem {
    Component.onCompleted: {
        console.log(animations[0].name); // Outputs the name of the first animation
    }
}

artboards

RiveQtQuickItem::artboards

read

Contains a list of available artboards.

This property holds a list of artboards present in the loaded Rive file. Each artboard contains meta information, as defined by the ArtBoardInfo class, providing details about the artboard's specifications and properties.

Structure Details:

The ArtBoardInfo class contains the following properties:

• id: A unique identifier for the artboard.
• name: The name of the artboard.

Example:

RiveQtQuickItem {
    Component.onCompleted: {
        console.log(artboards[0].name); // Outputs the name of the first artboard
    }
}

currentAnimationIndex

RiveQtQuickItem::currentAnimationIndex

readwrite

Represents the currently active animation index.

Change this property's value to alter the animation being played back. The index corresponds to the position of the animation in the animations list. Modifying the index will start the specified animation.

Structure Details:

The AnimationInfo struct contains the following properties:

• id: A unique integer that identifies the animation.
• name: The name of the animation.
• duration: The total duration of the animation in seconds.
• fps: The frame rate at which the animation should be played, expressed in frames per second.

Note

Setting the property has no effect if a state machine is currently active. A value of -1 for currentStateMachineIndex signifies that no state machine is selected.

Example:

RiveQtQuickItem {
    currentAnimationIndex: 2 // Starts the third animation
}

currentArtboardIndex

RiveQtQuickItem::currentArtboardIndex

readwrite

Represents the currently active artboard index.

Set this property to change the active artboard being displayed. The index corresponds to the position of the artboard in the artboards list. Changing the index will immediately reflect the change in the displayed content.

Example:

RiveQtQuickItem {
    currentArtboardIndex: 1 // Sets the second artboard as active
}

currentStateMachineIndex

RiveQtQuickItem::currentStateMachineIndex

readwrite

Represents the currently active state machine index.

Altering this property's value changes the active state machine. The index corresponds to the position of the state machine in the stateMachines list. Set the property to -1 to deselect any active state machine.

Example:

RiveQtQuickItem {
    currentStateMachineIndex: 0 // Activates the first state machine
}

fileSource

RiveQtQuickItem::fileSource

readwrite

Represents the source file for the Rive animation.

This property holds the path to the Rive animation file that will be used by the RiveQtQuickItem. Setting this property will initiate the loading process for the given animation. Once the animation is successfully loaded, users can manipulate and control playback via the other properties and methods provided by this class.

Note

Ensure that the provided file path is valid and the file is accessible.

Example:

RiveQtQuickItem {
 fileSource: "/path/to/rive/file.riv"
}

fillMode

RiveQtQuickItem::fillMode

readwrite

Represents the fill mode setting.

This property determines how the Rive animation fits within the bounding box of the item.

The possible modes are:

• Stretch: Stretches the animation to fill the entire bounding box.
• PreserveAspectFit: Maintains the original aspect ratio while fitting the animation within the bounds.
• PreserveAspectCrop: Maintains the original aspect ratio, potentially cropping parts of the animation if they exceed the bounds.

Example:

RiveQtQuickItem {
    fillMode: RiveRenderSettings.PreserveAspectFit // Sets the fill mode to preserve aspect while fitting
}

frameRate

RiveQtQuickItem::frameRate

read

Represents the frame rate of the animation.

This property provides the frame rate (in frames per second) at which the loaded Rive animation is intended to be played. It gives an insight into the expected playback speed of the animation.

Example:

RiveQtQuickItem {
    Component.onCompleted: {
        console.log(frameRate); // Outputs the animation's frame rate
    }
}

interactive

RiveQtQuickItem::interactive

readwrite

Indicates if the item is interactive.

When set to true, the item responds to mouse interactions. If set to false, it will not register any mouse interactions, except hover effects.

Example:

RiveQtQuickItem {
    interactive: false // Disables mouse interactions
}

loadingStatus

RiveQtQuickItem::loadingStatus

read

Indicates the loading status of the Rive file.

This property represents the current state of the Rive file loading process.

The possible statuses are:

• Idle: No file is being loaded.
• Loading: A file is currently being loaded.
• Loaded: The file has been successfully loaded.
• Error: An error occurred during the loading process.
• Unloading: The file is currently being unloaded.

Note

Monitoring this property is essential to determine the state of the animation and to handle any potential loading errors.

postprocessingMode

RiveQtQuickItem::postprocessingMode

readwrite

Represents the postprocessing.

The property defines whether the RiveQtQuickItem should be postprocessed

The possible modes are:

• None: No postprocessing is done
• SMAA: An antialiasing step is executed using the SMAA (Subpixel Morphological Antialiasing) algorithm

Example:

RiveQtQuickItem {
    postprocessingMode: RiveRenderSettings.SMAA // do antialiasing using SMAA
}

renderQuality

RiveQtQuickItem::renderQuality

readwrite

Represents the render quality setting.

This property defines the visual quality of the rendered Rive animation.

The possible qualities are:

• Low: Provides a lower-quality, optimized render. Suitable for less powerful devices.
• Medium: Provides a balanced render quality suitable for most applications.
• High: Delivers the highest quality render. May be resource-intensive.

Example:

RiveQtQuickItem {
    renderQuality: RiveRenderSettings.High // Sets the render quality to high
}

stateMachineInterface

RiveQtQuickItem::stateMachineInterface

readwrite

Represents the state machine property interface.

This object allows introspection and manipulation of the properties and states provided by Rive's state machine. For more details and advanced usage, refer to the detailed documentation specific to RiveStateMachineInput.

Example:

RiveQtQuickItem {
    stateMachineInterface: RiveStateMachineInput {
        property real level: slider.value // level must match a property name in the animation for this to work
    }
}
 
Slider {
     id: slider
     from: 1
     value: 25
     to: 100
     stepSize: 0.1
 }

stateMachines

RiveQtQuickItem::stateMachines

read

Contains a list of available state machines.

This property provides a list of state machines that are defined in the loaded Rive file. Each state machine entry, as defined by the StateMachineInfo struct, provides meta information, helping users to understand the structure and possible states of the machine.

Structure Details:

The StateMachineInfo struct contains the following properties:

• id: A unique identifier for the state machine.
• name: The name of the state machine.

Example:

RiveQtQuickItem {
    Component.onCompleted: {
        console.log(stateMachines[0].name); // Outputs the name of the first state machine
    }
}