define

A define is a string variable that is created at loading time just after its declaration is parsed. A define value can be reassigned, but only during loading time. After the loading completes, the value becomes a constant.

A define can be used for different purposes:

• Assign values to node fields.

• Branch code to load according to define existence or value.

• Create recursive template instancing at loading time.

• Expose configurable values to the user through the use of custom.xml.

Platform support

This element is fully supported on XR-Windows, XR-Portable Windows, XR-Portable iOS, XR-Portable Android, and XR-P WASM platforms.

Overwriting a define

You redefine, or redeclare, a define a multiple number of times. Declaring a define multiple times in the code will assign the latest value that was read at parsing time. By default, the software shows an error in the log for each time the define is redeclared. This is done to prevent accidental multiple declaration. If the reassignment is implemented by design, you can set the overwrite field of the define to true and the error will not appear.

Remember that define value can be reassigned, but only during loading time. After loading time, it becomes a constant.

The define value is always managed as a string content. To be able to perform assignments that perform value resolution, such as mathematical operations, you will need to explicitly set the resolve attribute to true.

For more information, see Using defines to override.

Recursive templates usage

One of the main reasons to overwrite a define is to create loops at loading time to instantiate templates multiple times based on a define value. This can be useful to create the exact quantity of needed content, instead of creating boxed quantities.

The template below is executed five times with idx value set to 0,1,2,3,4.

<define name=”neededIterations” value=”5” />

<deftemplate name=”REC_TEMPLATE” >

<ifndef=”currentIteration” >

<define name=” currentIteration” value=”%idx% />

</ifnedef>

<!—template stuff [Symbol]

<!-- … [Symbol]

<if condition=”@def:currentIteration@&lt;@def:neededIterations@” >

<define name=”currentIteration” value=”#@def:currentIteration@+1#” overwrite=”true” resolve=”true” />

<usetemplate name=”REC_ TEMPLATE” idx=”@def:currentIteration@” />

</if>

</deftemplate>

<usetemplate name=”REC_TEMPLATE” idx=”0” />

Different define declaration syntaxes

You can create defines with different syntaxes that will produce different results.

Standard assignment

This is the assignment to create a simple define.

<define name=”app.main.define” value=”this value” />

MDSTRING type assignment

If you need to create an MDSTRING type define, instead of using the standard syntax.

With MDSTRING type, you can use a structured and simpler syntax. The define must be signed with type attribute set to mdstring.

<!—mdstring as standard define -->

<define name=”complexDefine” value=” {dic1={key1=value1}{key2=value2}}{dic2={key3=value3}} “ />

<!—same mdstring with specific syntax [Symbol]

<define name=”complexDefine” type=”mdstring”>

<set key=”dic1” >

<item key=”key1” value=”value1” />

<item key=”key2” value=”value2” />

</set>

<set key=”dic2” >

<item key=”key3” value=”value3” />

</set>

</define>

In both cases, one define named complexDefine is created with the string value set as:

“{dic1={key1=value1}{key2=value2}}{dic2={key3=value3}}”

Config type syntax

This Config type syntax enables you to create multiple defines with a single declaration using the same syntax used by the config type files. This is a nice feature as the content of the define can be easily copied into a config file.

<!—config syntax [Symbol]

<define name=”app” type=”config”>

<item name=”type” value=”aType” />

<struct name=”details” />

<item name=”color” value=”0 0 0” />

</struct>

</define>

<!—is equivalent to [Symbol]

<define name=”app.type” value=”aType” />

<define name=”app.details.color” value=”0 0 0”/>

Fields

These are the fields for define command.