Pie Chart

A pie chart: the parts of a whole as the slices of a disc, each as much of the turn as its value is of their sum. With a hole in its middle it is a ring, a donut, which has room in the hole for a total or a title.

import com.pantrixui.components.chart.pie.PantrixPieChart

• Angle. startAngle is where the first slice begins, in degrees clockwise from twelve o'clock; sweepAngle is how much of a turn the slices take together: 360 a whole pie, 180 a half pie. A half pie is as wide as its box allows.
• Order and small slices. sort lays the slices out as given, largest first or smallest first. others gathers the slices smaller than a share of the whole into one slice at the end; that slice's tooltip and what a screen reader hears of it name each one it holds.
• Values. A slice's value is an amount; the chart works out its share. A slice with no value, or one that is not over nought, has no place in the pie, and its name stays in the legend.
• Ring. hole says how much of the radius is cut out: nought is a whole pie, six tenths a ring with room to write in. center stands in the hole, in the largest box the hole holds; in a half ring, in the hole of the half that is drawn.
• The slice pointed at. The slice under the pointer, or the one that is touched, stands out past the pie's rim and the tooltip writes its value and its share. With a finger, another touch on the slice that is pointed at lets go of it.
• Legend. The names of the slices, each beside its colour. Pressing an entry takes the slice out of the pie; the slices that are left share the whole anew.
• Labels. labels writes each slice's share on the slice, in black or white, whichever reads better on its colour; its value, where format is given. A label that does not fit on its slice is written outside it with the slice's name, and a line in the slice's colour links it to the slice. position changes this: Outside writes all of them outside, Center only inside. The pie makes room at its two sides for the words outside it; where that room would leave the pie less than half its size, the words stay inside only.
• Direction. The pie turns clockwise in a language read from right to left too; its legend follows the reading direction.
• 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. The chart is PieChart_<tagKey>; the pie .Plot, the slices .Slice_<number>, the legend's entries .Legend_<the slice's key>, the tooltip .Tooltip.

Examples

The shares of a whole

At its plainest: the slices, each with its key, its name and its value. The first slice starts at twelve o'clock and the others follow it clockwise; the legend stands under the chart.

Move the pointer over a slice, or touch it: the slice stands out and the tooltip writes the number of visits and its share of the total. Press a name in the legend: the slice goes and the others share the whole anew.

PantrixPieChart(
    slices = VISIT_SOURCES.map { PieSlice(it.key, it.name, it.visits) },
    description = "Visits by source",
    tagKey = "plain"
)

private data class VisitSource(
    val key: String,
    val name: String,
    val visits: Int,
    val before: Int
)

private val VISIT_SOURCES = listOf(
    VisitSource("direct", "Direct", visits = 420, before = 380),
    VisitSource("search", "Search", visits = 310, before = 240),
    VisitSource("social", "Social", visits = 150, before = 260),
    VisitSource("mail", "E-mail", visits = 80, before = 90),
    VisitSource("other", "Other", visits = 40, before = 30)
)

A ring with its total in the middle

A pie with its middle cut out is a ring: six tenths of the radius are cut out (hole) and the total is written in the hole (center).

Take a slice out from the legend: the number in the middle becomes the total of the slices that are left. The screen keeps the chart's state itself (rememberChartState) and reads the hidden slices from it.

val state = rememberChartState()
val strings = PantrixTheme.strings
val total = VISIT_SOURCES.filter { it.key !in state.hidden }.sumOf { it.visits }
PantrixPieChart(
    slices = VISIT_SOURCES.map { PieSlice(it.key, it.name, it.visits) },
    hole = 0.6f,
    center = {
        Column(horizontalAlignment = Alignment.CenterHorizontally) {
            PantrixText(text = strings.decimal(total), style = PantrixTheme.typography.title)
            PantrixText(text = "visits", color = PantrixTheme.colors.textSecondary)
        }
    },
    state = state,
    description = "Visits by source, with their total in the middle",
    tagKey = "ring"
)

private data class VisitSource(
    val key: String,
    val name: String,
    val visits: Int,
    val before: Int
)

private val VISIT_SOURCES = listOf(
    VisitSource("direct", "Direct", visits = 420, before = 380),
    VisitSource("search", "Search", visits = 310, before = 240),
    VisitSource("social", "Social", visits = 150, before = 260),
    VisitSource("mail", "E-mail", visits = 80, before = 90),
    VisitSource("other", "Other", visits = 40, before = 30)
)

The shares on the slices

The shares are on the slices (labels): each slice has its share of the total written on it, in black or white, whichever reads better on the slice's colour. Turn the switch: the labels write the value, not the share (ChartDataLabels(format = …)).

A label that does not fit on its slice is written outside it with the slice's name; a line links it to its slice.

var values by remember { mutableStateOf(false) }
val strings = PantrixTheme.strings
PantrixSwitchButton(
    checked = values,
    onCheckedChange = { values = it },
    label = "Write the values",
    tagKey = "pie_labels_values"
)
PantrixPieChart(
    slices = VISIT_SOURCES.map { PieSlice(it.key, it.name, it.visits) },
    labels = if (values) ChartDataLabels(format = { strings.decimal(it) }) else ChartDataLabels(),
    description = "Visits by source, with their shares",
    tagKey = "labels"
)

private data class VisitSource(
    val key: String,
    val name: String,
    val visits: Int,
    val before: Int
)

private val VISIT_SOURCES = listOf(
    VisitSource("direct", "Direct", visits = 420, before = 380),
    VisitSource("search", "Search", visits = 310, before = 240),
    VisitSource("social", "Social", visits = 150, before = 260),
    VisitSource("mail", "E-mail", visits = 80, before = 90),
    VisitSource("other", "Other", visits = 40, before = 30)
)

Where the labels go

Where the labels go (ChartDataLabels(position = …)). "Automatic" (Auto) writes each share on its slice and the ones that do not fit outside; "Outside" (Outside) writes each slice's name and share beside the pie; "Inside" (Center) leaves out the ones that do not fit. A line in the slice's colour links the words outside to their slice, and the pie makes room for them at its two sides.

var place by remember { mutableStateOf(ChartDataLabelPosition.Outside) }
PantrixSegmentButton(
    options = PIE_LABEL_PLACES,
    selected = place,
    onSelect = { place = it },
    fullWidth = false,
    tagKey = "pie_label_place"
)
PantrixPieChart(
    slices = VISIT_SOURCES.map { PieSlice(it.key, it.name, it.visits) },
    labels = ChartDataLabels(position = place),
    legend = null,
    description = "Visits by source, with their shares",
    tagKey = "label_place"
)

private data class VisitSource(
    val key: String,
    val name: String,
    val visits: Int,
    val before: Int
)

private val VISIT_SOURCES = listOf(
    VisitSource("direct", "Direct", visits = 420, before = 380),
    VisitSource("search", "Search", visits = 310, before = 240),
    VisitSource("social", "Social", visits = 150, before = 260),
    VisitSource("mail", "E-mail", visits = 80, before = 90),
    VisitSource("other", "Other", visits = 40, before = 30)
)

private val PIE_LABEL_PLACES = listOf(
    SegmentOption(value = ChartDataLabelPosition.Auto, label = "Automatic", tagKey = "auto"),
    SegmentOption(value = ChartDataLabelPosition.Outside, label = "Outside", tagKey = "outside"),
    SegmentOption(value = ChartDataLabelPosition.Center, label = "Inside", tagKey = "inside")
)

A half ring

A half ring: the slices begin at nine o'clock (startAngle = 270f) and take half a turn (sweepAngle = 180f). The ring is as wide as its box allows, and the total stands in the hole of the half that is drawn.

val total = PantrixTheme.strings.decimal(VISIT_SOURCES.sumOf { it.visits })
PantrixPieChart(
    slices = VISIT_SOURCES.map { PieSlice(it.key, it.name, it.visits) },
    hole = 0.6f,
    startAngle = 270f,
    sweepAngle = 180f,
    center = { PantrixText(text = total, style = PantrixTheme.typography.title) },
    description = "Visits by source, a half ring",
    tagKey = "half"
)

private data class VisitSource(
    val key: String,
    val name: String,
    val visits: Int,
    val before: Int
)

private val VISIT_SOURCES = listOf(
    VisitSource("direct", "Direct", visits = 420, before = 380),
    VisitSource("search", "Search", visits = 310, before = 240),
    VisitSource("social", "Social", visits = 150, before = 260),
    VisitSource("mail", "E-mail", visits = 80, before = 90),
    VisitSource("other", "Other", visits = 40, before = 30)
)

Order and small slices

Visits by browser, largest first (sort = PieSort.Descending). The slices smaller than five hundredths of the whole are gathered into one slice at the end (others = PieOthers(share = 0.05f)); its name is the theme's word. Move the pointer over the gathered slice, or touch it: the tooltip names each one it holds. Turn the switch off: every slice shows.

var gathered by remember { mutableStateOf(true) }
PantrixSwitchButton(
    checked = gathered,
    onCheckedChange = { gathered = it },
    label = "Gather the small ones",
    tagKey = "pie_gathered"
)
PantrixPieChart(
    slices = BROWSER_VISITS.map { PieSlice(it.key, it.name, it.visits) },
    sort = PieSort.Descending,
    others = if (gathered) PieOthers(share = 0.05f) else null,
    labels = ChartDataLabels(),
    legend = ChartLegend(position = ChartLegendPosition.End),
    description = "Visits by browser",
    tagKey = "gathered"
)

private data class Browser(
    val key: String,
    val name: String,
    val visits: Int
)

private val BROWSER_VISITS = listOf(
    Browser("safari", "Safari", 198),
    Browser("firefox", "Firefox", 42),
    Browser("chrome", "Chrome", 612),
    Browser("opera", "Opera", 24),
    Browser("edge", "Edge", 54),
    Browser("uc", "UC", 17),
    Browser("samsung", "Samsung", 31),
    Browser("yandex", "Yandex", 22)
)

Where the legend stands

The legend stands on one of the chart's four sides. Above and under it the entries are set in a row, which goes on to another line where they do not fit; at the sides they stand under one another and take no more than four tenths of the width. The pie is the largest circle that fits in the middle of what the legend leaves.

var place by remember { mutableStateOf(ChartLegendPosition.End) }
PantrixSegmentButton(
    options = PIE_LEGEND_PLACES,
    selected = place,
    onSelect = { place = it },
    fullWidth = false,
    tagKey = "pie_legend_place"
)
PantrixPieChart(
    slices = VISIT_SOURCES.map { PieSlice(it.key, it.name, it.visits) },
    hole = 0.6f,
    legend = ChartLegend(position = place),
    description = "Visits by source",
    tagKey = "legend"
)

private data class VisitSource(
    val key: String,
    val name: String,
    val visits: Int,
    val before: Int
)

private val VISIT_SOURCES = listOf(
    VisitSource("direct", "Direct", visits = 420, before = 380),
    VisitSource("search", "Search", visits = 310, before = 240),
    VisitSource("social", "Social", visits = 150, before = 260),
    VisitSource("mail", "E-mail", visits = 80, before = 90),
    VisitSource("other", "Other", visits = 40, before = 30)
)

private val PIE_LEGEND_PLACES = listOf(
    SegmentOption(value = ChartLegendPosition.Top, label = "Top", tagKey = "top"),
    SegmentOption(value = ChartLegendPosition.Bottom, label = "Bottom", tagKey = "bottom"),
    SegmentOption(value = ChartLegendPosition.Start, label = "Start", tagKey = "start"),
    SegmentOption(value = ChartLegendPosition.End, label = "End", tagKey = "end")
)

Pressing a slice

onSelect gives the slice that is pressed: its key, its name, its value and how the chart writes it. Press a slice, or go to one with the keyboard and press Enter: the line under the card writes what was pressed.

val report = LocalExampleEvents.current
PantrixPieChart(
    slices = VISIT_SOURCES.map { PieSlice(it.key, it.name, it.visits) },
    description = "Visits by source",
    onSelect = { point -> report("${point.name}: ${point.text}") },
    tagKey = "pressed"
)

private data class VisitSource(
    val key: String,
    val name: String,
    val visits: Int,
    val before: Int
)

private val VISIT_SOURCES = listOf(
    VisitSource("direct", "Direct", visits = 420, before = 380),
    VisitSource("search", "Search", visits = 310, before = 240),
    VisitSource("social", "Social", visits = 150, before = 260),
    VisitSource("mail", "E-mail", visits = 80, before = 90),
    VisitSource("other", "Other", visits = 40, before = 30)
)

Values that change

When the values change the slices go from where they were to where they are now. Turn the switch: the chart shows last year's visits. The slices are matched by their keys: a slice whose name or value changes is the same slice, and keeps its colour and its place in the legend.

var before by remember { mutableStateOf(false) }
PantrixSwitchButton(
    checked = before,
    onCheckedChange = { before = it },
    label = "Last year",
    tagKey = "pie_before"
)
PantrixPieChart(
    slices = VISIT_SOURCES.map { PieSlice(it.key, it.name, if (before) it.before else it.visits) },
    hole = 0.6f,
    labels = ChartDataLabels(),
    description = if (before) "Visits by source last year" else "Visits by source this year",
    tagKey = "changing"
)

private data class VisitSource(
    val key: String,
    val name: String,
    val visits: Int,
    val before: Int
)

private val VISIT_SOURCES = listOf(
    VisitSource("direct", "Direct", visits = 420, before = 380),
    VisitSource("search", "Search", visits = 310, before = 240),
    VisitSource("social", "Social", visits = 150, before = 260),
    VisitSource("mail", "E-mail", visits = 80, before = 90),
    VisitSource("other", "Other", visits = 40, before = 30)
)

Your own colours and sizes

A chart's own look. Each slice names its own colour (PieSlice(color = …)): shades of one violet from the palette in place of the theme's chart colours. ChartStyle gives the sizes: no gap between the slices (sliceGap) and a lower chart (height). A field that is not given stays the theme's.

val dark = LocalDemoDarkTheme.current
val violet = PantrixPalette.Violet
val tones = if (dark) {
    listOf(violet.shade300, violet.shade400, violet.shade500, violet.shade600, violet.shade700)
} else {
    listOf(violet.shade800, violet.shade600, violet.shade500, violet.shade400, violet.shade300)
}
PantrixPieChart(
    slices = VISIT_SOURCES.mapIndexed { index, source ->
        PieSlice(source.key, source.name, source.visits, color = tones[index])
    },
    labels = ChartDataLabels(),
    description = "Visits by source",
    style = ChartStyle(sliceGap = 0.dp, height = 180.dp),
    tagKey = "own_look"
)

private data class VisitSource(
    val key: String,
    val name: String,
    val visits: Int,
    val before: Int
)

private val VISIT_SOURCES = listOf(
    VisitSource("direct", "Direct", visits = 420, before = 380),
    VisitSource("search", "Search", visits = 310, before = 240),
    VisitSource("social", "Social", visits = 150, before = 260),
    VisitSource("mail", "E-mail", visits = 80, before = 90),
    VisitSource("other", "Other", visits = 40, before = 30)
)

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 pie as it is on the screen, the legend under it; the slice that is pointed at and its tooltip are not in it. What stands in the hole by center is not in the file either.

var file by remember { mutableStateOf<ChartExportFile?>(null) }
PantrixPieChart(
    slices = VISIT_SOURCES.map { PieSlice(it.key, it.name, it.visits) },
    hole = 0.6f,
    center = { PantrixText(text = "Visits", color = PantrixTheme.colors.textSecondary) },
    description = "Visits by source",
    tagKey = "exported",
    export = ChartExport(fileName = "visit-sources") { file = it }
)
ExportedFile(file, tagKey = "exported")

private data class VisitSource(
    val key: String,
    val name: String,
    val visits: Int,
    val before: Int
)

private val VISIT_SOURCES = listOf(
    VisitSource("direct", "Direct", visits = 420, before = 380),
    VisitSource("search", "Search", visits = 310, before = 240),
    VisitSource("social", "Social", visits = 150, before = 260),
    VisitSource("mail", "E-mail", visits = 80, before = 90),
    VisitSource("other", "Other", visits = 40, before = 30)
)

API

slices

A pie chart: the parts of a whole as the slices of a disc, each as much of the turn as its value is of their sum. With a hole in its middle it is a ring, a donut, which has room in the hole for a total or a title.

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

• Keyboard. The pie is one stop for Tab: the arrows go from slice to slice, and after the last slice back to the first; Home and End go to the first and the last slice, Escape lets go, Enter and Space press the slice that is pointed at. On desktop and on the web a press on the pie gives it the focus: the arrows that follow go round this pie.
• Screen reader. The chart says its description first, then each slice with its name, its value and its share.