Creating your own GUI

Languages:

English  • Help us translating

This tutorial should help you creating your own GUI. :)

This works in RoR version 0.38.66 and later.

Fundamental Concepts

• The GUI is described in a Layout file (*.layout). It is an XML file format that defines what controls appear where.
• The Layout Files should be edited by the provided GUI Editor
• The GUI is linked with RoR over "User Data" Strings. These are Strings that can be set-up in the LayoutEditors Widget Properties. A link is a connection between the GUI Elements and RoR game values.

• The controls are separated via Layers, so they can overlap each other in a defined way:

Needles should go on top (Main Layer), static background images to the bottom (Back Layer)

Required Software

• Gui Editor 4 (old version: GUI Editor 2)

• NOTE: some animations will not work exactly like in RoR yet. We are working on fixing this.

Workflow

1. Create graphics of gauges and needles

2. Start GUIEditor and create the controls using your graphics

3. Save the .layout and image files in your truck zip and integrate the layout into the TDF.

4. Test in RoR and fix in GUIEditor

Integration into RoR

Add this to your TDF (.truck file) (exchange the layout filename):

guisettings
dashboard your-file.layout

Animations

Animation	Type / Values / Ranges	Load on FPS	Arguments	MyGUI Control to use
anim=rotate Rotates a single image around its center	Float Unlimited Depending on input link Conditions not supported	Light	min - the minimum rotation angle max - the maximum rotation angle vmin - the value at the minimum angle vmax - the value at the maximum angle Example for a simple speedo gauge: anim=rotate min=-104 max=110 vmin=0 vmax=120 link=speedo_kph	RotatingSkin
anim=lamp Switches between two images	Boolean Limited True or false Conditions supported	Light	texture - the basename of the texture to use The resulting images are called <texture>-on.png and <texture>-off.png Example for a simple clutch lamp (images are clutch-on.png and clutch-off.png): anim=lamp texture=clutch link=clutchLamp	ImageBox
anim=series Switches between N images	Integer Limited 1 to N where N is the highest value of the input Conditions not supported	Light	texture - the basename of the texture to use The resulting images are called <texture>-<number>.png Example for a simple secured lamp (images are secured-0.png, secured-1.png and secured-2.png): anim=series texture=secured link=ties_mode	ImageBox
anim=scale Scales one image	Float Unlimited Depending on input link Conditions not supported	Heavier	min - the minimum size to add max - the maximum size to add vmin - the value at the minimum size vmax - the value at the maximum size direction - what side to scale up. possible values: up, down, left, right Example for a simple speedo bar (which is 200 pixels width): anim=scale min=-200 max=0 vmin=0 vmax=120 direction=right link=speedo_kph	ImageBox
anim=translate Moves around one image	Float Unlimited Depending on input link Conditions not supported	Heavier	min - the minimum size to translate max - the maximum size to translate vmin - the value at the minimum translation vmax - the value at the maximum translation direction - what side to move to. possible values: up, down, left, right Example for a simple speedo bar: anim=translate min=0 max=200 vmin=0 vmax=120 direction=right link=speedo_kph	ImageBox
anim=text Displays text	Character Limited 250 characters of text Conditions not supported	Light	format - (optional) the display format that should be used, see here for more info. Example for a simple speedo display: anim=text format=%04.0f km/h link=speedo_kph	TextBox

conditions

Lamps can have conditions on when they switch states. For example this lamp will be "on" for speeds over 50kph:

anim=lamp
texture=clutch
link=speedo_kph>50

Currently there is only support for < and > comparisons

Input Sources

Color code represents the input type

Example files

use this example to view how its done: Dashboard-example.zip

This example also features In-Editor debug (CTRL+T) using a special "DEBUG" Box.

Quickstart

Perhaps the easiest thing to add is a text readout, here we will add a simple readout that shows the speed of a vehicle in MPH.

1. Load up the layout editor and add a TextBox. You can do this by opening the Widgets tab, and under default you will find TextBox. Drag a TextBox out on the canvas as shown:

Click to enlarge

2. Change the properties of the TextBox. Do this in the Properties tab as shown. Align should be to a corner of the screen (Left Top here) and Layer should be "Main." Also add the user data properties:

anim=text
link=speedo_mph

put the keyword (e.g. "anim") into the box above "Key" and put the value (e.g. "text") above the box marked "Value." Then click on "Add" and repeat this step for all the user data properties. In the end you should have these properties for the TextBox:

Click to enlarge

3: Save the layout as "namehere.layout" and put the layout with the vehicle's .truck file.

4: In the .truck file add the following lines:

guisettings
dashboard namehere.layout

5: Test your readout!

Extra: Add these user values to format the display like this: "xxxx.xx MPH"

format=%.2f MPH

Now you have the basics of the layouteditor, move on to more advanced readouts:

Let's now create a simple speedo gauge:

IMPORTANT: Put your graphics into the YourMedia sub folder, so the editor can use it.

1. Open the layout editor.

2. Add an ImageBox in the same way that you added a TextBox in the first part of this quickstart.

3. Go into the ImageBox's properties and put the gauge texture into the ImageTexture field.

4. Add a RotatingSkin widget add your needle texture to it in the same way as you did previously.

5. Add these values to the RotatingSkin as User data:

anim=rotate
min=-104
max=110
vmin=0
vmax=120
link=speedo_kph

6. Save your .layout file, and move it and the images to your truck folder, and add the truck<-->.layout linkage as you did earlier in the quickstart.

7. Test out your gauge, and make modifications as necessary.