Meter Group

A meter group: several amounts of one whole, side by side on one bar. What a storage is filled with, how a budget is spent: the parts are read against each other and against what is left.

import com.pantrixui.components.chart.metergroup.PantrixMeterGroup

• Values. A part's value is counted in what max is counted in. A part with no value, or one that is not over nought, takes none of the bar, and its name stays in the legend. What the parts come to past max is cut off at the bar's end.
• Legend. It writes each part's name, then its value, beside its colour. It stands above the bar or under it: a legend at the start counts as above, one at the end as under. Its entries are no switches here: the bar shows what it is given.
• Writing. format says how a value is written in the legend; left out, it is written as a number in the theme's language.
• Direction. In a language read from right to left the first part stands at the right.
• 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. MeterGroup_<tagKey>; the bar .Bar, the legend's entries .Legend_<the part's key>.

Examples

What fills a whole

At its plainest: four things that fill a storage of sixty-four gigabytes. The end of the bar that is not filled shows the room that is left; the legend writes each part with its value.

PantrixMeterGroup(
    items = METER_STORAGE,
    max = 64,
    format = { "${it.toInt()} GB" },
    description = "Storage",
    tagKey = "plain"
)

private val METER_STORAGE = listOf(
    MeterItem("apps", "Apps", 16),
    MeterItem("photos", "Photos", 24),
    MeterItem("messages", "Messages", 8),
    MeterItem("system", "System", 10)
)

The legend above

The legend is above the bar and at the start of the line (ChartLegend(position = Top, alignment = Start)). The values are written as shares of the whole, in the theme's language.

val strings = PantrixTheme.strings
PantrixMeterGroup(
    items = METER_BUDGET,
    format = { strings.percent(it / 100) },
    legend = ChartLegend(position = ChartLegendPosition.Top, alignment = ChartLegendAlignment.Start),
    description = "How the budget is spent",
    tagKey = "legend_above"
)

private val METER_BUDGET = listOf(
    MeterItem("rent", "Rent", 40),
    MeterItem("food", "Food", 25),
    MeterItem("transport", "Transport", 15),
    MeterItem("savings", "Savings", 20)
)

The bar alone

A bar with no legend (legend = null): inside a row, where the words beside it already say what it shows. A screen reader hears the parts from the bar itself.

PantrixMeterGroup(
    items = METER_STORAGE,
    max = 64,
    format = { "${it.toInt()} GB" },
    legend = null,
    description = "Storage",
    tagKey = "bar_only"
)

private val METER_STORAGE = listOf(
    MeterItem("apps", "Apps", 16),
    MeterItem("photos", "Photos", 24),
    MeterItem("messages", "Messages", 8),
    MeterItem("system", "System", 10)
)

Your own colours and sizes

A bar's own look: each part names its own colour, the bar is thicker (meterHeight), its ends are square (barRadius) and there is no gap between the parts (sliceGap). A field that is not given stays the theme's.

val violet = PantrixPalette.Violet
PantrixMeterGroup(
    items = listOf(
        MeterItem("done", "Done", 18, color = violet.shade700),
        MeterItem("doing", "In progress", 9, color = violet.shade500),
        MeterItem("waiting", "Waiting", 13, color = violet.shade300)
    ),
    max = 40,
    description = "State of the work",
    style = ChartStyle(meterHeight = 16.dp, barRadius = 0.dp, sliceGap = 0.dp),
    tagKey = "own_look"
)

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 file has the bar and the legend under it: each part's name and value.

var file by remember { mutableStateOf<ChartExportFile?>(null) }
PantrixMeterGroup(
    items = METER_STORAGE,
    max = 64,
    format = { "${it.toInt()} GB" },
    description = "Storage",
    tagKey = "exported",
    export = ChartExport(fileName = "storage") { file = it }
)
ExportedFile(file, tagKey = "exported")

private val METER_STORAGE = listOf(
    MeterItem("apps", "Apps", 16),
    MeterItem("photos", "Photos", 24),
    MeterItem("messages", "Messages", 8),
    MeterItem("system", "System", 10)
)

API

items

A meter group: several amounts of one whole, side by side on one bar. What a storage is filled with, how a budget is spent: the parts are read against each other and against what is left.

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 bar is a picture with its description; the legend's entries say the parts. A bar with no legend says its parts itself.