What a reading means - the measurement model every instrument face draws. More...
| Import Statement: | import Clayground.Lab |
An instrument is a model and a face, not a widget. This is the model: a quantity, the limits it is read against, where the round numbers are, whether it sits in a good, a warned or an alarming part of the scale, and how a real movement lags and holds its peak. Gauge, BarFace, ColumnFace and DigitFace only draw it, and any of them renders any scale - a music VU meter is a BarFace on a log scale with peak-hold, not a new component.
It is not visual and has no size. Declare one beside the thing it measures and hand it to as many faces as the lab wants to show at once; they all agree, because there is only one reading.
Three ways to say what the limits are:
Example usage:
import Clayground.Lab
InstrumentScale {
id: windScale
probe: "windSpeed" // or: value: sensor.speed
unit: "m/s"
min: 0; max: 30
okUntil: 12; warnUntil: 20 // green / amber / red bands
damping: 0.4 // the lag of a real movement, in seconds
}
ColumnFace { scale: windScale; label: "WIND" }
DigitFace { scale: windScale }
See also Gauge, BarFace, ColumnFace, DigitFace, and InstrumentDock.
accent : color |
Colour while the instrument has no opinion.
autoRange : bool |
True while ranges drives the limits.
damping : real |
Movement time constant in seconds - the lag of a real meter.
Exponential and frame-rate independent, so a noisy signal reads as a needle that hunts slightly rather than as a blur. 0 (the default) is a perfectly rigid movement, which is what a digital readout wants.
digits : int |
Decimals in the printed reading, or -1 for three significant figures.
displayValue : real |
Where the face actually points - the reading after lag and settling.
fullScale : real |
Alias of hi, in the language a bench meter uses.
graded : bool |
True while the instrument has bands to judge by.
hi : real |
Top of the scale in force - the selected range, when self-ranging.
lo : real |
Bottom of the scale in force.
logScale : bool |
Position the reading by its logarithm - equal ratios, equal space.
A min of 0 is not an error here; it means four decades below the top, which is what a level meter shows.
max : real |
Top of a fixed scale.
min : real |
Bottom of a fixed scale.
okUntil : real |
Top of the good band. Leave unset for an instrument with no opinion.
peakFall : real |
How fast it then falls, in scale fractions per second.
peakFraction : real |
Where the peak marker sits, 0..1.
peakHold : bool |
Remember the highest reading and mark it.
peakFraction is where the marker sits; faces that can show one (BarFace, ColumnFace) draw it when this is on.
peakHoldTime : real |
Seconds the marker sits before falling.
probe : string |
rangeText : string |
The scale in force, e.g. "0 - 10 mA".
ranges : var |
reading : real |
The value as it is read against the scale.
A self-ranging meter reads magnitudes, so this is |source| there and source itself on a fixed scale that may run negative.
settleTime : int |
Milliseconds a face takes to travel to a new reading.
For a value that changes on an action - a switch closing, a scenario applied - the swing is worth showing. Set it to 0 for a continuously changing signal: an animation restarted every frame never arrives, and the face then visibly disagrees with the number printed on it. Use damping for that case instead.
severity : string |
"ok", "warn" or "alarm".
severityColor : color |
The colour the reading has earned - accent while the instrument is ungraded.
symbol : string |
What this instrument measures, as a glyph. Defaults to the unit.
Set it when the two differ - a tachometer reading "/min" is still an "n".
tickCount : int |
Labelled divisions a face should aim for.
ticks : var |
Gradations, [{value, fraction, major, text}].
Round numbers (1, 2, 5 and their decades) inside the limits - the limits are the instrument's, so a meter that says 0-2 V ends at 2 V rather than at whatever the tick algorithm found convenient.
unit : string |
SI unit of the reading, e.g. "V".
value : real |
The reading. Ignored while probe names one.
valueText : string |
The reading as a quantity, e.g. "50.0 mA".
warnUntil : real |
Top of the warned band.
zoneList : var |
The bands in force, [{from, to, severity}].
zones : var |
color colorAt(real v) |
The colour a reading of v has earned on this scale.
color colorFor(string severity) |
The theme colour for "ok", "warn" or "alarm".
real fractionOf(real v) |
Where v would sit on this scale, 0..1.
void reset() |
Drops the lag and the held peak - use it at a scenario boundary.
real valueAt(real f) |
What a face's f along the scale reads as.