★ Gauge Builder ★

Update 1 (Nov 8, 2013):

Note that a little more info is posted on the Gauge Graphics article.

Blog 1 (Mar 16, 2013):

This write-up is a work in progress. Thanks for your patience and for your help with making it complete.

With version 2.6.0 we finished off many of the todo's listed below. Check it out!

Version 1.6 introduced the Gauge Builder. Only one problem - it might be a little tricky to use without any instructions. Don't worry too much though as we will release future app updates to help make things easier.

Well... iiwii (it is what it is) but lucky you found this blog as we'll try and make life a little easier by explaining a few things...

Features that are being considered for a future release include:

  • Image picker. Not all images are yet settable but they sure need to be.Available in 2.6.0
  • Live View. Would be nice to be able to use touches to reposition gauges right from within the Preview view.Available in 2.6.0
  • Reset capability. Ability to revert back to the originally published setting for any gauge option.Available in 2.6.0
  • Gauge order. The first gauge listed ends up being the farthest from your view and gauges after it are successively are drawn on layers over top of each other in an arrangement called a z-order. Being able to change the z-order would be a good idea.Available in 2.6.0
  • Gauge hide/show. If you don't need a particular gauge it would be nice to be able to just hide it completely.Available in 2.6.0
  • Integrated instructions and/or help.Limited availability in 2.6.0
  • Data validation logic so that you are less likely to setup a gauge configuration that is NFG (no f-ing good) out of the gate.

Priority for any of these todo's will be set based on your input. So Tweet or Facebook your requests today!

Introduction

To start, every GaugeFace (skin) has a name, an Orientation a Background and is then configured with a set of Gauges.

  • The orientation, or simply Orient for short, can be Portrait or Landscape. The usable iPhone or iPod touch device screen size is 480 wide x 300 high (Landscape orientation) or 320 wide x 460 high (Portrait orientation). Note that the actual screen size is 20 pix in height higher but that is taken up by the status bar that shows network and GPS connectivity as well as the current time.
  • The Background property lets you (1) set an image that is either sized to match up with the desired screen dimension and will otherwise tile a smaller sized image or (2) set a color or (3) set the background up as a HUD. HUD stands for Heads Up Display and sets up the background to use your camera so that you can setup GaugeFace to see what's coming ahead of you when you attention is momentarily focused elsewhere.
  • Each gauge has a size and position that are collectively known as a Frame (*more info below).

Gauges are classified by a gauge type. A gauge type can be Circular, Linear, Digital or Boolean.

Gauge Types

Type Description
Circular Draws a circular gauge line with tick marks. The gauge line drawn starts at a Start Angle and ends at an End Angle. Tick marks drawn on the circular line, and associated number labels, are calculated and positioned by knowing Start Value, End Value, Major Increment and Minor Increment values. Circular gauges should have a Needle Image to point to the current value for that gauge.
Linear Draws a linear gauge line (vertical or horizontal) with tick marks. Tick marks drawn on a linear gauge line, and associated number labels, are calculated and positioned by knowing Start Value, End Value, Major Increment and Minor Increment values. Linear gauges should have a Needle Image to point to the current value for that gauge.
Digital This one is easy. No lines or ticks to worry about.
Boolean Also pretty easy but applies to things that go On or Off like your turn signals and engine warning light.

Each gauge is configured with a Reading Type. The reading types currently include Speedometer, Tachometer, Gear Indicator, Engine Temperature, Fuel Level, Left Turn Signal, Right Turn Signal, Check Engine Indicator, Altimeter & Compass.

Depending on the Gauge Type and Reading Type you will have various options to choose from. The following describes each of the options.

Gauge Options

Option Description
Frame Frames have an X & Y position that are anchored in the top left corner (0,0) of the screen and have a width & height.
Background Image A background image to use for a gauge. **Not yet settable until a future release.
Background Color Pretty simple... It's just a color dude!
Label Text A text label to show with a font size setup in the Label Font Size setting.
Minor Label Text A text label to show in a minor postion with a font size 2 points smaller than the main Label Text is shown in.
Label Position Postion of the label. For a Circular gauge this move the labels to the Top, Right, Left or Bottom around the center. For Linear gauges it basically does the same thing except also is used to indicate a horizontally (Top & Bottom) or vertically (Left & Right) designed mode.
Label Font Size Size of the Label Text. Defaults to a 12 point size.
Number Font Size Size of the Number labels drawn on the auto generate gauge line that match up with the tick marks.
Label/Line Color Primary color used to draw the labels & auto generate gauge line and tick marks.
Label/Line Shadow Color Shadow color used to draw the labels & auto generate gauge line and tick marks.
Needle Image Used on Circular & Linear gauges to indicate the current gauge reading. Should always be oriented point directly upwards with a size that centers it on the gauge. **Not yet settable until a future release.
Start Value The numeric value to show as the starting value on the auto generated line & ticks.
End Value The numeric value to show as the ending value on the auto generated line & ticks.
Major Increment The numeric value to calculate the main tick mark positions with. This value should be equally divisible by the difference of the Start & End Values (E.g. Start Value 0 & End Value 8; Major Increment possible values 0.25, 0.5, 1, 4 & 8.
Minor Increment The numeric value to calculate the minor tick mark positions with. This value should be equally divisible by the difference of the Start & End Values (E.g. Start Value 0 & End Value 8; Major Increment possible values 0.25, 0.5, 1, 2, 4 & 8. Can be empty or zero.
Inset Pushes the auto generated line and tick marks inwards (or outwards when negative) from outer edge by a specified numeric value.
Start Angle On a Circular gauge the starting angle is on the right side 1/2 ways up the edge at 0 degrees. You can have the auto generated line start at any Start Angle relative to the 0 degree angle.
End Angle On a Circular gauge the starting angle is on the right side 1/2 ways up the edge at 0 degrees. You can have the auto generated line end at any End Angle relative to the 0 degree angle.
Shift Light Image Image displayed in background when a Tachometer RPM value reaches and/or exceeds a user settable threshold.
Shift Light Blink Yes or No value to cause the Shift Light Image to blink on & off repeatedly while the RPM threshold has been exceeded.
Rotate Clockwise Used in Circular gauges and causes auto generated numeric labels, needle position and angles to be calculated from the 0 degree angle in a clockwise or counter-clockwise fashion.
Invert Used in Linear gauges and causes auto generated numeric labels, needle position and angles to be calculated from top to bottom or inverted bottom to top (for vertical mode) or left to right or inverted from right to left (for horizontal mode).
Text Format Digital gauges all take a 64-bit floating-point number (double) argument as their gauge reading. This shows up as a %f argument that can be further formated to limit the number of decimal places shown (ex: for 1 decimal place use %.1f). The format specifier gives you the ability to show the value with a nice format a IEEE "printf" compatible type of syntax.
Label Alignment Sets text on a Digital gauge Left, Right or Center aligned.
Multiplier A floating point value to adjust gauge readings by. Defaults to 1.0 for all gauges except Tachometer reading types for which a default multiplier of "0.001" is used (can be explicitly overidden with 1.0 if needed.
On Image Used to indicate the On settings for a Boolean Gauge. **Not yet settable until a future release.
Off Image Used to indicate the Off settings for a Boolean Gauge. **Not yet settable until a future release.