Widgets widgets/viz
Gauge
A bounded reading drawn as a Braille dial or a fallback bar.
A bounded reading drawn as a Braille dial or a fallback bar.
Package widgets/viz. API reference: pkg.go.dev/widgets/viz.
Gauge is a single bounded value on a dial, with a bar fallback.
Rendered output
cmd/capture through
widgettest.Capture: colour at 3 widths
(40, 80, 120 columns), and the exact plain-text cell grid at
the widest of them.
MinSize() returns 11 × 7 cells.
That is the whole widget including its own chrome, and it is the
widget's assertion about itself — below it, Draw clips rather
than blanks, and what to do about that is the application's decision.
40 columns × 11 rows
╭ dashboard ───────────────────────────╮ │ │ │ │ │ ⠁⠑⠛⠛⠛⠙⠉⠁ │ │ ⠛⠛⠁ ⠂⠛⠙ │ │ ⠁⠙⠁ ⠁⠛⠛ │ │ ⠂⠛⠛⠛⠛⠛⠛⠁ │ │ │ │ │ │render 70 │ ╰──────────────────────────────────────╯
80 columns × 9 rows
╭ dashboard ───────────────────────────────────────────────────────────────────╮ │ │ │ ⠁⠁⠁⠁ │ │ ⠓⠛⠃⠃⠛⠉ │ │ ⠙⠉⠁⠁⠓⠛ │ │ ⠃⠛⠛⠃ │ │ │ │render 70 │ ╰──────────────────────────────────────────────────────────────────────────────╯
120 columns × 9 rows
╭ dashboard ───────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ │ │ ⠁⠁⠁⠁ │ │ ⠓⠛⠃⠃⠛⠉ │ │ ⠙⠉⠁⠁⠓⠛ │ │ ⠃⠛⠛⠃ │ │ │ │render 70 │ ╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Plain text — the exact cell grid, trimmed per line. This is the honest form: Braille and block-element glyphs can take a different advance width in a web font than a terminal gives them, which breaks the alignment they depend on.
# Gauge — A bounded reading drawn as a Braille dial or a fallback bar. # package: widgets/viz # constructor: viz.NewGauge(r buffer.Rect) *viz.Gauge # 120 columns x 9 rows, rendered through widgettest.Capture ╭ dashboard ───────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ │ │ ⠁⠁⠁⠁ │ │ ⠓⠛⠃⠃⠛⠉ │ │ ⠙⠉⠁⠁⠓⠛ │ │ ⠃⠛⠛⠃ │ │ │ │render 70 │ ╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
What you are looking at. This is the cell grid the renderer produced, in a web page. It is not a screenshot of a terminal, and it cannot show interaction, resize or animation — a capture is one settled frame after N frames of settling. Braille and Block Elements can take a different advance width in your browser's font than in a terminal, so if a gauge or a sparkline above looks wrong, the plain-text form below it is the exact output and the colour one is the decoration. The colour frames are at 40, 80, 120 columns; the plain-text frame is at 120. More on this.
About this capture. The dial is Braille, U+2800..28FF: eight levels of vertical resolution in each cell, two samples per cell. A web font that gives those glyphs a different advance width destroys the arc, which is why the plain-text capture beside it is mandatory rather than a nicety.
Package context
Package viz provides the catalog’s measurement and display widgets: ProgressBar, Gauge, Meter, Sparkline and BarChart.
- Its space is Bounds(), never buf.Size() (ADR 0007 §1 rule 1).
- It repaints its whole Bounds() before drawing content (rule 3), by composing widgets/block.Block, whose Draw fills the rect in Background before anything else. No widget here draws a border, a corner or a title itself.
- Its Draw is allocation-free (ADR 0008 §4). Everything derived from the size — which regions survived the budget, where the axis labels go, the glyph ramp for a sparkline — is computed in the size-change check, cached against the rect, and only read in Draw.
Constructing it
viz.NewGauge(r buffer.Rect) *viz.Gauge
NewGauge takes a rect; Value is a field in the widget’s own range.
Value—float64— the reading, in the unitsMin/Maxdefine.Min—float64— the bottom of the dial.Max—float64— the top. A zero range is handled, not a divide-by-zero.Dial— unexporteddialParts— the arc geometry, chosen by the rect. Exported as whole parts so the fallback and the dial cannot disagree.ShowLabel—bool— draw the label.ShowValuedraws the number, which is the reading independent of the dial.
More on accessibility
The dial is Braille, U+2800..28FF: eight levels of vertical resolution per cell, two samples per cell. A web font that gives those glyphs a different advance width destroys the arc, which is why the plain-text capture sits beside every colour capture on this site and why ShowValue exists. Read the number, not the shape.
When not to use it
Do not use it where the exact value matters and the dial is the only reading. Braille gives roughly eight levels per cell; the arc tells a reader roughly where, and only ShowValue tells them how much. A gauge with ShowValue off is a decoration. If the number is the point, show the number.
Do not use it in a rect too small to hold a dial. It degrades to a bar — deliberately, so it never draws nonsense — but then you have a ProgressBar with extra steps. Check MinSize() before you assume you got a dial.
Do not use it for a series. One bounded value is what a dial encodes. History is Sparkline.
Do not use it for a bounded value with meaningful zones. A dial has no threshold. That is Meter, and if the reader’s question is “am I over the line”, a dial cannot answer it.
Do not screenshot it and expect the screenshot to survive. This is the widget most exposed to the capture problem on this site. See Limitations.
Instead: Meter for zones and a threshold, ProgressBar for a plain ratio, Sparkline for history.
Related
Meter— the zoned, thresholded reading.ProgressBar— the bar fallback this degrades to.- Limitations
- TermMosaic limitations that apply to every widget
- Source:
widgets/vizon GitHub