TODO: Rewrite is needed.

Every project has one .uia file (which we like to pronounce as "OO-yah!") representing the application. This XML file is created automatically when you create a new project with Qt 3D Studio. The file contains an <assets> section followed by zero or more <statemachine> sections:

<?xml version="1.0" encoding="UTF-8"?>
<application scalemode="center" watermark-location="1.0 1.0" xmlns="http://nvidia.com/uicomposer">
  <assets initial="#IVI">
    <behavior     id="MainApp" src="scripts/App.lua"                        />
    <presentation id="IVI"     src="IVI.uip"                                />
    <presentation id="music"   src="sub_music.uip"                          />
    <presentation id="radio"   src="sub_radio.uip"   active="false"         />
    <statemachine id="logic"   src="./charts/app.scxml" datamodel="getIt()" />
    <renderplugin id="plugin:mapviewer" src="scripts/mylib.so" args="whee"  />
  </assets>

  <statemachine ref="#logic">
    <visual-states>
      <state ref="Menu">
        <enter>
          <goto-slide element="IVI:Scene.Layer3D.Camera" slide="Animated"/>
        </enter>
        <exit>
          <goto-slide element="IVI:Scene" rel="next" wrap="true"/>
        </exit>
      </state>
      <state ref="Climate"><enter>
        <call element="IVI:Scene.Menu" handler="focusItem" arguments="'Climate'"/>
        <set-attribute element="IVI:Scene.Subs" attribute="sourcepath" value="'phone'"/>
      </enter></state>
      <transition ref="transition_93">
        <fire-event element="IVI:Scene" event="onSomethingHappened" />
      </transition>
    </visual-states>
  </statemachine>
</application>

Application

The <application> element encompasses the contents of the file and also specifies simple attributes for the application's display.

The scalemode="..." attribute specifies how large the "initial presentation" (see below) is rendered when the dimensions of the supplied viewport are different than the size entered for that presentation. There are three legal values for this attribute:

• scalemode="center" - the presentation is rendered at the size specified in Studio. Additional content is cropped, additional space is letterboxed. This setting is the default behavior if not specified.
• scalemode="fit" - the aspect ratio of the initial presentation is preserved, letterboxing as needed.
• scalemode="fill" - the presentation is always rendered to fill the viewport.

For more information on the behavior of the scalemode settin - nd its interaction with layer sizing and camera scalin - ee Using Scale Modes.

Assets

The <assets> section may contain one or more <behavior/>, <presentation/>, <statemachine/>, and <renderplugin/> elements, in any order.

Each asset must have a unique id="..." attribute and a src="..." attribute referencing the location of the file (relative to the project folder).

A <statemachine/> asset may optionally have a datamodel="..." attribute. If present, this attribute must provide valid Lua code to run that returns a Lua table. The contents of this table will be used for the initial values in the data model of the state chart.

A <renderplugin/> asset may optionally have a args="..." attribute. This provides arguments needed to initialize the shared library for the plugin.

An application does not need any <presentation/> elements to run. This allows you to create state charts and test them before any visuals have been created. Such an application will not display anything on screen, however.

If more than one <presentation/> asset is supplied then the first one listed is chosen as the `initial' (outermost) presentation that renders for the application; all others are treated as `sub-presentations' which may be referenced by the main presentation. To select a different presentation as the initial the <assets> element may have an initial="\#presentation-id" attribute referencing the presentation to use as the main presentation.

A <presentation/> element may optionally have an active="..." attribute with either the value true (the default) or false. See the <set-presentation> action below for more information on the effects of making a presentation inactive.

All <behavior/> assets are initialized before any <statemachine/> assets, regardless of element ordering. This allows you to create a global function in your application behaviors and use that function to initialize the data model for a state chart.

Visual States

Each <statemachine/> in the <assets> section (above) may have a paired <statemachine> element following the <assets> section. These provide the glue between the logical states of the state chart and the visual impact displayed by the presentation(s).

A <statemachine> section must have a ref="\#statemachine-asset-id" attribute referencing the state chart to listen to.

The only allowed child element of a <statemachine> section is <visual-states>. The <visual-states> element may have zero or more <state> and <transition> elements, in any order.

• Each <state> element must have a ref="StateId" attribute describing a valid state id in the associated state chart. It may have either or both of <enter> and <exit> elements, describing what occurs when the state is entered or exited. Each of these elements may have zero or more visual action elements (see below).
• Each <transition> element must have a ref="TransitionId" attribute describing a valid transition id in the associated state chart. It may have zero or more visual action elements that describe what occurs when the transition is taken.

Visual Actions

The content elements in each <enter>, <exit>, and <transition> element may be any of the following (as many as you like, in any order):

<goto-slide element="..."/>

Change scene or component slide, possibly changing how it plays.

• The element attribute must reference a full path to a Scene or component element in a presentation, prefixed with that presentation's id and a colon. For example, element="IVI:Scene.Background.Theme".
• The action must have either a slide="..."** or rel="..." attribute (but not both):
• The slide attribute must reference the name of a slide to go to.
• The rel attribute must be either rel="next" or rel="prev", describing a direction to change slides.
  • (optional) With rel you may also supply wrap="true" to indicate that slide changes past the end of the slide list should wrap to the slide on the other end.
• (optional) Specifying direction="..." will force playback on the new slide to go either forward or reverse.
• If the direction is reverse and no time="..." attribute is specified (see below) then playback will start at the end time of the slide.
• (optional) Specifying mode="..." will override the play mode for the slide to be one of: stopatend, looping, ping, pingpong, or playthrough.
• If playthrough is specified you must also add playthroughto="..." with either the name of a slide to play through to, or the values next or previous.
• (optional) Specifying state="..." with either play or pause will override the play state set for the slide.
• (optional) Specifying rate="..." with a floating point value will cause the playback speed to be multiplied by this value.
• For example, a value of 2 will cause animations on the slide to play back twice as fast as normal, while a value of 0.5 will cause animations to play at half speed.
• The behavior of the runtime for negative rate values is not guaranteed; use direction="reverse" to play backwards.
• (optional) Specifying time="..." with a floating point value will cause playback to start at the specified time.

<call element="..." handler="..."/>

Invoke a function on a presentation behavior.

• The element attribute must reference a full id-prefixed path to a behavior element in a presentation.
• The handler attribute must match the name of a function value on the table for the referenced behavior.
• (optional) Specifying an arguments="..." attribute allows you to pass arguments to the function. The contents of this attribute are evaluated in the global Lua context. If the resulting value is a Lua table, it is treated as a list and each integer-keyed value passed to the function through unpack(). If the result is any other type of value it is passed as a single first parameter to the function.
• To pass just one argument, use arguments="42"
• To pass multiple arguments, use arguments="\{1,2,3\}"
• To pass a single Lua table to the function wrap it in a list table, e.g. arguments="\{\{hello='World',valid=true\}\}"

<set-attribute element="..." attribute="..." value="..."/>

Set a value on a presentation element.

• The element attribute must reference a full id-prefixed path to any element in a presentation.
• The attribute attribute must match the scripting name of an attribute on that element.
• The value attribute must provide a Lua expression to evaluate, the result of which will be set as the value on the element.

For example, <set-attribute element="IVI:Scene.Background" attribute="name" value="'new name'"/>; note the extra quotes needed in the value attribute to set a string value.

<set-presentation ref="..." attribute="active" value="..."/>

make a presentation active/inactive.

• The ref must be the id of a <presentation/> in the <assets> section.
• The attribute attribute must be equal to active. (Future releases may allow the control of more presentation attributes.)
• The value attribute must be either true or false. (Arbitrary Lua expressions are not supported at this time.)

For example, <set-presentation ref="music" attribute="active" value="true"/>.

Notes

• Making a presentation inactive prevents any elements, behaviors, and animations within it from updating. It also prevents any events within that presentation from being processed. It does not, however, prevent the presentation from rendering. An inactive presentation will continue to render using its last-updated information.
• Explicitly inactivating presentations can provide a significant performance increase, depending on the number and size of the presentations that are inactive.
• Inactive presentations are not `paused'. When the presentation is re-activated, animations will resume at the time they should be had they been running, not where they were when the presentation was made inactive.

<fire-event element="..." event="..."/>

Fire a presentation event on an element in the presentation.

• The element attribute must reference a full id-prefixed path to any element in a presentation.
• The event attribute must be the name of the event to fire.