Rive Qt QML API reference

Everything is in one module:

import Hypernuclear.Rive

RiveView is the only type you create. The others come from it: its state machine, its bound view model, and that view model’s properties.

RiveView

A QQuickItem that loads a .riv, advances it on the scene graph’s frame clock, and renders it with Rive’s GPU renderer.

Loading

Property	Type	Default
`source`	`url`		The `.riv` to load: `qrc:/`, `file://` or `http(s)://`. Remote files load asynchronously.
`artboard`	`string`	`""`	The artboard to show. Empty means the file’s default.
`artboardNames`	`list<string>`		Every artboard in the file. Read-only.

loadFailed(string reason) is emitted when the file can’t be fetched or parsed.

Playback

Property	Type	Default
`playing`	`bool`	`true`	Whether the artboard advances.
`speed`	`real`	`1.0`	Playback rate: `0.5` is half speed, `0` freezes. Negative values clamp to `0`.
`playbackMode`	`enum`	`Auto`	What drives the artboard; see below.
`stateMachineName`	`string`	`""`	The state machine to run. Empty means the artboard’s default.
`stateMachineNames`	`list<string>`		The artboard’s state machines. Read-only.
`animationName`	`string`	`""`	The linear animation to play when no state machine is driving. Empty means the first.
`animationNames`	`list<string>`		The artboard’s linear animations. Read-only.
`currentFrame`	`int`		The animation’s playhead, in frames. Write it to seek.
`frameCount`	`int`		The animation’s length, in frames. Read-only.
`fps`	`int`		The animation’s frame rate. Read-only.

currentFrame, frameCount and fps describe linear animations only, and read 0 while a state machine is running: a state machine is a graph, not a timeline. To scrub, set playing: false and write currentFrame.

playbackMode takes RiveView.PlaybackMode:

Auto: run the state machine; if the artboard has none, play the linear animation.
StateMachine: run the state machine only. Without one, the artboard stays still.
Animation: never build the state machine; play animationName. The mode for timelines you scrub or sequence yourself.

Method	Returns
`animationDuration(name)`	`real`	The animation’s length in seconds, without loading it.
`animationLoops(name)`	`bool`	Whether the animation repeats.
`stateMachineGraph(name)`	`object`	The machine’s states, transitions and entry, as a map. Empty before the file loads.

Layout

Property	Type	Default
`fit`	`enum`	`Contain`	How the artboard fits the item.
`alignment`	`enum`	`Center`	Where it sits when it doesn’t fill the item.
`layoutSize`	`size`	invalid	Drives the artboard’s own size, for responsive artboards. Invalid uses the size it was designed at.

fit takes RiveView.Fit: Fill, Contain, Cover, FitWidth, FitHeight, None, ScaleDown and Layout. Layout hands sizing to Rive’s layout system; pair it with layoutSize.

alignment takes RiveView.Alignment: TopLeft, TopCenter, TopRight, CenterLeft, Center, CenterRight, BottomLeft, BottomCenter and BottomRight.

Input

Property	Type	Default
`inputForwarding`	`bool`	`true`	Sends mouse, touch and keyboard input to the state machine, mapped into artboard space. Turn it off to send pointer events yourself through `stateMachine`.

Keyboard input reaches the artboard while the RiveView has focus.

Data binding

Property	Type	Default
`viewModel`	`RiveViewModelInstance`		The bound view model instance, or `null`. Read-only.
`viewModelNames`	`list<string>`		Every view model in the file. Read-only.
`viewModelName`	`string`	`""`	The view model to bind. Empty follows the artboard’s default.
`viewModelInstanceName`	`string`	`""`	Which of its instances to bind. Empty uses the default instance.
`autoBindViewModel`	`bool`	`true`	Binds the artboard’s default view model on load. Turn it off to bind later with `bindViewModelInstance()`.

Method	Returns
`bindViewModelInstance(name)`	`bool`	Binds the named instance (and turns `autoBindViewModel` back on). Returns `true` when a bind was scheduled; watch `viewModel` for the result.

State machine

Property	Type
`stateMachine`	`RiveStateMachine`	The running state machine, or `null` before the file loads. Replaced when `artboard` or `stateMachineName` changes.

stateMachineStateChanged(string layerName, string stateName) is emitted for every state the machine enters.

Fonts

Method
`RiveView.setFallbackFontPath(path)`	A font used for any text whose font asset can’t be resolved, for every `RiveView` in the process. Defaults to a system font (Segoe UI, Helvetica or DejaVu Sans). Empty turns the fallback off.
`RiveView.fallbackFontPath()`	The current fallback.

RiveStateMachine

The running state machine, from RiveView.stateMachine. RiveView advances it; you can send it pointer events and watch its states.

Property	Type
`name`	`string`	The machine’s name.
`currentStateTimeline`	`string`	The timeline of the state now playing.
`currentStateTime`	`real`	Seconds into that timeline. `0` while nothing is playing. For progress displays; you can’t seek a state machine.

Method	Returns
`pointerDown(pos, pointerId = 0)`	`HitResult`	A press at `pos`, in artboard coordinates.
`pointerMove(pos, pointerId = 0)`	`HitResult`	A move.
`pointerUp(pos, pointerId = 0)`	`HitResult`	A release.
`pointerExit(pos, pointerId = 0)`	`HitResult`	The pointer leaving.

HitResult is None, Hit (a listener took it) or HitOpaque (an opaque listener took it; don’t pass it on). Give each concurrent touch its own pointerId.

stateChanged(string layerName, string stateName) is emitted when a layer enters a state. stateName is the state’s timeline; entry, exit, any and blend states report an empty name.

Rive has retired state machine inputs and events in favour of data binding, so there are no input setters or event signals here. Use the view model.

RiveViewModelInstance

The bound view model, from RiveView.viewModel (or a nested or list property). Reach its properties by name, typed:

Method	Returns
`number(name)`	`RiveVMNumberProperty`
`boolean(name)`	`RiveVMBooleanProperty`
`string(name)`	`RiveVMStringProperty`
`color(name)`	`RiveVMColorProperty`
`enumProperty(name)`	`RiveVMEnumProperty`
`trigger(name)`	`RiveVMTriggerProperty`
`viewModel(name)`	`RiveVMNestedProperty`
`list(name)`	`RiveVMListProperty`
`image(name)`	`RiveVMImageProperty`
`artboard(name)`	`RiveVMArtboardProperty`
`property(name)`	`RiveVMProperty`, whatever its type

Each returns null when there’s no property by that name and type, and the same object every time for the same name, so bindings to it hold.

Property	Type
`propertyNames`	`list<string>`	Every property’s name.
`props`	`object`	The plain values (numbers, booleans, strings, colors, enums) by name, for declarative bindings: `text: rive.viewModel.props.title`, or `rive.viewModel.props.title = "Hi"`.

View model properties

Every property has name and type (RiveVMProperty.Type: Number, Boolean, String, Color, Enum, Trigger, ViewModel, List, Image, Artboard). A write wakes a settled state machine, so the change shows on the next frame.

Type	Members
`RiveVMNumberProperty`	`value` (`real`), `valueChanged()`
`RiveVMBooleanProperty`	`value` (`bool`), `valueChanged()`
`RiveVMStringProperty`	`value` (`string`), `valueChanged()`
`RiveVMColorProperty`	`value` (`color`), `valueChanged()`
`RiveVMEnumProperty`	`valueIndex` (`int`), `valueName` (`string`), `values` (`list<string>`, read-only), `valueChanged()`
`RiveVMTriggerProperty`	`fire()`, `triggered()`
`RiveVMNestedProperty`	`value` (`RiveViewModelInstance`, read-only), `valueChanged()`
`RiveVMListProperty`	`count`, `itemAt(index)`, `removeAt(index)`, `swap(a, b)`, `clear()`, `countChanged()`
`RiveVMImageProperty`	`setSource(url)`: replaces the image from a `qrc:/` or file URL
`RiveVMArtboardProperty`	`value` (`string`: the artboard’s name), `valueChanged()`

triggered() fires whether your code or the file fired the trigger, which makes triggers the way an artboard signals your app. Several fire() calls between two frames count as one.