Shedsoft

The Controls

There are five types of controls with which you can build dashboards in iRDDU2:

Number Used to display formatted numbers.
Text For text strings; names, headings, labels etc.
Gauge A rotating picture. Used for analogue gauges mostly.
Bitmap A graphical image.
Group A way of grouping controls together to build more complex controls.

With these five building blocks you can make pretty well any kind of dashboard. To add one to your dashboard drag the appropriate icon to the place you want it to appear and let go. A new control will be added to the dropdown containing a set of reasonable default properties which will almost certainly be quite unlike anything you want them to be. You will therefore need to change them.

Anything you change in the properties panel to the right forces the dash to be redrawn. In actual fact most things force it to be completely reloaded which can take a while if it’s a complex dash with a lot of controls. That’s something I need to optimise for a later release but for now please be patient.

People moving from iRDDU 1.3 will notice that the RevBar control has gone.  Essentially it was a bit too specialised for it's own good and with iRDDU2's group and scripting features you don't need it any more.  There is an example of a rev bar group file in the Components dashboard download.

I’ll deal with what the properties actually do for each control in turn.

The Text Control

The Text control is the simplest to understand and forms the basis of all the character based controls so I’ll deal with it first.

All controls have a number of parameters in common, these are located in the top section of the Properties panel under “Basic Settings”.

Dimensions we’ve already covered and Formula and Script are big enough to warrant their own sections. The others are (in order of importance):

Name:    The name of the control which must be unique within each dashboard. It’s used by iRDDU to identify the control in the selection dropdown as well as when referring to it’s value from formulae and scripts on other controls. The editor will not let you change a control’s name to be the same as an existing control.

Control Type:    This is read only; you can’t change the type of a control.

Active:    Set this to false and the control will be ignored by iRDDU. It’s value will not be updated, it will not be drawn and any scripts attached will not be executed. This may seem pointless but when we look at scripting it’s usefulness will become clearer.

Visible:    Determines whether the control will be displayed on each update of the dashboard. The control will still have it’s value updated if this is set to false, it just won’t be actually displayed. Sometimes you just want a control as a variable to hold a value but not display it, this allows you to do that. Alternatively you might only want to display a value under certain conditions; perhaps the car’s speed in relation to the pit limit but only when the car is in the pitlane. Again, once we start to look at scripts you’ll see many ways to use it.

Flash Period:    You can make a control flash on and off at a regular rate. The period is a value in seconds between states so if you want the control to flash on and off once a second you would set it to 0.5 (0.5 seconds on then 0.5 off). The refresh rate of the dashboard is critical to the smoothness of the flashing. iRDDU can only change the control’s state during an update so you need to have it set faster than the flash rate to work at all and a lot faster to have a chance of flashing smoothly.

The control specific properties under “Text Settings” allow you to customise the way the text will appear.

Text Colour:    An RGB value defining the colour to draw the text. If you click on the property then a dropdown button will appear to the right. Click this button and a colour selection panel will appear.

Text Font:    Which font to use when drawing the text. Clicking on the arrowhead to the left of the property will expand the field and show various font attributes – ignore them. I will activate the other attributes in a future release but for now the only thing the editor takes any notice of is the font name, everything else is ignored. Similarly to the colour, clicking on the Name activates a font selection list.

The size of the font used is calculated automatically by iRDDU from the height of the control.

Options:    The options field holds extra formatting information not covered by the other properties. To specify the option just enter the appropriate character into the field; you can enter as many or as few options as you like. The available values are:

  • B Bold.
  • I Italic
  • < Left Align
  • > Right Align
  • V Centre Align

If no options are specified the defaults are No Bold, No Italic, Centre Align.

The Number Control

The Number control is a specialised version of the Text control. The basic settings along with Font, Colour and Options are identical but there are two extra properties that it’s well worth taking the time to understand.

Output Unit:    This one parameter goes to the core of what iRDDU2 is about in that I’ve tried to do as much automatically as I can. It consists of a dropdown containing every unit of measure iRDDU supports. To convert the value to a specific measure, just select it from the list and iRDDU will in most cases do the conversion for you.

For example, say you use the [SIM|Speed] field to get the speed of your car from the API and you want to display it in MPH. The iRacing API delivers the car’s speed in metres per second but if you set the Output Unit to MPH iRDDU does the conversion.

Format Mask:    The Formatting Mask tells iRDDU how to display the control’s value. Number controls in iRDDU are designed to handle many types of numeric data. In addition to numbers they can hold dates, times and laptimes.

The Number control doesn’t only display numbers, it’s also designed for dates, times and laptimes. iRDDU uses the Output Unit to determine which type of format string to use. Ignoring the special cases for the moment, the majority of number controls will need formatting as pure numbers so I’ll deal with them first.

To anyone who’s done some C# programming the following will require little explanation but for everyone else a few examples should suffice to get you started. Imagine the value to be displayed by the control is 123.45678 and we want to format it as a number. These values of Formatting Mask would result in the following output:

0 123(default)
0.000 123.457
00000 00123
0000.0000 0123.4568
#,#.00 1,234.46
#.######## 123.45678

The above – The above - with a little modification - should cover most of the ways you are likely to want to format numbers in iRDDU but if not then have a look at this - http://msdn.microsoft.com/en-us/library/0c899ak8(v=vs.100).aspx. It’s one of those things that initially looks scary but in reality isn’t.

Laptimes are stored internally as a number of seconds. If the Output Unit is set to Second then iRDDU expects a timespan format string. The following examples assume a value of 83.456 (1:23.456):

m\:ss\.fff 1:23.456 (default)
s\.fff 83.456
#,#.00 1,234.46
#.######## 123.45678

There aren’t too many ways to format a laptime and the above probably covers them but if you’re feeling creative you can get the full rundown as http://msdn.microsoft.com/en-us/library/ee372286(v=vs.100).aspx.

The final special formatting case is for dates and times. Let’s say the time is 8:15:50 on the 17th April 2014:

dd MMM yyyy h\:mm\:ss 17 Apr 2014 8:15:50 (default)
dd/MM/yyyy 17/04/2014
HH\:mm\:ss 08:15:50
hh\:mm\:ss 16:15:50

And here’s the full reference. http://msdn.microsoft.com/en-us/library/8kb3ddd4%28v=vs.110%29.aspx.

The Bitmap Control

The bitmap control draws a picture on the dash. The value it is fed needs to be a reference to a bitmap file. You can specify a bitmap file using the BMP field prefix.

I’ll cover field prefixes in more detail in the API Fields and Formulae section but in essence they tell iRDDU where to get the data from. The BMP prefix tells iRDDU to look for a bitmap file with the specified name. For example if I put [BMP|GreenFlag.PNG] in the Formula property. When updating the value of the control iRDDU first looks for a file called GreenFlag.PNG in the dashboard’s folder. If it doesn't find one it will look in the iRDDU2\Components folder.  Finally it will look for the file in it's internal graphic store where a number of basic bitmaps such as Needles and LED lights are stored.

Static bitmaps are all very well but this control is really designed to allow you to create dynamic bitmaps like rev bars and warning lights.  The way you do that is to use one of iRDDU's built in functions; the IF function.  This works the same as the IF function in Microsoft Excel and returns one of two values if the supplied condition is true:

IF( condition , value if true , value if false )

As usual an example shows it best.  Let's create a shift light which comes on when the engine is running over 5600 RPM:

IF( [SIM|RPM] > 5600 , [BMP|RedLED.png] , [BMP|Blank] )

Each time the dashboard is updated iRDDU gets the value of the RPM field from iRacing.  If it is greater than 5600 it sets the value of the control to be the bitmap in RedLED.png, otherwise it leaves it blank.  Hey Presto, the light comes on when you're at the red line.  Job's a good'n. :o)

It's more efficient when designing dashboards with indicator lights to put the "off" version of the light on the background graphic and overlay it with the "on" version.  Of course you don't have to limit this sort of thing to a Bitmap control, you could just as easily use it to display different values in a  number or text field.

You can get as complex as you like nesting if statements within if statements.  I'd suggest that if you're getting past 2 or 3 nested IFs in one formula that a script would be a better option.  I cover scripts in their own section.

The Gauge Control

The Bitmap control draws a static picture.  The Gauge does the same thing but allows you to rotate it.  The properties are designed to make it easy to control the needle on an analogue gauge but with a little imagination you could make a yaw gauge, reflections that move with the direction of the car, a compass, whatever you like.

The best way to get to grips with it is to play with it.

Gauge Needle:    A bitmap file containing the thing you want to rotate, usually a needle.

Remember that when iRDDU rotates the bitmap it does it around the centre point and there needs to be room for it to rotate without going off the side.  in other words use symmetrical bitmaps with the pivot point in the middle.

Gauge Minimum:    The lowest value you are expecting the control to receive.  For example for a rev counter or speedometer this would be zero but for a G meter it might be -5.

Gauge Maximum:    The highest value you are expecting the control to receive.  You weren't expecting that were you?  This will usually be the highest value the gauge can handle so on a speedo it might be 180.

Gauge Range:    This is the key one, it tells iRDDU how far to rotate between Gauge Minimum and Gauge Maximum.  Another way of putting it would be that this defines the sweep of the needle.

It's measured in degrees so 270 means the needle will travel three quarters of the way round between min and max.  180 would result in a gauge with a sweep of only half a circle.

An important point to note is that you can make the needle rotate in either direction.  The default is clockwise but if you want the needle to rotate anticlockwise, make the Gauge Range negative.

Start Angle:    Start Angle allows you to move the zero point of the gauge.  By default 0 degrees is straight down.If you wanted it to be straight left you could set Start Angle to 90 (90 degrees round from straight down).  To move it anticlockwise make it negative; -45 would set the zero point to be halfway between 4 and 5 on a clock.

There's no reason why it should be limited to a single rotation.  Say you were designing a graphic to show the steering wheel position, your wheel has three turns lock to lock and iRacing returns a value between -1 and +1 to signify the steering position.  You would set the gauge minimum to -1, the gauge maximum to 1, the Gauge Range to 1080 and the Start Angle to -540.

The Group Control

The final control type is the group control.  iRDDU2 allows you to group sets of controls together in a separate file.  This allows you to create complex controls like an entire gauge or a rev bar and use it in a number of different dashboards.

To get you started I've made a few examples.  Download the components pack for "Get Dashes" and add a Group control to a dashboard.  Set the width and height to 121 and enter G_Meter_121x121.icg into the File parameter.

A cross hair and circle will appear with a blue dot in the centre.  It's a G Meter, it'll show lateral and longitudinal G in real time while you're driving.

That's a really simple one, you can make it more complex.  Each group file can be sent up to four parameters, two numbers and two text strings.  This enables you to create generic group files which display different data.  For example, you could create a generic gauge control which uses the value in [SIM|Number1] to determine the value and [SIM|Text1] to pass a label; RPM, OIL, WATER etc.