Bar Chart

A bar chart of rows that are given once: at each place the rows name, a bar for each of the values read from them, side by side, or on one another where they are stacked.

import com.pantrixui.components.chart.bar.PantrixBarChart

• Side by side or stacked. A place's bars stand side by side; with stacked they stand on one another, in the order of values. Side by side suits a few values compared at each place; stacked suits the parts of a whole: the whole reads as well. A stack's tooltip writes the total after the values.
• Shares. stacking = ChartStacking.Percent counts every stack as a hundred percent: the parts' shares read, not the whole. The axis writes percentages, the tooltip adds each value's share beside it, and a label writes the share.
• Zero. A bar chart's value axis starts at zero: a bar's length is read as an amount. A value below zero goes down from zero; in a stack, under the others that go down.
• Band. Each place has a band of the chart's width, and its bars stand in the middle of that band. A bar is no wider than a set width however much room it has (ChartStyle.barMaxWidth); where there is little room the bars get thinner.
• Horizontal. horizontal = true sets the places down the side of the chart, and the bars go from the left (from the right in a language read from the right): for a ranking, or for places with long names. Each name is written across, on its own line; a name wider than a third of the box is cut short. The values are written under the chart, a second axis over it. The arrows down and up go from place to place, right and left from value to value. A horizontal chart that is looked at closer (zoom) goes up and down its places; its navigator stands upright beside the chart, at the side lines end at.
• The place pointed at. The band of the place under the pointer or the finger is shaded, and the tooltip shows the values of that place. Where the tooltip tells the series apart (shared = false) a ring is drawn around the bar under the pointer.
• With a line. A chart that wants a line over its bars is a PantrixChart: it takes a BarSeries for each run of bars and a LineSeries for the line. Its example is on the "Chart" page.
• Value labels. labels writes the values at the ends of the bars, and inside stacked bars; position names another place, and total writes a stack's total past its end. A label with no room is left out.
• Marks. marks draws a target line or the band of a range, as told on the "Chart" page.
• Automation. The chart is tagged as the PantrixChart it is: Chart_<tagKey>.

Examples

A single amount

At its plainest: the rows, the x that gives a row's place, and a single value. A chart of one series has no legend.

Move the pointer over a month, or touch the month: its band is shaded and the tooltip writes that month's sales.

PantrixBarChart(
    data = SALES,
    x = { it.month },
    values = listOf(ChartValue("online", "Online") { it.online }),
    description = "Online sales by month",
    tagKey = "plain"
)

private data class Sales(
    val month: String,
    val online: Int,
    val stores: Int,
    val partners: Int
)

private val SALES = listOf(
    Sales("Jan", online = 42, stores = 58, partners = 21),
    Sales("Feb", online = 51, stores = 49, partners = 18),
    Sales("Mar", online = 48, stores = 61, partners = 26),
    Sales("Apr", online = 63, stores = 55, partners = 24),
    Sales("May", online = 70, stores = 52, partners = 31),
    Sales("Jun", online = 66, stores = 64, partners = 29)
)

Side by side or stacked

Three sales channels, side by side each month: which of them leads in each month is read. Turn the switch: the bars go on one another (stacked) and each month's total is read too; the channels' shares are seen from the colours.

Press a name in the legend: the channel goes, and the bars that stay widen or the stack gets shorter.

var stacked by remember { mutableStateOf(false) }
PantrixSwitchButton(
    checked = stacked,
    onCheckedChange = { stacked = it },
    label = "Stacked",
    tagKey = "bar_stacked"
)
PantrixBarChart(
    data = SALES,
    x = { it.month },
    values = listOf(
        ChartValue("online", "Online") { it.online },
        ChartValue("stores", "Stores") { it.stores },
        ChartValue("partners", "Dealers") { it.partners }
    ),
    stacked = stacked,
    description = "Sales of three channels by month",
    tagKey = "stacked"
)

private data class Sales(
    val month: String,
    val online: Int,
    val stores: Int,
    val partners: Int
)

private val SALES = listOf(
    Sales("Jan", online = 42, stores = 58, partners = 21),
    Sales("Feb", online = 51, stores = 49, partners = 18),
    Sales("Mar", online = 48, stores = 61, partners = 26),
    Sales("Apr", online = 63, stores = 55, partners = 24),
    Sales("May", online = 70, stores = 52, partners = 31),
    Sales("Jun", online = 66, stores = 64, partners = 29)
)

Values that go below zero

Values on both sides of zero: a month's profit or loss. A profit goes up from zero and a loss down from it; a line is drawn at zero. The values are written short (format).

val strings = PantrixTheme.strings
PantrixBarChart(
    data = BALANCE,
    x = { it.first },
    values = listOf(ChartValue("balance", "Profit") { it.second }),
    yAxis = ChartAxis(format = { strings.compact(it) }),
    description = "Profit and loss by month",
    tagKey = "below_zero"
)

private val BALANCE = listOf(
    "Jan" to 64_000,
    "Feb" to 31_000,
    "Mar" to -12_000,
    "Apr" to -38_000,
    "May" to 22_000,
    "Jun" to 87_000
)

Bars read one at a time

The tooltip tells the series apart (shared = false): the bar under the pointer is marked by a ring and the tooltip writes its value alone. On a keyboard the arrows up and down go from one bar to the other. Press a bar: the row underneath writes what was pressed.

var pressed by remember { mutableStateOf<String?>(null) }
PantrixBarChart(
    data = SALES,
    x = { it.month },
    values = listOf(
        ChartValue("online", "Online") { it.online },
        ChartValue("stores", "Stores") { it.stores }
    ),
    tooltip = ChartTooltip(shared = false),
    onSelect = { pressed = "${it.label}, ${it.name}: ${it.text}" },
    description = "Online and store sales by month",
    tagKey = "one_by_one"
)
PantrixText(text = pressed ?: "Press a bar")

private data class Sales(
    val month: String,
    val online: Int,
    val stores: Int,
    val partners: Int
)

private val SALES = listOf(
    Sales("Jan", online = 42, stores = 58, partners = 21),
    Sales("Feb", online = 51, stores = 49, partners = 18),
    Sales("Mar", online = 48, stores = 61, partners = 26),
    Sales("Apr", online = 63, stores = 55, partners = 24),
    Sales("May", online = 70, stores = 52, partners = 31),
    Sales("Jun", online = 66, stores = 64, partners = 29)
)

Many places

Thirty days. Each day's band is narrow and the bars are thin to match; the days' names are left out by a rule. All the values stay where they are: the value of every day is shown with a pointer or a finger.

PantrixBarChart(
    data = DAYS,
    x = { it.first },
    values = listOf(ChartValue("orders", "Orders") { it.second }),
    xAxis = ChartAxis(label = { "Day $it" }),
    description = "Daily orders of the last thirty days",
    tagKey = "many_places"
)

private val DAYS = List(30) { day -> (day + 1) to 120 + day * 4 - (if (day % 7 >= 5) 45 else 0) + (day * 37) % 23 }

Long names

Places with long names: a shop's eight best-selling products. Where the names do not fit side by side, and more of them fit turned, they are written turned an eighth, each ending under its place; where they do not fit turned either, every second or third is written, as before. The first and the last name are always written. A very long name is cut short so that it reaches no further down than a third of the chart's height, and a name at the box's edge so that it stays inside. Short names stay flat.

PantrixBarChart(
    data = BEST_SELLERS,
    x = { it.first },
    values = listOf(ChartValue("sold", "Sold (units)") { it.second }),
    description = "This month's sales of the eight best-selling products",
    tagKey = "long_names"
)

private val BEST_SELLERS = listOf(
    "Wireless headphones" to 412,
    "Smart watch" to 356,
    "Portable charger" to 298,
    "Bluetooth speaker" to 251,
    "Gaming mouse" to 214,
    "Mechanical keyboard" to 187,
    "High-resolution webcam" to 143,
    "USB-C hub" to 121
)

Horizontal bars

The same eight products, as horizontal bars (horizontal = true): the names stand beside the chart, each on its own line, written across; the bars go from the left and their values are written at their ends (labels). The target line (marks) stands on the axis of values, so it cuts the chart from top to bottom.

Move the pointer over a product or touch it: its row is shaded and the tooltip writes its value. With the keyboard, on the chart, the down and up arrows go from product to product.

PantrixBarChart(
    data = BEST_SELLERS,
    x = { it.first },
    values = listOf(ChartValue("sold", "Sold (units)") { it.second }),
    horizontal = true,
    labels = ChartDataLabels(),
    marks = listOf(ChartReferenceLine(y = 300, label = "Target")),
    description = "This month's sales of the eight best-selling products, as horizontal bars",
    tagKey = "horizontal"
)

private val BEST_SELLERS = listOf(
    "Wireless headphones" to 412,
    "Smart watch" to 356,
    "Portable charger" to 298,
    "Bluetooth speaker" to 251,
    "Gaming mouse" to 214,
    "Mechanical keyboard" to 187,
    "High-resolution webcam" to 143,
    "USB-C hub" to 121
)

Horizontal and stacked

Horizontal bars stand side by side or stacked too: here three channels' monthly sales, stacked. The legend takes a channel out; each stack's total is written at the end of its bar (total).

PantrixBarChart(
    data = SALES,
    x = { it.month },
    values = listOf(
        ChartValue("online", "Online") { it.online },
        ChartValue("stores", "Stores") { it.stores },
        ChartValue("partners", "Dealers") { it.partners }
    ),
    stacked = true,
    horizontal = true,
    labels = ChartDataLabels(total = true),
    description = "Sales of three channels by month, as horizontal stacked bars",
    tagKey = "horizontal_stacked"
)

private data class Sales(
    val month: String,
    val online: Int,
    val stores: Int,
    val partners: Int
)

private val SALES = listOf(
    Sales("Jan", online = 42, stores = 58, partners = 21),
    Sales("Feb", online = 51, stores = 49, partners = 18),
    Sales("Mar", online = 48, stores = 61, partners = 26),
    Sales("Apr", online = 63, stores = 55, partners = 24),
    Sales("May", online = 70, stores = 52, partners = 31),
    Sales("Jun", online = 66, stores = 64, partners = 29)
)

A long ranking

The number of stores in forty provinces, from the most to the fewest: this many rows do not fit in the chart's height. In a horizontal chart that is looked at closer (zoom) the first ten provinces fill the plot (ChartState.zoomTo); the navigator (navigator = true) stands upright at the chart's right and shows all the provinces, and the part in view is dragged along it or made larger by its ends.

Drag the chart up and down with the mouse, turn the wheel, or slide two fingers along it; the wheel with Ctrl, and two fingers moved apart or together, look closer or further off. The buttons go up and down, look further off and closer, and show all the provinces again. With the keyboard the arrow down goes to the next province; reaching one that is out of view moves the part in view.

val state = rememberChartState()
LaunchedEffect(state) { state.zoomTo(start = 0f, end = 0.25f) }
PantrixBarChart(
    data = PROVINCES,
    x = { it.first },
    values = listOf(ChartValue("stores", "Stores") { it.second }),
    modifier = Modifier.height(360.dp),
    horizontal = true,
    zoom = ChartZoom(navigator = true),
    state = state,
    description = "The number of stores in forty provinces, from the most to the fewest",
    tagKey = "long_ranking"
)

private val PROVINCES = PROVINCE_NAMES.mapIndexed { place, name -> name to 2400 / (place + 3) + 5 }

private val PROVINCE_NAMES = (
    "İstanbul Ankara İzmir Bursa Antalya Konya Adana Gaziantep Şanlıurfa Kocaeli " +
        "Mersin Diyarbakır Hatay Manisa Kayseri Samsun Balıkesir Kahramanmaraş Van Aydın " +
        "Tekirdağ Sakarya Denizli Muğla Eskişehir Mardin Trabzon Malatya Ordu Erzurum " +
        "Afyonkarahisar Sivas Tokat Zonguldak Adıyaman Elazığ Batman Çorum Kütahya Şırnak"
).split(" ")

Values over the bars

Values are written beside the bars (labels): over the end of a bar that stands by itself, under a bar that goes below zero. Turn the switch: in stacked bars a value is written inside its bar, in the black or white that reads better on the bar's colour, and the stack's total over its end (total). The line marks a target no month reaches (marks); where it runs through a label, the label is written on a plate that covers the line there. The target's words stand at the line's start (labelPosition): at its end they would take the place of the highest months' labels.

Pick where the labels go with the buttons (position): "Auto" is wherever there is room; the others are past the bar's end, inside its end, its middle and its base. Past the end of a stacked bar is the next bar: there the label is written inside the end of its own bar.

A label is written where it has room: one that would stand on another label, reach out of the chart or not fit its bar is left out; the value is still in the tooltip and with the screen reader. ChartDataLabels(format = …) says how a value is written; left out, the axis' way of writing is used.

var stacked by remember { mutableStateOf(false) }
var position by remember { mutableStateOf(ChartDataLabelPosition.Auto) }
PantrixSwitchButton(
    checked = stacked,
    onCheckedChange = { stacked = it },
    label = "Stacked",
    tagKey = "bar_labels_stacked"
)
PantrixSegmentButton(
    options = LABEL_PLACES,
    selected = position,
    onSelect = { position = it },
    fullWidth = false,
    tagKey = "label_place"
)
PantrixBarChart(
    data = SALES,
    x = { it.month },
    values = listOf(
        ChartValue("online", "Online") { it.online },
        ChartValue("stores", "Stores") { it.stores }
    ),
    stacked = stacked,
    labels = ChartDataLabels(position = position, total = stacked),
    marks = listOf(
        ChartReferenceLine(
            y = if (stacked) 140 else 75,
            label = "Target",
            labelPosition = ChartMarkLabelPosition.Start
        )
    ),
    description = "Online and store sales by month, with their values",
    tagKey = "labels"
)

private data class Sales(
    val month: String,
    val online: Int,
    val stores: Int,
    val partners: Int
)

private val SALES = listOf(
    Sales("Jan", online = 42, stores = 58, partners = 21),
    Sales("Feb", online = 51, stores = 49, partners = 18),
    Sales("Mar", online = 48, stores = 61, partners = 26),
    Sales("Apr", online = 63, stores = 55, partners = 24),
    Sales("May", online = 70, stores = 52, partners = 31),
    Sales("Jun", online = 66, stores = 64, partners = 29)
)

private val LABEL_PLACES = listOf(
    SegmentOption(value = ChartDataLabelPosition.Auto, label = "Auto", tagKey = "auto"),
    SegmentOption(value = ChartDataLabelPosition.Outside, label = "Out", tagKey = "outside"),
    SegmentOption(value = ChartDataLabelPosition.InsideEnd, label = "End", tagKey = "inside_end"),
    SegmentOption(value = ChartDataLabelPosition.Center, label = "Middle", tagKey = "center"),
    SegmentOption(value = ChartDataLabelPosition.InsideStart, label = "Base", tagKey = "inside_start")
)

Stacked as shares

Each channel's share of every month: each month's bar is a hundred percent and the channels take their shares of it (stacking = ChartStacking.Percent). What reads is not the sales themselves but how they are shared: in which month the online share grew. The axis writes percentages and the labels the shares; the tooltip writes each channel's sales with its share, and then the month's total.

PantrixBarChart(
    data = SALES,
    x = { it.month },
    values = listOf(
        ChartValue("online", "Online") { it.online },
        ChartValue("stores", "Stores") { it.stores },
        ChartValue("partners", "Dealers") { it.partners }
    ),
    stacked = true,
    stacking = ChartStacking.Percent,
    labels = ChartDataLabels(),
    description = "Each channel's share of sales by month",
    tagKey = "shares"
)

private data class Sales(
    val month: String,
    val online: Int,
    val stores: Int,
    val partners: Int
)

private val SALES = listOf(
    Sales("Jan", online = 42, stores = 58, partners = 21),
    Sales("Feb", online = 51, stores = 49, partners = 18),
    Sales("Mar", online = 48, stores = 61, partners = 26),
    Sales("Apr", online = 63, stores = 55, partners = 24),
    Sales("May", online = 70, stores = 52, partners = 31),
    Sales("Jun", online = 66, stores = 64, partners = 29)
)

Second axis

Two kinds of value: sales in thousands of lira, the online share in percent. The share is read by the second axis (ChartValue(axis = ChartYAxis.Second)), which stands at the chart's other side and writes its values its own way (secondYAxis). Both axes start at zero, and their zeros are on one line.

val strings = PantrixTheme.strings
PantrixBarChart(
    data = SALES,
    x = { it.month },
    values = listOf(
        ChartValue("online", "Online") { it.online },
        ChartValue("share", "Online share", axis = ChartYAxis.Second) {
            it.online.toDouble() / (it.online + it.stores)
        }
    ),
    secondYAxis = ChartAxis(format = { strings.percent(it) }),
    description = "Online sales by month, and their share of all sales",
    tagKey = "second_axis"
)

private data class Sales(
    val month: String,
    val online: Int,
    val stores: Int,
    val partners: Int
)

private val SALES = listOf(
    Sales("Jan", online = 42, stores = 58, partners = 21),
    Sales("Feb", online = 51, stores = 49, partners = 18),
    Sales("Mar", online = 48, stores = 61, partners = 26),
    Sales("Apr", online = 63, stores = 55, partners = 24),
    Sales("May", online = 70, stores = 52, partners = 31),
    Sales("Jun", online = 66, stores = 64, partners = 29)
)

Your own sizes

A chart's own sizes: the bars have square ends (barRadius), are no wider than twenty-four dp (barMaxWidth), stand further apart side by side (barGap) and take nine tenths of a month's band (barBandShare). A field that is not given stays the theme's.

PantrixBarChart(
    data = SALES,
    x = { it.month },
    values = listOf(
        ChartValue("online", "Online") { it.online },
        ChartValue("stores", "Stores") { it.stores }
    ),
    description = "Online and store sales by month",
    style = ChartStyle(barRadius = 0.dp, barMaxWidth = 24.dp, barGap = 6.dp, barBandShare = 0.9f),
    tagKey = "own_look"
)

private data class Sales(
    val month: String,
    val online: Int,
    val stores: Int,
    val partners: Int
)

private val SALES = listOf(
    Sales("Jan", online = 42, stores = 58, partners = 21),
    Sales("Feb", online = 51, stores = 49, partners = 18),
    Sales("Mar", online = 48, stores = 61, partners = 26),
    Sales("Apr", online = 63, stores = 55, partners = 24),
    Sales("May", online = 70, stores = 52, partners = 31),
    Sales("Jun", online = 66, stores = 64, partners = 29)
)

API

data

A bar chart of rows that are given once: at each place the rows name, a bar for each of the values read from them, side by side, or on one another where they are stacked.

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.