A needle dial that picks its own range - the instrument, not a number. More...
| Import Statement: | import Clayground.Lab |
A reading printed as text says what the value is; a dial says what it is relative to what the instrument can take, which is the thing a learner actually needs. It came out of the circuit kit's meters, where a printed dial made an ammeter unmistakably an ammeter from across the board in a way a coloured ring never did.
Gauge is the needle face of the instrument foundation: the measurement itself lives in an InstrumentScale, and this draws it. Give it value and ranges and it builds its own scale, which is the short form every existing lab uses; hand it a scale instead and it draws that one - the same scale a BarFace or a DigitFace beside it is drawing, so the two can never disagree.
Ranges work the way a real multimeter's do: give it the ranges the instrument has and it selects the smallest one the reading still fits, printing which range it settled on. That is a lesson in itself - the needle jumping back to a third of scale as the range switches is exactly what a bench meter does.
Everything is laid out in fractions of the item's own size, so the same component serves a 90-pixel HUD dial and a 260x200 item baked into a Texture for a 3D part.
Example usage:
import Clayground.Lab Gauge { width: 120; height: 96 symbol: "A" unit: "A" ranges: [0.01, 0.1, 1, 10] value: circuit.current accent: LabTheme.forest }
See also InstrumentScale, BarFace, ColumnFace, DigitFace, ReadoutPanel, and LabTheme.
accent : color |
Ring/symbol colour - use it to say what this is.
face : color |
The dial face.
frameRadius : real |
Corner radius of the face.
Set it to 0 when the gauge is baked into a Texture: a rounded corner there is a transparent hole in the printed plate rather than a rounded panel.
fullScale : real |
The selected range - the smallest one the reading fits in.
majorEvery : int |
Every n-th tick is a long one.
needleColor : color |
The needle, while the scale has no severity bands.
A graded scale colours the needle by the band the reading is in, since that is the whole point of declaring bands.
rangeText : string |
The selected range as a quantity, e.g. "10 mA".
ranges : var |
Full-scale values on offer, ascending.
The smallest one that still contains the reading is selected. With a single entry the dial is fixed-range.
scale : InstrumentScale |
The measurement this face draws.
Defaults to one built from value, unit, ranges and settleTime - the short form. Assign a shared InstrumentScale to put this needle on the same measurement as the other faces around it; the properties above are then ignored.
settleTime : int |
Milliseconds the needle takes to swing to a new reading.
A real movement has inertia and the swing is worth showing when the value changes on an action - a switch closing, a resistor swapped. Set it to 0 for a continuously changing signal: an animation restarted every frame never arrives, and the needle then visibly disagrees with the number printed under it. For a noisy continuous signal reach for InstrumentScale.damping instead, which lags rather than chases.
Ignored when an external scale is assigned - the scale owns its own dynamics then.
showFrame : bool |
Draw the panel background and border.
showValue : bool |
Print the reading under the dial as well.
Off by default: on a part in a 3D scene the number belongs on a chip beside it, not on the face. On a HUD dial, turn it on.
sweep : real |
Angular travel of the needle, in degrees.
symbol : string |
The large glyph in the corner - what this instrument measures.
Defaults to the unit. Set it when the two differ (a tachometer reading "/min" is still an "n").
ticks : int |
Tick marks across the sweep.
unit : string |
SI unit of value, e.g. "A".
value : real |
The reading. Its magnitude drives the needle.
valueText : string |
The reading as a quantity.