Line Chart

A line chart of rows that are given once: a line for each of the values read from them, along the places x reads from them.

import com.pantrixui.components.chart.line.PantrixLineChart

• Rows and values. data gives the rows, x a row's place. Each ChartValue is a series: its key, its name and the function that reads its value from a row.
• How the line goes. curve says how the line goes from one point to the next: straight, smooth or stepped. A smooth line stays between two points; it shows no peak or dip that the values do not have.
• More than colour. A series' dash draws its line in dashes or in dots, and its marker puts a shape on its points. Both show in the series' sample in the legend and in the tooltip.
• Missing values. missing says what the line does at a row that has no value: it breaks, connects, or counts it as zero.
• Numeric axis. Where the places are numbers and xAxis = ChartAxis(numeric = true), the points stand as far apart as their numbers and the axis is marked at round numbers; otherwise numbers are names too, set out at even steps.
• Value labels and marks. labels writes the values over the points; marks draws a target line or the band of a range.
• When `PantrixChart`. For a chart whose series come from different lists, are of different kinds or are read by a second axis: each series takes its own LineSeries.
• Automation. The chart is tagged as the PantrixChart it is: Chart_<tagKey>.

Examples

Lines from the same rows

At its plainest: the rows, the x that gives a row's place, and a ChartValue for each series. A series takes its key and its name; the block at the end reads its value from a row.

Three series take the theme's first three chart colours. Press a name in the legend: its series goes, and the ones that stay keep their colours.

PantrixLineChart(
    data = TRAFFIC,
    x = { it.day },
    values = listOf(
        ChartValue("search", "Search") { it.search },
        ChartValue("direct", "Direct") { it.direct },
        ChartValue("social", "Social") { it.social }
    ),
    description = "Three sources of visits by day of the week",
    tagKey = "plain"
)

private data class Traffic(
    val day: String,
    val search: Int,
    val direct: Int,
    val social: Int
)

private val TRAFFIC = listOf(
    Traffic("Mon", search = 420, direct = 240, social = 130),
    Traffic("Tue", search = 480, direct = 260, social = 120),
    Traffic("Wed", search = 455, direct = 300, social = 165),
    Traffic("Thu", search = 530, direct = 280, social = 190),
    Traffic("Fri", search = 510, direct = 330, social = 240),
    Traffic("Sat", search = 360, direct = 210, social = 310),
    Traffic("Sun", search = 330, direct = 180, social = 285)
)

Numeric axis

The height of a hiking trail, measured at uneven points along the way: the places are numbers, in kilometres. With xAxis = ChartAxis(numeric = true) the points stand as far apart as their numbers: 0.8 km and 1.2 km close together, 7.5 km and 11 km far apart; the axis is marked at round kilometres, written as format says. The summit's line does not stand at a measurement but at 9.6 km.

Turn the switch off: the numbers become names, set out at even steps, and the trail's steepness reads wrong.

var numeric by remember { mutableStateOf(true) }
val strings = PantrixTheme.strings
PantrixSwitchButton(
    checked = numeric,
    onCheckedChange = { numeric = it },
    label = "Numeric axis",
    tagKey = "line_numeric"
)
PantrixLineChart(
    data = TRAIL,
    x = { it.first },
    values = listOf(ChartValue("height", "Height (m)") { it.second }),
    curve = ChartCurve.Smooth,
    xAxis = ChartAxis(numeric = numeric, format = { "${strings.decimal(it)} km" }),
    marks = listOf(ChartReferenceLine(x = 9.6, label = "Summit")),
    description = "The height of a hiking trail, measured along the way",
    tagKey = "numeric"
)

private val TRAIL = listOf(
    0.0 to 420,
    0.8 to 455,
    1.2 to 470,
    2.5 to 560,
    4.0 to 610,
    7.5 to 820,
    9.6 to 1_040,
    11.0 to 930,
    12.4 to 780
)

How the line goes

curve says how the line goes from one point to the next. Linear goes straight. Smooth goes round through the points but stays between them: it makes up no peak or dip. The stepped ones carry a value level from one point to the next: StepAfter holds until the value changes, like a stock or a price; StepBefore goes to the next value ahead of it; Step steps halfway between the two.

var curve by remember { mutableStateOf(ChartCurve.Smooth) }
PantrixSegmentButton(
    options = CURVES,
    selected = curve,
    onSelect = { curve = it },
    fullWidth = false,
    tagKey = "curve"
)
PantrixLineChart(
    data = TRAFFIC,
    x = { it.day },
    values = listOf(ChartValue("search", "Search", marker = ChartMarker.Circle) { it.search }),
    curve = curve,
    description = "Visits from search by day of the week",
    tagKey = "curves"
)

private data class Traffic(
    val day: String,
    val search: Int,
    val direct: Int,
    val social: Int
)

private val TRAFFIC = listOf(
    Traffic("Mon", search = 420, direct = 240, social = 130),
    Traffic("Tue", search = 480, direct = 260, social = 120),
    Traffic("Wed", search = 455, direct = 300, social = 165),
    Traffic("Thu", search = 530, direct = 280, social = 190),
    Traffic("Fri", search = 510, direct = 330, social = 240),
    Traffic("Sat", search = 360, direct = 210, social = 310),
    Traffic("Sun", search = 330, direct = 180, social = 285)
)

private val CURVES = listOf(
    SegmentOption(value = ChartCurve.Linear, label = "Straight", tagKey = "linear"),
    SegmentOption(value = ChartCurve.Smooth, label = "Smooth", tagKey = "smooth"),
    SegmentOption(value = ChartCurve.Step, label = "Step", tagKey = "step"),
    SegmentOption(value = ChartCurve.StepBefore, label = "Before", tagKey = "before"),
    SegmentOption(value = ChartCurve.StepAfter, label = "After", tagKey = "after")
)

Series told apart by more than colour

Colour alone is not enough for every reader: for an eye that does not tell red from green, for a black and white printout, for a chart of many series. Here each series is told apart by more than its colour too: one is a solid line with circles, one a dashed line with squares, one a dotted line with triangles.

The same sample stands in the legend and in the tooltip: a series is known there too by its line and its shape.

PantrixLineChart(
    data = TRAFFIC,
    x = { it.day },
    values = listOf(
        ChartValue("search", "Search", marker = ChartMarker.Circle) { it.search },
        ChartValue("direct", "Direct", dash = ChartDash.Dashed, marker = ChartMarker.Square) { it.direct },
        ChartValue("social", "Social", dash = ChartDash.Dotted, marker = ChartMarker.Triangle) { it.social }
    ),
    description = "Three sources of visits by day of the week",
    tagKey = "told_apart"
)

private data class Traffic(
    val day: String,
    val search: Int,
    val direct: Int,
    val social: Int
)

private val TRAFFIC = listOf(
    Traffic("Mon", search = 420, direct = 240, social = 130),
    Traffic("Tue", search = 480, direct = 260, social = 120),
    Traffic("Wed", search = 455, direct = 300, social = 165),
    Traffic("Thu", search = 530, direct = 280, social = 190),
    Traffic("Fri", search = 510, direct = 330, social = 240),
    Traffic("Sat", search = 360, direct = 210, social = 310),
    Traffic("Sun", search = 330, direct = 180, social = 285)
)

A small line with no axes

A small line in the corner of a card: it has no axes and no legend (null), and is sixty dp tall. Its values are still in place: the value of the day pointed at with a pointer or a finger is read in the tooltip, and a screen reader says the days one by one.

A chart with no axis tells its tooltip how its values are written (ChartTooltip.format): here what the number counts is added after the number.

val strings = PantrixTheme.strings
PantrixLineChart(
    data = TRAFFIC,
    x = { it.day },
    values = listOf(ChartValue("search", "Search") { it.search }),
    modifier = Modifier.height(60.dp),
    curve = ChartCurve.Smooth,
    xAxis = null,
    yAxis = null,
    tooltip = ChartTooltip(format = { "${strings.decimal(it)} visits" }),
    description = "Visits from search by day of the week",
    tagKey = "bare"
)

private data class Traffic(
    val day: String,
    val search: Int,
    val direct: Int,
    val social: Int
)

private val TRAFFIC = listOf(
    Traffic("Mon", search = 420, direct = 240, social = 130),
    Traffic("Tue", search = 480, direct = 260, social = 120),
    Traffic("Wed", search = 455, direct = 300, social = 165),
    Traffic("Thu", search = 530, direct = 280, social = 190),
    Traffic("Fri", search = 510, direct = 330, social = 240),
    Traffic("Sat", search = 360, direct = 210, social = 310),
    Traffic("Sun", search = 330, direct = 180, social = 285)
)

API

data

A line chart of rows that are given once: a line for each of the values read from them, along the places x reads from them.

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.