Q3DSPresentation Class | Qt 3D Studio Runtime 2.0

Qt 3D Studio Runtime | C++ Classes | Q3DSPresentation

Qt 3D Studio Runtime 2.0 Manual

# Q3DSPresentation Class

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

Header: | #include <Q3DSPresentation>
Since: | Qt 3D Studio 2.0
Instantiated By: | Presentation
Inherits: | QObject

- List of all members, including inherited members

## Properties

- profileUiScale : float
- profileUiVisible : bool
- profilingEnabled : bool
- source : QUrl

- 1 property inherited from QObject

## Public Functions

| Q3DSPresentation(QObject *parent = nullptr)
virtual | ~Q3DSPresentation()
void | fireEvent(const QString &elementPath, const QString &eventName)
QVariant | getAttribute(const QString &elementPath, const QString &attributeName)
void | goToSlide(const QString &elementPath, const QString &name)
void | goToSlide(const QString &elementPath, int index)
void | goToSlide(const QString &elementPath, bool next, bool wrap)
void | goToTime(const QString &elementPath, float timeSeconds)
bool | isProfileUiVisible() const
bool | isProfilingEnabled() const
void | keyPressEvent(QKeyEvent *e)
void | keyReleaseEvent(QKeyEvent *e)
void | mouseDoubleClickEvent(QMouseEvent *e)
void | mouseMoveEvent(QMouseEvent *e)
void | mousePressEvent(QMouseEvent *e)
void | mouseReleaseEvent(QMouseEvent *e)
float | profileUiScale() const
void | reload()
void | setAttribute(const QString &elementPath, const QString &attributeName, const QVariant &value)
void | setDataInputValue(const QString &name, const QVariant &value)
void | setProfileUiScale(float scale)
void | setProfileUiVisible(bool visible)
void | setProfilingEnabled(bool enable)
void | setSource(const QUrl &source)
QUrl | source() const
void | tabletEvent(QTabletEvent *e)
void | touchEvent(QTouchEvent *e)
void | wheelEvent(QWheelEvent *e)

- 34 public functions inherited from QObject

## Signals

void | customSignalEmitted(const QString &elementPath, const QString &name)
void | profileUiScaleChanged()
void | profileUiVisibleChanged()
void | profilingEnabledChanged()
void | slideEntered(const QString &elementPath, int index, const QString &name)
void | slideExited(const QString &elementPath, int index, const QString &name)
void | sourceChanged()

- 2 signals inherited from QObject

### Additional Inherited Members

- 1 public slot inherited from QObject
- 1 public variable inherited from QObject
- 10 static public members inherited from QObject
- 9 protected functions inherited from QObject
- 2 protected variables inherited from QObject

## Detailed Description

Represents a Qt 3D Studio presentation.

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

Note: This class should not be instantiated directly when working with the C++ APIs. Q3DSSurfaceViewer and Q3DSWidget create a Q3DSPresentation instance implicitly. This can be queried via Q3DSSurfaceViewer::presentation() or Q3DSWidget::presentation().

## Property Documentation

### profileUiScale : float

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

The default value is 1.0.

Access functions:

float | profileUiScale() const
void | setProfileUiScale(float scale)

Notifier signal:

void | profileUiScaleChanged()

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

Access functions:

bool | isProfileUiVisible() const
void | setProfileUiVisible(bool visible)

Notifier signal:

void | profileUiVisibleChanged()

### 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. Therefore the changing of this property must happen before calling setSource().

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

Access functions:

bool | isProfilingEnabled() const
void | setProfilingEnabled(bool enable)

Notifier signal:

void | profilingEnabledChanged()

### source : QUrl

Holds the name of the main presentation file (`*.uia` or `*.uip`). This may be either a local file or qrc URL.

The names of all further assets (image files for texture maps, qml behavior scripts, mesh files) will be resolved relative to the location of the presentation, unless they use absolute paths. This allows bundling all assets next to the presentation in the Qt resource system.

Access functions:

QUrl | source() const
void | setSource(const QUrl &source)

Notifier signal:

void | sourceChanged()

## Member Function Documentation

### Q3DSPresentation::Q3DSPresentation(QObject *parent = nullptr)

Constructs a new Q3DSPresentation with the given parent.

### `[virtual]` Q3DSPresentation::~Q3DSPresentation()

Destructor.

### `[signal]` void Q3DSPresentation::customSignalEmitted(const QString &elementPath, const QString &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")`.

### void Q3DSPresentation::fireEvent(const QString &elementPath, const QString &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().

See setAttribute() for a description of elementPath.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

### QVariant Q3DSPresentation::getAttribute(const QString &elementPath, const QString &attributeName)

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

See setAttribute() for a description of elementPath.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

See also setAttribute.

### void Q3DSPresentation::goToSlide(const QString &elementPath, const QString &name)

Requests a time context (a Scene or a Component object) 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"`.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

### void Q3DSPresentation::goToSlide(const QString &elementPath, int index)

Requests a time context (a Scene or a Component object) to change to a specific slide by 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"`.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

### void Q3DSPresentation::goToSlide(const QString &elementPath, bool next, bool wrap)

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

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

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

### void Q3DSPresentation::goToTime(const QString &elementPath, float timeSeconds)

Moves the timeline for a time context (a Scene or a Component element) to a specific position. The position is given in seconds in timeSeconds.

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

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

### void Q3DSPresentation::keyPressEvent(QKeyEvent *e)

Passes a key press event e to the presentation.

Note: The event forwarders in Q3DSPresentation are not normally needed since Q3DSWidget and Studio3D both pass mouse, keyboard and touch input on to the Qt 3D Studio engine. They may become useful however with Q3DSSurfaceViewer, or in special situations, in order to inject input events.

### void Q3DSPresentation::keyReleaseEvent(QKeyEvent *e)

Passes a key release event e to the presentation.

Note: The event forwarders in Q3DSPresentation are not normally needed since Q3DSWidget and Studio3D both pass mouse, keyboard and touch input on to the Qt 3D Studio engine. They may become useful however with Q3DSSurfaceViewer, or in special situations, in order to inject input events.

### void Q3DSPresentation::mouseDoubleClickEvent(QMouseEvent *e)

Passes a mouse double click event e to the presentation.

Note: The event forwarders in Q3DSPresentation are not normally needed since Q3DSWidget and Studio3D both pass mouse, keyboard and touch input on to the Qt 3D Studio engine. They may become useful however with Q3DSSurfaceViewer, or in special situations, in order to inject input events.

### void Q3DSPresentation::mouseMoveEvent(QMouseEvent *e)

Passes a mouse move event e to the presentation.

Note: The event forwarders in Q3DSPresentation are not normally needed since Q3DSWidget and Studio3D both pass mouse, keyboard and touch input on to the Qt 3D Studio engine. They may become useful however with Q3DSSurfaceViewer, or in special situations, in order to inject input events.

### void Q3DSPresentation::mousePressEvent(QMouseEvent *e)

Passes a mouse press event e to the presentation.

Note: The event forwarders in Q3DSPresentation are not normally needed since Q3DSWidget and Studio3D both pass mouse, keyboard and touch input on to the Qt 3D Studio engine. They may become useful however with Q3DSSurfaceViewer, or in special situations, in order to inject input events.

### void Q3DSPresentation::mouseReleaseEvent(QMouseEvent *e)

Passes a mouse release event e to the presentation.

Note: The event forwarders in Q3DSPresentation are not normally needed since Q3DSWidget and Studio3D both pass mouse, keyboard and touch input on to the Qt 3D Studio engine. They may become useful however with Q3DSSurfaceViewer, or in special situations, in order to inject input events.

### void Q3DSPresentation::reload()

Reloads the presentation.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

### void Q3DSPresentation::setAttribute(const QString &elementPath, const QString &attributeName, const QVariant &value)

Sets the value of an attribute (property) on the 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`.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

See also getAttribute.

### void Q3DSPresentation::setDataInputValue(const QString &name, const QVariant &value)

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

Data input provides a higher level, designer-driven alternative to Q3DSElement and setAttribute(). 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() and goToTime() family of APIs and to Q3DSSceneElement.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

### `[signal]` void Q3DSPresentation::slideEntered(const QString &elementPath, int index, const QString &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.

### `[signal]` void Q3DSPresentation::slideExited(const QString &elementPath, int index, const QString &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.

### void Q3DSPresentation::tabletEvent(QTabletEvent *e)

Passes a tablet (pen) event e to the presentation.

Note: The event forwarders in Q3DSPresentation are not normally needed since Q3DSWidget and Studio3D both pass mouse, keyboard and touch input on to the Qt 3D Studio engine. They may become useful however with Q3DSSurfaceViewer, or in special situations, in order to inject input events.

### void Q3DSPresentation::touchEvent(QTouchEvent *e)

Passes a touch event e to the presentation.

Note: The event forwarders in Q3DSPresentation are not normally needed since Q3DSWidget and Studio3D both pass mouse, keyboard and touch input on to the Qt 3D Studio engine. They may become useful however with Q3DSSurfaceViewer, or in special situations, in order to inject input events.

### void Q3DSPresentation::wheelEvent(QWheelEvent *e)

Passes a mouse wheel event e to the presentation.

Note: The event forwarders in Q3DSPresentation are not normally needed since Q3DSWidget and Studio3D both pass mouse, keyboard and touch input on to the Qt 3D Studio engine. They may become useful however with Q3DSSurfaceViewer, or in special situations, in order to inject input events.