Gauge

A gauge: one reading on a scale, as how far round an arc it reaches. A speed, a load, a share of a quota: a value that is read against the least and the most it can be.

import com.pantrixui.components.chart.gauge.PantrixGauge

• Scale. min and max are the ends of the scale. A value past an end stands at that end and is written as it is. A gauge with no value (null) shows only its scale.
• Ranges. segments gives parts of the scale a colour and a name: the range that is fine, the range that is too much. Each GaugeSegment says where it ends (upTo); the first begins where the scale does, the others where the one before ends. The arc fills in the colour of the range the value has reached; the ranges themselves stay under it in their faint colours.
• Needle. With needle a hand reaches from the middle to the value, and the value is written under it. In a gauge with both a needle and ranges the ranges are drawn in their full colours and the arc is not filled: the hand is read against them.
• Writing. format says how the value and the two ends of the scale are written; left out, they are written as numbers in the theme's language. center puts your own content in place of the value's writing.
• Size and motion. The gauge is as wide as the room it is given and as tall as the chart's style says; the arc is the largest that fits there. When the value changes the arc and the hand go to the new value; where the system asks for reduced motion they do not go, they are there.
• Direction. The scale turns the same way in a language read from right to left too.
• Export. export puts a button over the chart: the chart is made, as it is on the screen and without the part that is pointed at or its tooltip, into a PNG, an SVG or a PDF file and handed to the app.
• Automation. Gauge_<tagKey>.

Examples

A value on a scale

At its plainest: a value and the end of the scale. Thirty-two gigabytes of a storage of fifty are used; format writes the value and the two ends of the scale with their unit.

PantrixGauge(
    value = 32,
    max = 50,
    format = { "${it.toInt()} GB" },
    description = "Storage used",
    tagKey = "plain"
)

Ranges

The scale has three ranges: normal up to sixty, high up to eighty-five, critical after that. The arc fills in the colour of the range the value has reached; the ranges show under it in their faint colours.

Choose a value: the arc goes there and its colour changes with the range it has reached. A screen reader says the range's name after the value too: "72%, High". format writes the value in the theme's language (PantrixTheme.strings.percent).

The ranges name their own colours here: the theme's success, warning and danger colours. A range that is given no colour takes the theme's next chart colour; those colours carry no meaning.

var load by remember { mutableStateOf(72) }
val strings = PantrixTheme.strings
PantrixSegmentButton(
    options = loadReadings(),
    selected = load,
    onSelect = { load = it },
    fullWidth = false,
    tagKey = "gauge_load"
)
PantrixGauge(
    value = load,
    segments = loadRanges(),
    format = { strings.percent(it / 100) },
    description = "Processor load",
    tagKey = "segments"
)

@Composable
private fun loadRanges(): List<GaugeSegment> {
    val colors = PantrixTheme.colors
    return listOf(
        GaugeSegment(upTo = 60, color = colors.success.color, name = "Normal"),
        GaugeSegment(upTo = 85, color = colors.warning.color, name = "High"),
        GaugeSegment(upTo = 100, color = colors.danger.color, name = "Critical")
    )
}

@Composable
private fun loadReadings(): List<SegmentOption<Int>> {
    val strings = PantrixTheme.strings
    return listOf(40 to "low", 72 to "high", 93 to "critical").map { (load, key) ->
        SegmentOption(value = load, label = strings.percent(load / 100.0), tagKey = key)
    }
}

A needle

A gauge with a needle: a hand reaches from the middle to the value, and the value is written under it. The ranges are drawn in their full colours and the arc is not filled: the hand is read against them.

var load by remember { mutableStateOf(40) }
val strings = PantrixTheme.strings
PantrixSegmentButton(
    options = loadReadings(),
    selected = load,
    onSelect = { load = it },
    fullWidth = false,
    tagKey = "gauge_needle_load"
)
PantrixGauge(
    value = load,
    segments = loadRanges(),
    needle = true,
    format = { strings.percent(it / 100) },
    description = "Processor load",
    tagKey = "needle"
)

@Composable
private fun loadRanges(): List<GaugeSegment> {
    val colors = PantrixTheme.colors
    return listOf(
        GaugeSegment(upTo = 60, color = colors.success.color, name = "Normal"),
        GaugeSegment(upTo = 85, color = colors.warning.color, name = "High"),
        GaugeSegment(upTo = 100, color = colors.danger.color, name = "Critical")
    )
}

@Composable
private fun loadReadings(): List<SegmentOption<Int>> {
    val strings = PantrixTheme.strings
    return listOf(40 to "low", 72 to "high", 93 to "critical").map { (load, key) ->
        SegmentOption(value = load, label = strings.percent(load / 100.0), tagKey = key)
    }
}

A scale that does not start at nought

A gauge with a needle and no ranges: the arc fills up to the value and the hand points at it too. A scale need not start at nought: this thermometer goes from twenty below to forty.

val strings = PantrixTheme.strings
PantrixGauge(
    value = 7.5,
    min = -20,
    max = 40,
    needle = true,
    format = { "${strings.decimal(it, fractionDigits = 1)}°" },
    description = "Outside temperature",
    tagKey = "below_zero"
)

Your own content in the middle

center puts your own content in place of the value's writing: here the unit under the value. The content fits the room the arc leaves in its middle.

A screen reader hears the value from the gauge itself (description and format); what is written in the middle is for the eye.

PantrixGauge(
    value = 86,
    max = 120,
    format = { "${it.toInt()} km/h" },
    center = {
        Column(horizontalAlignment = Alignment.CenterHorizontally) {
            PantrixText(text = "86", style = PantrixTheme.typography.headline)
            PantrixText(text = "km/h", color = PantrixTheme.colors.textSecondary)
        }
    },
    description = "Speed",
    tagKey = "own_center"
)

Your own sizes

A gauge's own sizes: a thinner arc (gaugeWidth) and a lower gauge (height). No gap between the ranges (sliceGap). A field that is not given stays the theme's.

val strings = PantrixTheme.strings
PantrixGauge(
    value = 54,
    segments = loadRanges(),
    format = { strings.percent(it / 100) },
    description = "Processor load",
    style = ChartStyle(gaugeWidth = 8.dp, height = 160.dp, sliceGap = 0.dp),
    tagKey = "own_look"
)

@Composable
private fun loadRanges(): List<GaugeSegment> {
    val colors = PantrixTheme.colors
    return listOf(
        GaugeSegment(upTo = 60, color = colors.success.color, name = "Normal"),
        GaugeSegment(upTo = 85, color = colors.warning.color, name = "High"),
        GaugeSegment(upTo = 100, color = colors.danger.color, name = "Critical")
    )
}

Export

export = ChartExport(...) puts an export button over the chart: press it and choose the kind (PNG, SVG or PDF). The chart makes the file and hands it to onExport; below, its name and size show, and a PNG's picture, and "Save the file" hands it over in the platform's way.

The value in the middle is written in the file too; content put there by center is not in the file.

var file by remember { mutableStateOf<ChartExportFile?>(null) }
PantrixGauge(
    value = 32,
    max = 50,
    format = { "${it.toInt()} GB" },
    description = "Storage used",
    tagKey = "exported",
    export = ChartExport(fileName = "storage") { file = it }
)
ExportedFile(file, tagKey = "exported")

API

value

A gauge: one reading on a scale, as how far round an arc it reaches. A speed, a load, a share of a quota: a value that is read against the least and the most it can be.

ChartStyle

A chart's geometry: how tall it is where nothing says, how thick its lines and how large its marks are, and the room between its parts; and whether its fills have textures besides their colours.

ChartColors

What a chart is painted with, for a chart that does not take the theme's colours: a colour that is set is used, and one that is left out stays the theme's.

Accessibility

• Screen reader. The gauge is one thing: its description, then the value as it is written and, where it has one, the name of the range it is in.