Presentation QML Type | Qt 3D Studio Runtime 2.0

Qt 3D Studio Runtime | QML Types | Presentation QML Type

Qt 3D Studio Runtime 2.0 Manual

# Presentation QML Type

Represents a Qt 3D Studio presentation. More...

Import Statement: | import .
Instantiates: | Q3DSPresentation

- List of all members, including inherited members

## Properties

- profileUiScale : real
- profileUiVisible : bool
- profilingEnabled : bool
- source : url

## Signals

- customSignalEmitted(string elementPath, string name)
- slideEntered(string elementPath, int index, string name)
- slideExited(string elementPath, int index, string name)

## Methods

- void fireEvent(string elementPath, string eventName)
- variant getAttribute(string elementPath, string attributeName)
- void goToSlide(string elementPath, bool next, bool wrap)
- void goToSlide(string elementPath, int index)
- void goToSlide(string elementPath, string name)
- void goToTime(string elementPath, real time)
- void setAttribute(string elementPath, string attributeName, variant value)
- void setDataInputValue(string name, variant value)

## Detailed Description

This class provides properties and methods for controlling a presentation.

Qt 3D Studio supports multiple presentations in one project. There is always a main presentation and zero or more sub-presentations. The sub-presentations are composed into the main presentations either as contents of Qt 3D Studio layers or as texture maps.

In the filesystem each presentation corresponds to one `.uip` file. When present, the `.uia` file ties these together by specifying a name for each of the (sub-)presentations and specifies which one is the main one.

From the API point of view Presentation corresponds to the main presentation. The source property can refer either to a `.uia` or `.uip` file. When specifying a file with `.uip` extension and a `.uia` is present with the same name, the `.uia` is loaded automatically and thus sub-presentation information is available regardless.

The Presentation type handles child objects of the types Element, SceneElement, DataInput, and SubPresentationSettings specially. These will get automatically associated with the presentation and can control certain aspects of it from that point on.

### Example usage

      Studio3D {
          Presentation {
              id: presentation

              source: "qrc:/presentation/barrel.uip"
              profilingEnabled: true

              onSlideEntered: console.log("Entered slide " + name + "(index " + index + ") on " + elementPath)
              onSlideExited: console.log("Exited slide " + name + "(index " + index + ") on " + elementPath)
              onCustomSignalEmitted: console.log("Got custom signal " + name)

              DataInput {
                  name: "di_text"
                  value: "hello world"
              }

              SceneElement {
                  elementPath: "SomeComponentNode"
                  onCurrentSlideIndexChanged: console.log("Current slide index for component: " + currentSlideIndex)
                  onCurrentSlideNameChanged: console.log("Current slide name for component: " + currentSlideName)
              }

              SubPresentationSettings {
                  qmlStreams: [
                      QmlStream {
                          presentationId: "sub-presentation-id"
                          Rectangle {
                              width: 1024
                              height: 1024
                              color: "red"
                          }
                      }
                  ]
              }
          }
      }
      Button {
          onClicked: presentation.setAttribute("SomeMaterial", "diffuse", "0 1 0");
      }

See also Studio3D.

## Property Documentation

profileUiScale : real

Controls the scale factor of the in-scene debug and profile views.

The default value is 1.0.

profileUiVisible : bool

When this property is `true`, the interactive statistics and profile view is displayed in-scene, on top of the 3D content.

Note: This feature can be disabled at build time, in which case this property has no effect.

Default value is `false`.

profilingEnabled : bool

When enabled, Qt 3D objects managed by the runtime get tracked, and various statistics get collected internally. These are then exposed in the views that can be toggled by profileUiVisible.

The default value is `false`.

Note: Changing the value after the presentation has been loaded has no effect for the already loaded presentation.

Note: In the Qt 3D Studio Viewer application presentations are opened with profiling enabled by default. Therefore, applications wishing to have an experience comparable to the Viewer, when it comes to the debug and profile views, should set this property to `true`.

source : url

Holds the main presentation source (`*.uia` or `*.uip`) file location. May be either a file URL or a qrc URL.

## Signal Documentation

customSignalEmitted(string elementPath, string name)

This signal is emitted when an action with the `Emit Signal` handler is executed in the Qt 3D Studio presentation. elementPath specifies the scene object on which the (Qt 3D Studio) "signal" name was triggered.

Connecting to this signal offers a way of reacting upon certain events in the Qt 3D Studio presentation.

In this example, pressing or tapping on the Cluster object will result in emitting `customSignalEmitted("Cluster", "clusterPressed")`.

slideEntered(string elementPath, int index, string name)

This signal is emitted when a slide is entered in the presentation. The elementPath specifies the time context (a Scene or a Component element) owning the entered slide. The index and name contain the index and the name of the entered slide.

slideExited(string elementPath, int index, string name)

This signal is emitted when a slide is exited in the presentation. The elementPath specifies the time context (a Scene or a Component element) owning the exited slide. The index and name contain the index and the name of the exited slide.

## Method Documentation

void fireEvent(string elementPath, string eventName)

Dispatches a Qt 3D Studio presentation event with eventName on scene object specified by elementPath. These events provide a way to communicate with the `.qml` based `behavior scripts` attached to scene objects since they can register to be notified via Behavior::registerForEvent().

variant getAttribute(string elementPath, string attributeName)

Returns the value of an attribute (property) on the object specified by elementPath. The attributeName is the scripting name of the attribute.

void goToSlide(string elementPath, bool next, bool wrap)

Requests a time context (a Scene or a Component node) to change to the next or the previous slide, depending on the value of next. If the context is already at the last or first slide, wrap defines if change occurs to the opposite end.

If elementPath points to a time context, that element is controlled. For all other element types the time context owning that element is controlled instead. You can target the command to a specific sub-presentation by adding "SubPresentationId:" in front of the element path, for example `"SubPresentationOne:Scene"`.

void goToSlide(string elementPath, int index)

Requests a time context (a Scene or a Component node) to change to a specific slide by index index. If the context is already on that slide playback will start over.

If elementPath points to a time context, that element is controlled. For all other element types the time context owning that element is controlled instead. You can target the command to a specific sub-presentation by adding "SubPresentationId:" in front of the element path, for example `"SubPresentationOne:Scene"`.

void goToSlide(string elementPath, string name)

Requests a time context (a Scene or a Component node) to change to a specific slide by name. If the context is already on that slide playback will start over.

If elementPath points to a time context, that element is controlled. For all other element types the time context owning that element is controlled instead. You can target the command to a specific sub-presentation by adding "SubPresentationId:" in front of the element path, for example `"SubPresentationOne:Scene"`.

void goToTime(string elementPath, real time)

Sets a time context (a Scene or a Component node) to a specific playback time in seconds.

If elementPath points to a time context, that element is controlled. For all other element types the time context owning that element is controlled instead. You can target the command to a specific sub-presentation by adding "SubPresentationId:" in front of the element path, for example `"SubPresentationOne:Scene"`.

The behavior when specifying a time before 0 or after the end time for the current slide depends on the play mode of the slide:

- `Stop at End` - values outside the valid time range instead clamp to the boundaries. For example, going to time -5 is the same as going to time 0.
- `Looping` - values outside the valid time range mod into the valid range. For example, going to time -4 on a 10 second slide is the same as going to time 6.
- `Ping Pong` - values outside the valid time range ‘bounce’ off the ends. For example, going to time -4 is the same as going to time 4 (assuming the time context is at least 4 seconds long), while going to time 12 on a 10 second slide is the same as going to time 8.
- `Ping` - values less than 0 are treated as time 0, while values greater than the endtime bounce off the end (eventually hitting 0.)

void setAttribute(string elementPath, string attributeName, variant value)

Sets the value of an attribute (property) on the Qt 3D Studio scene object specified by elementPath. The attributeName is the scripting name of the attribute.

An element path refers to an object in the scene either by name or id. The latter is rarely used in application code since the unique IDs are not exposed in the Qt 3D Studio application. To refer to an object by id, prepend `#` to the name. Applications will typically refer to objects by name.

Names are not necessarily unique, however. To access an object with a non-unique name, the path can be specified, for example, `Scene.Layer.Camera`. Here the right camera object gets chosen even if the scene contains other layers with the default camera names (for instance `Scene.Layer2.Camera`).

If the object is renamed to a unique name in the Qt 3D Studio application's Timeline view, the path can be omitted. For example, if the camera in question was renamed to `MyCamera`, applications can then simply pass `MyCamera` as the element path.

To access an object in a sub-presentation, prepend the name of the sub-presentation followed by a colon, for example, `SubPresentationOne:Scene.Layer.Camera`.

void setDataInputValue(string name, variant value)

Sets the value of a data input element name in the presentation.

Data input provides a higher level, designer-driven alternative to setAttribute or Element. Instead of exposing a large set of properties with their intenal engine names, data input allows designers to decide which properties should be writable by the application, and can assign custom names to these data input entries, thus forming a well-defined contract between the designer and the developer.

In addition, data input also allows controlling the time line and the current slide for time context objects (Scene or Component). Therefore it is also an alternative to the goToSlide, goToTime, and SceneElement.

As an alternative to this method, the DataInput type can be used. That approach has the advantage of being able to use QML property bindings for the value, instead of having to resort to JavaScript function calls for every value change.