# Rive Qt QML API reference

> Every property, method and signal of RiveView, its state machine, and the data-bound view model types in rive-qt-plugin.

Everything is in one module:

```qml

```

`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.

---

From https://hypernuclear.com/docs/rive-qt/qml-api/