UI Files

Almost all of the UI file tags have attributes, and it is good to know the following general rules:

• All dimensions provided as attribute values are in pixels.
• File names are relative to the root data directory.
• Colors are in the Web format, that is, #RRGGBB, or in the #RRGGBBAA format. Here RR, GG, BB, and AA correspond to a hexadecimal color component value—red, green, blue, and alpha, respectively; values range from 00 to FF.
• Boolean values can be set in different forms. For FALSE use: 0, false, no. For TRUE use: 1, true, yes.

<sprite align="overlap,top,right" pos_x="10" pos_y="-42" texture="data/core/gui/unigine.png"/>

You can use standard XML comments syntax. Comment blocks will be skipped during processing of a UI file. An example comment:

<!-- 
This section will be omitted
-->

A unique name of the widget. If the export flag is set to yes, the widget will be referred to in scripts by this name. The name may contain a namespace specification and/or an array index.

<!-- The following widget will be accessible via scripts as foo::bar -->
<button name="foo::bar" export="yes"/>
<!-- This widget will be accessible via scripts as fooArray[2] -->
<button name="fooArray[2]" export="yes"/>

A name of a widget that receives the focus next, if the user presses the TAB key. If this attribute is omitted, the widget that immediately follows the current one will receive the focus.

<!-- Custom focus order: button_0 → button_2 → button_1 -->
<button name="button_0" next="button_2"/>
<button name="button_1" next="button_0"/>
<button name="button_2" next="button_1"/>

A set of alignment flags for the widget. Flags are separated by commas. Available flags are:

• center
  Centers the widget in both dimensions in the available space.

  

  Source code (XML)

  <window name="Test::window" width="150" height="150" export="1" sizeable="1">
  	<text>Window Title</text>
  	<label align="center">
  		<text size="20">Label Center</text>
  	</label>
  </window>

• left
  Aligns the widget to the left side.

  

  Source code (XML)

  <label align="left">
  	<text size="20">Label Left</text>
  </label>

• right
  Aligns the widget to the right side.

  

  Source code (XML)

  <label align="right">
  	<text size="20">Label Right</text>
  </label>

• top
  Aligns the widget to the top.

  

  Source code (XML)

  <label align="top">
  	<text size="20">Label Top</text>
  </label>

• bottom
  Aligns the widget to the bottom.

  

  Source code (XML)

  <label align="bottom">
  	<text size="20">Label Bottom</text>
  </label>

• expand
  Justifies the text in the available space.

  

  Source code (XML)

  <vscroll name="Test::vscroll_0" export="1" align="expand"/>
  <vscroll name="Test::vscroll_1" export="1"/>

• overlap
  Places the widget over the contents of the parent container.

  

  Source code (XML)

  <label align="left">
  	<text size="35">Label</text>
  </label>
  <button name="Test::button" export="1"  align="overlap">
  	<text>Button</text>
  </button>

• background
  Places the widget underneath other widgets in the same container. Use this flag together with overlapone.
• fixed
  Places the widget in focus on the background or on the foreground (depending on where it was created). This flag is valid only if overlapflag is also set. Non-fixed overlapping windows can pop over the fixed ones, while the latter cannot do it.

A flag that specifies whether the widget is enabled. An enabled widget receives keyboard and mouse events; a disabled widget does not. Some widgets display themselves differently when they are disabled (usually they are dimmed). If a container is disabled, its content is also disabled. Acceptable values:

• 0 or no
  The widget is disabled.
• 1 or yes
  The widget is enabled.

<button name="Test::button" export="1"  enabled="1">
	<text size="15">Button Enabled</text>
</button>
<button name="Test::disabled_button" export="1" enabled="0">
	<text size="15">Button Disabled</text>
</button>

A flag that specifies whether the widget is hidden or not. When a widget is hidden, it is not rendered, and other widgets in the same container are re-arranged. Acceptable values:

• 0 or no
  The widget renders normally.
• 1 or yes
  The widget is hidden.

<label>
	<text size="20" rich="1">Label 0</text>
</label>
<button name="Test::button" export="1"  hidden="1">
	<text size="15">Button Hidden</text>
</button>
<label>
	<text size="20" rich="1">Label 1</text>
</label>
<label>
	<text size="20" rich="1">Label 2</text>
</label>
<button name="Test::disabled_button" export="1" hidden="0">
	<text size="15">Button Rendered</text>
</button>

The x-coordinate of the widget relative to its parent container. It takes effect only if the overlapalignment flag is set.

<button name="Test::button" export="1" align="overlap" pos_x="40">
	<text size="15">Button</text>
<button>

The y-coordinate of the widget relative to its parent container. It takes effect only if the overlapalignment flag is set.

<button name="Test::button" export="1" align="overlap" pos_y="30">
	<text size="15">Button</text>
<button>

Width of a widget.

Height of a widget.

A flag that specifies whether to export a reference to the widget or not. If yes, the widget will be exported with the name set using the name attribute. The default value is 0. Acceptable values:

• 0 or no (default)
  The widget will not be exported.
• 1 or yes
  The widget will be exported.

A flag indicating whether a container is referenced by the referencetag. Acceptable values:

• no reference flag or 0 (default)
  The container will be shown in the UI as usual.
• 1
  The container will not be shown in the UI and you will be able to refer it by using the referencetag.

Many widgets and containers have a text child, which provides some formatting capabilities.

Attributes:

• rich
  Whether the text inside the tag is formatted or plain. The default is 0 (boolean), which corresponds to plain.
• face
  Path to a TrueType font file, which will be used by default.
  Source code (XML)

  <text face="fontb.ttf">Text</text>

• size
  Default font size (pixels).
  Source code (XML)

  <text size="20">Text</text>

• color
  Default font color.
  Source code (XML)

  <text color="#ff0000">Text</text>

• permanent
  Whether a text color should be changed when the widget is disabled (non active), transparent (enabled option on non-active window), or widget loses focus. The default is 0 (not to change the color).

  For example, when the window is disabled, the second label doesn't change its color.

  

  Source code (XML)

  <window name="Test::window" width="150" height="150" export="1" sizeable="1" enabled="0">
  	<text>Window Title</text>
  	<label><text permanent="0">Label 0</text></label>
  	<label><text permanent="0">Label 1</text></label>
  </window>

• outline
  Whether the text should be outlined. The default is 0 (boolean), which corresponds to no outlining.

  

  The outlined text is represented on the right picture.

  Source code (XML)

  <label><text size="20" outline="1">Label 0</text></label>

• wrap
  Whether the text should be wrapped around, if it does not fit width of the container. The default is 0 (boolean), which corresponds to no wrapping.

  

  Source code (XML)

  <label><text size="20" wrap="1">Long text to wrap</text></label>

• hspacing
  Horizontal spacing (in pixels) between letters. The default is 0.

  

  Source code (XML)

  <label align="center"><text size="20" hspacing="8">Text</text></label>

• vspacing
  Vertical spacing (in pixels) between text lines. The default is 0.

  

  Source code (XML)

  <label align="center"><text size="20" vspacing="15" rich="1">Text<br/>Text<br/>Text</text></label>

• hoffset
  Horizontal text offset (in pixels). The default is 0 (no offset).

  

  Source code (XML)

  <label align="center"><text size="20" hoffset="35">Text</text></label>

• voffset
  Vertical text offset (in pixels). The default is 0 (no offset).

  

  Source code (XML)

  <label align="center"><text size="20" hoffset="35" voffset="35">Text</text></label>

• translate
  Whether the text can be translated. The default is 1 (boolean), which means that the text depends on the selected language.

Enables to change font characteristics of widgets and containers. This tag can be applied to a group of widgets or containers. The list of attributes is the same as for the texttag except thetranslate attribute. This attribute should be applied to a text or a label individually (see the example below).

Also the font size can be calculated relatively to its current size. For example:

<font size="+10">Larger</font>
<font size="-4">Smaller</font>
<font size="%200">Same or smaller</font>

The following example demonstrates how to apply the font to the group of widgets:

<vbox>
	<font size="13" rich="1" outline="1">
		<align align="left">
			<label face="fontb.ttf" size="15" color="#ff9900">Labels</label>
			<label translate="1">Label <b>1</b></label><!-- this label can be translated -->
			<label>Label <b>2</b></label>
			<label><font size="17">Label of bigger size</font></label>
			<label>Label <b>4</b></label>
		</align>
	</font>	
</vbox>

Font tags can be nested. However, the following restrictions exist:

• If the nested font tag is applied to a widget or a container, font properties are not inherited.
  Source code (XML)

  <font size="13" rich="1" outline="1">
  	<align align="left">
  		<label face="fontb.ttf" size="15" color="#ff9900">Labels</label>
  		<label>Label <b>1</b></label>
  		<font size="20" rich="1">
  			<label>Label <b>2</b></label>
  		</font>
  	</align>
  </font>

  In the result, Label 2 will not be outlined:

  

• If the font tag is applied to the rich text inside a widget or a container, font properties are inherited.
  Notice

  In this case, the list of font attributes will differ. See the details below.
  Source code (XML)

  <font size="13" rich="1" outline="1">
  	<align align="left">
  		<label>Label <b>1</b></label>
  		<label><font size="17">Label of bigger size</font></label>
  	</align>
  </font>

  In the result, the font characteristics will be inherited:

  

Unlike the align attribute of the texttag, thealign tag can be applied to a group of widgets.

Attributes:

• align
  Acceptable values are center, left, right.

For example:

<align align="right">
	<label><text>Title1</text></label>
	<edittext name="Test::edittext_1" export="1" width="100" height="100">
		<text>EditLine1</text>
	</edittext>
	<label><text>Title2</text></label>
	<edittext name="Test::edittext_2" export="1" width="100" height="100">
		<text>EditLine2</text>
	</edittext>
</align>

If the rich attribute of the textorfonttag is equal to1, yes or true, the following tags and entities can be used to format the text inside them:

br

<text rich="1">Text 1 <br/>
Text 2<br>Text 3</text>

p

center

font

<label>
	<text rich="1">
		<font size="20" color="#ff0000">A big red text</font> and a text of the default style.<br/>
		<font face="fontb.ttf" size="20">You can also change the font face.</font><br/>
		<font color="#00ff00">Here is a green text with a <font size="10">small tail.</font></font>
	</text>
</label>

sub

<text size="20" rich="1">Text <sub>Subscript text</sub></text>

sup

<text size="20" rich="1">Text <sup>Superscript text</sup></text>

i

b

bi

table

<text size="20" rich="1">
	<table space="10" color="#ffffff">
		<tr height="45">
			<td>Row 0 Column 0</td>
			<td>Row 0 Column 1</td>
		</tr>
		<tr height="45">
			<td>Row 1 Column 0</td>
			<td>Row 1 Column 1</td>
		</tr>
	</table>
</text>

xy

<text size="20" rich="1"><xy x="12" y="24"/>Text</text>

<text rich="1" size="20">
	This is a <xy x="%50" y="%100"/>long text
</text>

image

<text rich="1" size="15">
	Image with a long description: <image src="brush_square.png" x="%100" y="%100"/>
</text>

right

<text rich="1">Text<right/>Text</text>

>

<

&

"

'