Widgets

Many widgets have specific parameters, however, they all share a set of common parameters.

Besides, all widgets can have the following children.

tooltip

<button>
	<tooltip>Button <br/>to press</tooltip>
	<text size="20">Press</text>
</button>
					

attach

<editline name="editline"/>
<hslider min="0" max="3000">
	<attach multiplier="1000" flags="log10,max_expand">editline</attach>
</hslider>

callback

<button>
	<callback type="clicked" accel_key="n" accel_ctrl="1">ctrl_n_clicked</callback>
</button>

Corresponds to an object of the WidgetButton class.

Parameters:

• background
  Whether to render button background or not. The default is 1 (boolean).
• toggleable
  Whether the widget is a toggle button or an ordinary one. The default is 0 (boolean).
• toggled
  Whether the toggle button is pressed by default or not. The default is 0 (boolean).
• texture
  Path to a button image texture.

Children:

• text
  Text displayed on the button. Acceptable parameters:
  • align with values center, left, right.

<button name="Test::button" export="1">
	<text>Button</text>
</button>
<button name="Test::toggle_button" export="1" toggleable="1" toggled="1">
	<text>Toggle button</text>
</button>

To add a button without background, set the background parameter to 0:

<button name="Test::button1" export="1" texture="button_texture.png">
	<text>Button1</text>
</button>
<button name="Test::button2" export="1" background="0">
	<text>Button2</text>
</button>
				

Corresponds to an object of the WidgetCanvas class.

After a canvas widget was created, it can be used to draw polygons (either textured or not), lines and text in the script. The canvas can be used to create different trackers, charts, tables, etc.

Parameters:

• texture
  Background texture to be drawn across the canvas

<canvas name="Test::canvas" export="1" texture="canvas/canvas.png"/>

To create a simple canvas, define the canvas tag in your UI file as follows:

<window name="Test::window" export="1" width="350" height="270" sizeable="1" enabled="1">
	<text>Window Title</text>
	<label><text size="15">This is a simple canvas example:</text></label>
	<canvas name="Test::canvas" export="1" align="center" width="250" height="180"/>
</window>
				

class Test {

	WidgetWindow window;
	WidgetCanvas canvas;
	
	Test() {
		ui = engine.gui.addUserInterface(engine.getGui(),"canvas.ui");	
	}
	
	int show(int x,int y)() {
		Gui gui = engine.getGui();
		
		// add the window widget and its children to the GUI
		gui.addChild(window,GUI_ALIGN_CENTER);
		window.setPosition(x,y);
		
		// draw polygons
		int id = canvas.addPolygon();
		canvas.setPolygonColor(id,vec4(0.8f,0.4f,0.0f,1.0f));
		canvas.setPolygonTransform(id,translate(130.0f,64.0f,0.0f));
		forloop(int i = 0; 7) {
			float angle = PI2 * i / 6;
			canvas.addPolygonPoint(id,vec3(sin(angle),cos(angle),0.0f) * 64.0f);
		}
		
		// draw lines
		id = canvas.addLine();
		canvas.setLineColor(id,vec4(0.0f,0.0f,0.0f,1.0f));
		canvas.setLineTransform(id,translate(128.0f,64.0f,0.0f));
		forloop(int i = 0; 6) {
			float angle = PI2 * i * 1 / 3;
			canvas.addLinePoint(id,vec3(sin(angle),cos(angle),0.0f) * 48.0f);
		}
	}
}

int init(){
	Window window_0 = new Window();
	window_0.show(150,150);
	
	return 1;
}
				

Corresponds to an object of the WidgetCheckBox class.

Parameters:

• checked
  Whether the checkbox is selected by default or not. The default is 0 (boolean).

Children:

• text
  Text label.
• attach
  First checkbox widget of a radio button group.

<checkbox name="Test::checkbox0" export="1">
	<text>Checkbox 0</text>
</checkbox>
<checkbox name="Test::checkbox1" export="1" checked="1">
	<text>Checkbox 1</text>
</checkbox>

To create a radio button group, use the attach child:

<checkbox name="Test::radiobutton0" export="1" checked="1">
	<text>Variant 0</text>
</checkbox>
<checkbox name="Test::radiobutton1" export="1">
	<attach>Test::radiobutton0</attach>
	<text>Variant 1</text>
</checkbox>

Corresponds to an object of the WidgetComboBox class.

Parameters:

• texture
  Path to a texture with mini-icons. This texture is a strip of N pixels in width and N*M pixels in height.

Children:

• text
  Text of a list item. Multiple items are supported, the default item is the first one. Acceptable parameters:
  • texture, which sets the ID of a mini-icon to be used for the item starting from zero.

<combobox name="Test::combobox" export="1">
	<text>item 0</text>
	<text>item 1</text>
	<text>item 2</text>
	<text>item 3</text>
</combobox>

To set a mini-icon for each item, use the texture parameter as follows:

<combobox name="Test::combobox" export="1" texture="combobox_icons.png">
	<text texture="0">item 0</text>
	<text texture="1">item 1</text>
	<text texture="2">item 2</text>
	<text texture="3">item 3</text>
</combobox>
				

The combobox_icons.png image is a vertical strip of square (16×16 pixels) mini-icons that have a transparent background:

See the article on Skin Layout for more details.

Corresponds to an object of the WidgetEditLine class.

Parameters:

• editable
  Whether to allow modifying the text or not. The default is 1 (boolean).
• password
  Whether the text should be displayed as dots. The default is 0 (boolean).
• background
  Whether the widget has a background or not. The default is 1 (boolean).
• capacity
  Maximum number of characters that can be entered (integer).
• validator
  Value validator, acceptable types are any, int, uint, float or ascii.
• color
  Text color. Changes the text color only if the text tag is not specified as a child. If the child tag is specified, this parameter won't affect the text color.

Children:

• text
  The initial string.

<editline name="Test::editline" export="1" width="100" capacity="10">
	<text>EditLine</text>
</editline>

The following example shows possible ways of using the editline widget:

<hbox align="expand">
	<editline align="expand" validator="int"/>
	<button width="30">
		<text>Button1</text>
	</button>
</hbox>
<hbox align="expand">
	<editline align="expand" password="1"/>
	<button width="30">
		<text>Button2</text>
	</button>
</hbox>
<hbox align="expand">
	<editline align="expand" validator="any" background="0" color="#3300CC"/>
	<button width="30">
		<text>Button1</text>
	</button>
</hbox>
				

Corresponds to an object of the WidgetEditText class.

Parameters:

• editable
  Whether to allow modifying the text or not. The default is 1 (boolean).
• background
  Whether the widget has a background or not. The default is 1 (boolean).
• color
  Text color. Changes the text color only if the text tag is not specified as a child. If the child tag is specified, this parameter won't affect the text color.

Children:

• text
  The initial string.

<edittext name="Test::edittext" export="1" width="100" height="100">
	<text>EditLine
	Multiline</text>
</edittext>

The edittext widget can be used, for example, to input some source code:

<hbox align="expand">
	<label align="left,top">Source:</label>
	<edittext name="Test::edittext" export="1" align="expand"/>
</hbox>
				

If the text scrolling is required, define the edittext widget inside the scrollbox container:

<scrollbox name="Test::scrollbox" align="expand">
	<edittext name="Test::edittext" export="1" align="expand"/>
</scrollbox>	
				

Corresponds to an object of the WidgetScroll class.

Parameters:

• object
  Width of the area to scroll (in pixels). The default is 100.
• frame
  Width of the visible frame (in pixels). The default is 10.
• step
  Number of pixels to scroll, when the user clicks one of the arrows. The default is 1.
• value
  Initial position of the scroller. Cannot exceed object-frame pixels.

<hscroll name="Test::hscroll" export="1" width="100"/>

Corresponds to an object of the WidgetSlider class.

Parameters:

• min
  Minimum value (integer).
• max
  Maximum value (integer).
• value
  Initial value (integer).
• button_width
  Width of the handle.

Children:

• attach
  Widget name, which will display the current value. Acceptable parameters: format (takes a format string), multiplier (int), and flags (string). Note that multiplier divides the current value.

<hslider name="Test::hslider" export="1" align="expand" min="500" max="3500" value="1000" width="100" button_width="30">
	<attach format=" %.1f" multiplier="1000">hslider_label</attach>
</hslider>
<label name="hslider_label" width="28"/>

It is possible to combine several horizontal sliders by using one of the containers. For example:

<hbox space_x="10">
	<vbox space_y="20">
		<hslider name="Test::hslider_1" export="1" min="0" max="10" value="0" width="100" button_width="30">
			<attach format="%.1f" multiplier="10">hslider_option_1</attach>
		</hslider>
		<hslider name="Test::hslider_2" export="1" min="0" max="10" value="0" width="100" button_width="30">
			<attach format="%.1f" multiplier="10">hslider_option_2</attach>
		</hslider>
		<hslider name="Test::hslider_3" export="1" min="0" max="10" value="0" width="100" button_width="30">
			<attach format="%.1f" multiplier="10">hslider_option_3</attach>
		</hslider>
	</vbox>
	<vbox space_y="20">
		<label name="hslider_option_1"/>
		<label name="hslider_option_2"/>
		<label name="hslider_option_3"/>
	</vbox>
</hbox>
				

Corresponds to an object of the WidgetSpacer class.

Parameters:

• Width
  Separator width.

<hspacer width="50"/>

The hspacer widget can be used to group the other widgets. For example:

<vbox>
	<gridbox name="Test::gridbox_1" space="10">
		<label><text>Label 0</text></label>
		<label><text>Label 1</text></label>
		<label><text>Label 2</text></label>
		<label><text>Label 3</text></label>
	</gridbox>
	<hspacer width="50"/>
	<gridbox name="Test::gridbox_2" space="10">
		<label><text>Label 0</text></label>
		<label><text>Label 1</text></label>
		<label><text>Label 2</text></label>
		<label><text>Label 3</text></label>
	</gridbox>
</vbox>
				

Corresponds to an object of the WidgetIcon class.

It is a square image, whose size is divisible by 2. For example, 16×16, 32×32, 64×64. Each icon has 4 states. For more details, see the article on Skin Layout.

Parameters:

• toggleable
  Whether the widget is a toggle button or an ordinary one. The default is 0 (boolean).
• toggled
  Whether the icon serving as a toggle button is pressed by default or not. The default is 0 (boolean).
• texture
  Path to an icon image.

Children:

• text
  The icon capture. The acceptable values are left, right, center.

<icon name="Test::icon_1" export="1" texture="icons/icon_1.png" toggleable="1"/>
<icon name="Test::icon_2" export="1" texture="icons/icon_2.png"/>
<icon name="Test::icon_3" export="1" texture="icons/icon_3.png" toggleable="1" toggled="1"/>
<icon name="Test::icon_4" export="1" texture="icons/icon_4.png" toggleable="1"/>

To add an image caption, use the text tag with the required set of parameters:

<icon name="Test::icon_1" export="1" texture="icon.png">
	<text voffset="25" size="15">Icon Caption</text>
</icon>
				

The following example demonstrates icons of different size and sets of parameters:

<gridbox name="Test::gridbox" space_y="10">
	<label>
		<text>16×16 icons:</text>
	</label>
	<hbox name="Test::hbox_1">
		<icon name="Test::icon_1" export="1" texture="icon_1.png" toggleable="1"/>
		<icon name="Test::icon_2" export="1" texture="icon_2.png"/>
	</hbox>
	<label>
		<text>32×32 icons:</text>
	</label>
	<hbox name="Test::hbox_2">
		<icon name="Test::icon_3" export="1" texture="icon_3.png"/>
		<icon name="Test::icon_4" export="1" texture="icon_4.png" toggleable="1" toggled="1"/>
	</hbox>		
</gridbox>
				

Each icon represented by the image that includes 4 states of the icon. For example:

4 states of the 16×16 square icon	4 states of the 32×32 square icon

Corresponds to an object of the WidgetLabel class.

The label widget can have any of the common parameters.

Children:

• text
  Label text.

<label>
	<text>Label</text>
</label>

It is possible to change the width and height of the label, its alignment or position. The label text can be changed by using the text parameters. For example:

<label align="left">
	<text color="#3300CC">Label 0</text>
</label>
<label align="right">
	<text size="15">Label 1</text>
</label>
<label pos_x="30" pos_y="80" align="overlap">
	<text size="20">Label 2</text>
</label>
<label>
	<text size="25" color="#FF6600">Label 3</text>
</label>
				

If the text formatting is not required, the text tag can be omitted:

<label>Label</label>
				

Corresponds to an object of the WidgetListBox class.

Parameters:

• multi_selection
  Whether to allow picking more than one item or not. CTRL and SHIFT modifiers are used for multiple selection.
• texture
  Path to a listbox texture of mini-icons. This texture is a bar of N pixels in width and N*M pixels in height.

Children:

• text
  Text of a list item. Multiple items are supported. Acceptable parameters:
  • texture
    Sets the ID of a mini-icon to be used for the item starting from zero.

<listbox multi_selection="1">
	<text>item 0</text>
	<text>item 1</text>
	<text>item 2</text>
	<text>item 3</text>
	<text>item 4</text>
	<text>item 5</text>
</listbox>

To add an icon for each list item, use the texture parameter as follows:

<listbox texture="menu_icons.png">
	<text texture="0">item 0</text>
	<text texture="1">item 1</text>
	<text texture="2">item 2</text>
	<text>item 3</text>
</listbox>
				

The menu_icons.png image is a vertical strip of square mini-icons, each the size of 16×16 pixels, that has a transparent background:

See the article on Skin Layout for more details.

Corresponds to an object of the WidgetMenuBar class.

Children:

• menu
  A single menu.
  May contain the following children describing a menu:
  • text
    Menu title. Acceptable parameters:
    • translate
      Whether the text can be translated (boolean).
    Notice

    You can use the text tag only with the translate parameter. The other parameters described for text are not accepted.
  • menubox
    Menu itself.

<hbox background="1" space="5">
	<menubar align="expand">
		<menu>
			<text>File</text>
			<menubox name="Test::file_mb">
				…
			</menubox>
		</menu>
		<menu>
			<text>Edit</text>
			<menubox name="Test::edit_mb">
				…
			</menubox>
		</menu>
		<menu>
			<text>Help</text>
			<menubox name="Test::help_mb">
				…
			</menubox>
		</menu>
	</menubar>
</hbox>
				

All of the common parameters can be be used for the menubar. For example:

<menubar name="Test::menubar" align="right">
	<menu>
		<text>File</text>
		<menubox name="Test::file" texture="menubox_icons.png" align="left">
			<text separator="1">Menu Item 0</text>
			<text enabled="0" texture="0">Menu Item 1</text>
			<text texture="1">Menu Item 2</text>
			<text texture="2">Menu Item 3</text>
			<text texture="3">Menu Item 4</text>
		</menubox>
	</menu>
	<menu enabled="0">
		<text>Edit</text>
		<menubox name="Test::edit">
			<text>Menu Item 0</text>
		</menubox>
	</menu>
</menubar>
				

Corresponds to an object of the WidgetMenuBox class.

Parameters:

• texture
  Path to a menubox texture of mini-icons. This texture is a strip of N pixels in width and N*M pixels in height.
• space
  Overall spacing (pixels).
• space_x
  Horizontal spacing (pixels).
• space_y
  Vertical spacing (pixels).

Children:

• text
  Text of a menu item. Multiple items are supported. Acceptable parameters:
  • texture
    Sets the ID of a mini-icon to be used for the item starting from zero.
  • separator (boolean)
    Specifies whether the item is followed by a separator.
  • enabled (boolean)
    Specifies whether the item can be selected.

<menubox space="8">
	<text separator="1">Menu Item 0</text>
	<text enabled="0">Menu Item 1</text>
	<text>Menu Item 2</text>
</menubox>

To add icon for each item, use the texture parameter as follows:

<menubox space="8" texture="menu_icons.png">
	<text separator="1">Menu Item 0</text>
	<text enabled="0" texture="0">Menu Item 1</text>
	<text texture="1">Menu Item 2</text>
	<text texture="2">Menu Item 3</text>
	<text texture="3">Menu Item 4</text>
</menubox>
				

The menu_icons.png image is a vertical strip of square mini-icons, each the size of 16×16 pixels, that has a transparent background:

See the article on Skin Layout for more details.

Corresponds to an object of the WidgetSpinBox class.

Parameters:

• min
  Minimum value (integer).
• max
  Maximum value (integer).
• value
  Initial value (integer).

Children:

• attach
  Widget name, which will display the current value. Acceptable parameters:
  • format (takes a format string)
  • multiplier (float)
  • flags (string)

<hbox>
	<editline name="editline">
		<text>11</text>
	</editline>
	<spinbox max="100" min="10" value="11" align="overlap">
		<attach>editline</attach>
	</spinbox>
</hbox>

All of the common parameters are acceptable. For example, you can enable the spinbox:

<spinbox max="100" min="10" value="11" align="overlap" enabled="0">
	<attach>editline</attach>
</spinbox>
				

Corresponds to an object of the WidgetSprite class.

Sprite is an image composed of several layers that can be assigned textures, scaled, translated and colored.

Parameters:

• color
  Modulation color of the first layer.
• texture
  Path to a texture of the first layer.
• scale
  Scale factor for the first layer.
• scale_x
  Scale factor for the first layer (by x).
• scale_y
  Scale factor for the first layer (by y).
• translate
  Offset for the first layer.
• translate_x
  Offset for the first layer (by x).
• translate_y
  Offset for the first layer (by y).
• texcoord_x
  The X coordinate of the upper left corner of the texture for the first (bottom) layer of the sprite.
• texcoord_y
  The Y coordinate of the upper left corner of the texture for the first (bottom) layer of the sprite.
• texcoord_z
  The X coordinate of the lower right corner of the texture for the first (bottom) layer of the sprite.
• texcoord_w
  The Y coordinate of the lower right corner of the texture for the first (bottom) layer of the sprite.

Children:

• layer
  A 2D layer, additional to the default (first) layer. Multiple layers are supported. Acceptable parameters:
  • color
    Modulation color.
  • texture
    Path to the texture of the layer.
  • scale
    Overall scale factor (float).
  • scale_x
    Horizontal scale factor (float).
  • scale_y
    Vertical scale factor (float).
  • translate
    Overall layer offset (float).
  • translate_x
    Horizontal layer offset (float).
  • translate_y
    Vertical layer offset float).

<sprite name="Test::sprite" export="1" color="#ff0000" texture="sprites/layer0.png" scale="0.5">
	<layer color="#00ff00" texture="sprites/layer1.png" scale_x="0.8"/>
</sprite>

Corresponds to an object of the WidgetTreeBox class.

Parameters:

• editable
  Whether to allow modifying the hierarchy of items or not. The hierarchy can be modified by dragging items with ALT pressed.
• multi_selection
  Whether to allow picking more than one item or not. CTRL and SHIFT modifiers are used for multiple selection.
• texture
  Path to a treebox texture of mini-icons. This texture is a bar of N pixels in width and N*M pixels in height.

Children:

• text
  Text of a list item. Multiple items are supported. Acceptable parameters:
  • texture
    Sets the ID of a mini-icon to be used for the item starting from zero.

<treebox name="Test::treebox" editable="1" multi_selection="1" texture="menu_icons.png">
	<text texture="0">item 0</text>
	<text texture="1">item 1</text>
	<text texture="2">item 2</text>
	<text texture="3">item 3</text>
	<text>item 4</text>
	<text>item 5</text>
	<text>item 6</text>
</treebox>

The menu_icons.png image is a vertical strip of square mini-icons, each the size of 16×16 pixels, that has a transparent background:

See the article on Skin Layout for more details.

Corresponds to an object of the WidgetScroll class.

Parameters:

• object
  Height of the area to scroll (in pixels). The default is 100.
• frame
  Height of the visible frame (in pixels). The default is 10.
• step
  Number of pixels to scroll, when the user clicks one of the arrows. The default is 1.
• value
  Initial position of the scroller. Cannot exceed object-frame pixels.

<vscroll name="Test::vscroll" export="1" height="100"/>

Corresponds to an object of the WidgetSlider class.

Parameters:

• min
  Minimum value (integer).
• max
  Maximum value (integer).
• value
  Initial value (integer).
• button_height
  Height of the handle.

Children:

• attach
  Widget name, which will display the current value. Acceptable parameters:
  • format (takes a format string)
  • multiplier (int). It divides the current value
  • flags (string)

<vslider name="Test::vslider" export="1" align="expand" min="0" max="1000" value="500" height="100" button_height="30">
	<attach format="Value: %.1f" multiplier="1000">vslider_label</attach>
</vslider>
<label name="vslider_label" width="70"/>

The vslider widget can be used, for example, to select the option value:

<hbox space_x="30">
	<vslider name="Test::vslider_1" export="1" min="0" max="10" value="0" height="100" button_height="30">
		<attach format="%.1f" multiplier="10">vslider_option_1</attach>
	</vslider>
	<vslider name="Test::vslider_2" export="1" min="0" max="10" value="0" height="100" button_height="30">
		<attach format="%.1f" multiplier="10">vslider_option_2</attach>
	</vslider>
	<vslider name="Test::vslider_3" export="1" min="0" max="10" value="0" height="100" button_height="30">
		<attach format="%.1f" multiplier="10">vslider_option_3</attach>
	</vslider>
</hbox>
<hbox space_x="20">
	<label name="vslider_option_1"/>
	<label name="vslider_option_2"/>
	<label name="vslider_option_3"/>
</hbox>
				

Corresponds to an object of the WidgetSpacer class.

Parameters:

• height
  Separator height.

<vspacer height="50"/>

For example, you can visually group several icons by using the vspacer widget:

<hbox name="Test::hbox">
	<icon name="Test::icon_1" export="1" texture="icon.png"></icon>
	<icon name="Test::icon_2" export="1" texture="icon_3.png"></icon>
	<vspacer height="30"/>
	<icon name="Test::icon_3" export="1" texture="icon_4.png" toggleable="1"></icon>
</hbox>