Treemap

A treemap: a box cut into tiles, each as large as its value is of the whole. It suits a whole of many parts, where a pie would have too many slices to read: the folders of a disk, a budget by its lines, a market by its companies. What is large is seen at once, and the small parts still have their place.

import com.pantrixui.components.chart.treemap.PantrixTreemap

• What is written in a tile. With labels each tile has its name written in it and under it its value, in the one of black and white that reads better on its colour. A tile with no room for its name has neither; the tooltip and a screen reader say both.
• Groups. An item that gives children is a group: its value is the sum of its tiles, and a value given to it is not read.
• Colour. Each item given takes the one of the theme's chart colours that falls to its place; a group's tiles are in the group's colour. color gives an item or a tile a colour of its own.
• Shaded by value. Given a scale, every tile is drawn in its value's shade on the scale, as a heatmap's cells are (HeatmapScale): a large tile lies nearer the scale's end. The item's and the group's colours are not read then; the blocks and the groups' names stay. The scale bar stands where legend says.
• The tile pointed at. The tile under the pointer, or the one that is tapped, is ringed, and the tooltip writes its group, its name, its value and its share of the whole.
• State and pressing. The tile that is pointed at is kept in ChartState, as a selection whose x is the item's key. onSelect gives the tile that is pressed.
• Direction. In a language read from right to left the largest tile lies 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. Treemap_<tagKey>; the tiles .Plot, a tile .Tile_<number>, the scale .Legend, the tooltip .Tooltip.

Examples

What fills a disk

What fills a disk, in gigabytes. Each folder is a tile: the largest comes first.

Move the pointer over a tile or tap it: the tooltip writes the folder's size and its share of the disk.

PantrixTreemap(
    items = diskFolders(),
    description = "The folders that fill the disk",
    tagKey = "plain"
)

internal fun diskFolders(): List<TreemapItem> = listOf(
    TreemapItem("photos", "Photos", 148),
    TreemapItem("video", "Videos", 96),
    TreemapItem("apps", "Apps", 64),
    TreemapItem("music", "Music", 41),
    TreemapItem("docs", "Documents", 27),
    TreemapItem("mail", "Mail", 14),
    TreemapItem("other", "Other", 9)
)

Groups

A budget, by department and by the lines of each department. Each department is a group: its lines lie in one block, in the department's colour, with the department's name over them.

PantrixTreemap(
    items = budgetByDepartment(),
    description = "Budget by department",
    tagKey = "grouped"
)

internal fun budgetByDepartment(): List<TreemapItem> = listOf(
    TreemapItem(
        key = "product",
        name = "Product",
        children = listOf(
            TreemapItem("engineering", "Engineering", 420),
            TreemapItem("design", "Design", 160),
            TreemapItem("research", "Research", 90)
        )
    ),
    TreemapItem(
        key = "growth",
        name = "Growth",
        children = listOf(
            TreemapItem("ads", "Ads", 240),
            TreemapItem("events", "Events", 110),
            TreemapItem("content", "Content", 70)
        )
    ),
    TreemapItem(
        key = "operations",
        name = "Operations",
        children = listOf(
            TreemapItem("support", "Support", 130),
            TreemapItem("office", "Office", 80),
            TreemapItem("legal", "Legal", 45)
        )
    )
)

Shaded by value

The same budget, its tiles shaded by their values (scale): the scale goes from the theme's primary container colour to its primary colour, a large line darker. The scale bar is under the chart; the groups' colours are not read then.

val colors = PantrixTheme.colors
PantrixTreemap(
    items = budgetByDepartment(),
    scale = HeatmapScale(low = colors.primary.container, color = colors.primary.color),
    description = "Budget by department",
    tagKey = "shaded"
)

internal fun budgetByDepartment(): List<TreemapItem> = listOf(
    TreemapItem(
        key = "product",
        name = "Product",
        children = listOf(
            TreemapItem("engineering", "Engineering", 420),
            TreemapItem("design", "Design", 160),
            TreemapItem("research", "Research", 90)
        )
    ),
    TreemapItem(
        key = "growth",
        name = "Growth",
        children = listOf(
            TreemapItem("ads", "Ads", 240),
            TreemapItem("events", "Events", 110),
            TreemapItem("content", "Content", 70)
        )
    ),
    TreemapItem(
        key = "operations",
        name = "Operations",
        children = listOf(
            TreemapItem("support", "Support", 130),
            TreemapItem("office", "Office", 80),
            TreemapItem("legal", "Legal", 45)
        )
    )
)

Pressing a tile

onSelect gives the tile that is pressed: press a tile, or go to one with the keyboard and press Enter, and the line under the card writes what was pressed. The values are written in a way of their own: in the tiles by ChartDataLabels(format), in the tooltip by ChartTooltip(format).

val report = LocalExampleEvents.current
PantrixTreemap(
    items = diskFolders(),
    labels = ChartDataLabels(format = { "${it.toInt()} GB" }),
    tooltip = ChartTooltip(format = { "${it.toInt()} GB" }),
    onSelect = { tile -> report("${tile.name}: ${tile.text}") },
    description = "The folders that fill the disk",
    tagKey = "pressed"
)

internal fun diskFolders(): List<TreemapItem> = listOf(
    TreemapItem("photos", "Photos", 148),
    TreemapItem("video", "Videos", 96),
    TreemapItem("apps", "Apps", 64),
    TreemapItem("music", "Music", 41),
    TreemapItem("docs", "Documents", 27),
    TreemapItem("mail", "Mail", 14),
    TreemapItem("other", "Other", 9)
)

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 tiles and their names; the tooltip of the tile that is pointed at is not in it.

var file by remember { mutableStateOf<ChartExportFile?>(null) }
PantrixTreemap(
    items = diskFolders(),
    description = "The folders that fill the disk",
    tagKey = "exported",
    export = ChartExport(fileName = "disk") { file = it }
)
ExportedFile(file, tagKey = "exported")

internal fun diskFolders(): List<TreemapItem> = listOf(
    TreemapItem("photos", "Photos", 148),
    TreemapItem("video", "Videos", 96),
    TreemapItem("apps", "Apps", 64),
    TreemapItem("music", "Music", 41),
    TreemapItem("docs", "Documents", 27),
    TreemapItem("mail", "Mail", 14),
    TreemapItem("other", "Other", 9)
)

API

items

A treemap: a box cut into tiles, each as large as its value is of the whole. It suits a whole of many parts, where a pie would have too many slices to read: the folders of a disk, a budget by its lines, a market by its companies. What is large is seen at once, and the small parts still have their place.

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 chart is one stop for Tab: an arrow goes to the nearest tile the way it points; Home and End go to the largest tile and the last, Escape lets go, Enter and Space press the tile that is pointed at.
• Screen reader. The chart says its description, then each tile from the largest block on, with its group, its name, its value and its share. A chart of more than two hundred tiles is told by its description alone.