Skip to main content Link Menu Expand (external link) Document Search Copy Copied

NeedleGauge

This example NeedleGauge implements a tachometer using the ‘rpm’ attribute.

<gauge>
    <name>tachogauge</name>
    <type>NeedleGauge</type>
    <x>1160</x>
    <y>60</y>
    <radius>226</radius>
    <min>0</min>
    <max>8000</max>
    <initial>0</initial>
    <attribute>rpm</attribute>
    <colours>red</colours>
    <background>tvrtach600.bmp</background>
    <nightbackground loadondemand="1">tvrtach600night.bmp</nightbackground>
    <visible>1</visible>
    <units>rpm</units>
    <needle>1</needle>
    <needlefile>tvrneedle1920black.bmp</needlefile>
    <needletail>100</needletail>
    <arcalpha>125</arcalpha>
    <arc>0</arc>
    <arcstroke>38</arcstroke>
    <zorder>1</zorder>
    <smoothing>0.2</smoothing>
</gauge>

Note that where image names are specified, no folder name is used. All images are stored in a folder, c:\media, on the SD card. However, See the image vault section for a higher performance method of loading images.

Attribute Mandatory? Value Type Description
x Yes Integer The x coordinate of the bottom left of the gauge
y Yes Integer The y coordinate of the bottom left of the gauge
radius Yes Integer The basic radius of the gauge. This is used to draw a vector based needle if no needle image is defined
min Yes Integer The minimum value of the gauge
max Yes Integer The maximum value of the gauge
initial Yes Integer The value the gauge should display if no input is received
attribute Yes String The name of the attribute the gauge is to be based on
colours Yes String The base colour definition of the gauge. This is the colour used to draw any vector graphics such as a vector based needle. When a NeedleGauge is properly designed, this colour is not used.
visible No Integer (0 or 1) Defines whether the gauge should be displayed or not when the page is first drawn
units Yes String The units to be used on the gauge. Currently must be specified but may not actually be used.
needle No Integer (0 or 1) Indicates whether a needle should be drawn or not
needlefile No String Filename of a bitmap file to be used to render the needle. If no file is supplied, a vector version of the needle will be drawn using the defined radius.
needletail No String  
arc No Integer 1 or 0 Defines whether a coloured arc should be drawn between the start angle and the current needle position. If not specified, defaults to off (0)
arcstroke No Integer The line width of the arc to be drawn if enabled
arcalpha No Integer 0 to 255 The alpha (opacity) of the arc being drawn if enabled. 255 is solid. 0 is totally transparent (you won’t see anything at all!
needleydelta No Integer Offset in the Y direction of the pivot point of the needle. If not specified, the pivot will be calculated to be in the centre of the gauge as defined by the gauge dimensions
needlexdelta No Integer Offset in the X direction of the pivot point of the needle
zeroangle No Integer. Default 225 The angle of the zero point on the gauge. 0 degrees would be 3 o’clock if you were looking at a clock face. 270 degrees would be 6 o’clock
rangedegrees No Integer. Default 270 The range in degrees the needle should sweep between the minimum and maximum values
background No, but recommended String The filename of the background image to be used to draw the gauge’s clock. If not specified, nothing will be drawn but the needle. This gauge has an optional ‘loadondemand’ specifier (see example above), which if specified means the background image won’t be loaded from disk until it is needed. In a complex cluster definition this can save a bit of initial boot time as fewer resources need to be loaded before the startup cluster can be displayed
nightbackground No String The filename of the background image to be used for the gauge when the system is in ‘night’ mode. Typically such an image should have less bright colours (on my own car I simulated the glow of the backlit dials). This setting also supports the ‘loadondemand’ specifier. It is intended to help in scenarios where the screen cannot be dimmed.
delta No Integer Default 0. Enables the value used by the gauge to be offset by a set amount. For example, coolant temperature values from the ECU are offset by 40 degrees to enable a more sensible temperature range. Setting delta to -40 will provide a correct temperature reading from the 0 to 255 range of the value sent by the ECU
xscale No Floating point Scale the entire gauge in the X direction
yscale No Floating point Scale the entire gauge in the Y direction
outlinethickness No Integer, default 0 For a nonzero value, causes the system to draw a circle on the area used by the gauge as defined by its width and height. The line width used will be the specified outline thickness.
w Yes Integer Width in pixels the gauge will take up. Not actually used to reserve space, so can be set to something approximate.
h Yes Integer Height in pixels the gauge will take up. Not actually used to reserve space, so can be set to something approximate.
colours_script No String Pascalscript definition of a standardised function which can set the colour of the gauge based on a script. Although this setting is supported on the Needle Gauge, it is more relevant for other gauges such as bar charts or values.
gradienttype No String. Valid values radial, conical, none. This specifies if a colour gradient is to be used when drawing an arc.
smoothing No Floating point, default value 0.0 (no smoothing) This setting provides some damping for the gauge and helps to smooth out the flow of the needle between the values being received from the ECU. The more damping you add (bigger smoothing number), the more lag you add to the needle. A sensible smoothing number for a tachometer is about 0.2, and for a speedometer about 0.08. If no smoothing is set, the needle will always reflect the current value received from the ECU. In the case of, say, RPM, this will make the needle slightly jumpy. For certain gauges such as coolant temperature, you don’t want any smoothing at all.
needledirection No Integer, 0 or 1 Default 0. This defines whether the needle should travel in the clockwise direction (0) or anticlockwise direction (1).
mindrawvalue No Integer If the current value of the attribute the gauge is based on is less than the value supplied here, then the needle and/or arc won’t be drawn.