# Bar chart

> Dashboard component reference for the Bar chart, the categorical comparison of live points, with every editor property.

The **Bar chart** compares live points side by side: one bar per address, read at this
moment. It is a categorical chart, not a time chart: there is no time axis, no window,
no sampling cadence and no retention behind it. To follow points over time, use the
[Line chart](component-line-chart).

A point that is not reading is left out of the comparison instead of being drawn at zero,
and the chart says so under the drawing (`1 of 4 points is not reading and is left out.`).
A screen that has only just opened says nothing yet: not read yet is not the same as not
reading.

## Content and points {#content-and-points}

| Property | What it does | Values | Default |
|---|---|---|---|
| Chart title | Optional heading drawn inside the plot. This is the chart's own heading, not the component's corner title (that one lives in the shared Appearance section). | text | empty |
| Points | The categories compared, one card per bar, in the order declared. Each card holds the three fields below. **Add point** appends one. | list | empty |
| · Address | Rooted Logic address the bar reads. The field suggests from the live point list, filtered to numeric points, and shows the point's current reading once named. | address | empty |
| · Name | What the axis and the legend call the bar. | text | blank falls back to the address |
| · Color | The bar's ink as `#RRGGBB`. | hex color | blank takes the palette's turn |
| Order | The order the bars are drawn in. The declared order keeps a station where the operator put it whatever it produced; sorting answers who leads instead. | as declared · smallest first · largest first | as declared |

## Format {#format}

One declaration for the whole chart, on the bars, in the tooltips and in the labels
alike, because a chart writes one number in one way.

| Property | What it does | Values | Default |
|---|---|---|---|
| Unit | Optional engineering unit written after each reading. | text | empty |
| Decimals | Fixed decimal places for the readings. | 0 to 15 | blank uses the station's preference |
| Reads as | How each reading is written out. The value itself is never rescaled by the choice. | Number · Percentage · Duration | Number |
| The value counts | What one unit of the value means while the format is a duration. Only shown for that format. | Seconds · Milliseconds · Minutes | Seconds |

## Bars {#bars}

| Property | What it does | Values | Default |
|---|---|---|---|
| Lay the bars on their side | Draws the bars horizontally. Long names read better across than under a bar. When the cell is too narrow for the names, the readings and the scale side by side, it gives up room in this order: a name longer than its share of the width ends in an ellipsis, then the readings are left off, then the names themselves. The tooltip over a bar still gives its whole name and its reading, and each part comes back as soon as the cell is wide enough for it. | on / off | off |
| Stack them into one bar | Stacks the categories into a single bar instead of standing them beside each other. Beside each other answers "how much did each"; stacked answers "how does the whole divide", which is the pie's question drawn straight. | on / off | off |
| Write each reading on its bar | Writes the formatted value on every bar. A cell too short to write the readings over standing bars, or, with the bars on their side, too narrow to write them beside the bars, leaves them to the tooltip, and so does a reading that would be written over its neighbour's. | on / off | on |
| Min | The bottom the value axis is held at, in the readings' own unit. Blank lets the axis re-fit to whatever is being read, which puts the tallest bar at the top of the plot whatever it measured. A held scale is what makes two glances comparable. | number | blank (auto) |
| Max | The top the value axis is held at. The two ends are independent: a floor can hold while the ceiling follows the data. | number | blank (auto) |
| Legend | Where the legend sits. Offered only while the bars are stacked: standing apart, the bars are already named on the axis and a legend would print the same list twice; stacked into one column, the legend is the only thing that can tell the segments apart. A cell too narrow to write every name on the legend's one row lists the segments one per line instead: a name longer than its line ends in an ellipsis and the tooltip over the line shows it whole. The list takes at most five lines, and fewer in a cell too short to also keep a third of its height for the plot: with more segments than lines, it shows them a page at a time, with the arrows and the page counter (such as 1/3) on its last line. The row comes back once the cell is wide enough. | over the plot · under the plot · none | over the plot |

A cell too small for everything leaves parts off before the plot gets too small to read. In a
short cell, standing bars beside each other give up the readings over them first and then the
names under them, and bars on their side, beside each other or stacked, give up the numbers of the
scale under them. In a narrow cell, standing bars, beside each other or stacked, give up the
numbers of the scale beside them, and a name under a bar that no longer fits ends in an ellipsis.
The tooltip over a bar still gives its name and its reading, and each part comes back as soon as
the cell has room for it.

## Scale bands {#scale-bands}

The **Scale** section declares stretches of the value range and what each means, through
the same band editor every visualization component shares. On a bar chart the bands are a
palette: they tint the bars by where each reading falls, and nothing more. Several
readings are compared at once, so there is no single stretch the drawing is *in*: the
bands carry no wording field here and no reference mark is offered.

Each band covers everything up to its bound, from where the band above it in the list
ended; a reading past the last bound belongs to no band and keeps the bar's authored ink.
The tone names the meaning (Neutral, Information, Success, Caution, Critical) and the
running theme decides the paint.

## Toolbox {#toolbox}

The **Toolbox** section picks which buttons the operator gets on this chart. A comparison
has no axis to walk, so only the tools it can honour are offered; with none of them ticked
no toolbar is drawn at all.

| Tool | What it does | In the default set |
|---|---|---|
| Save PNG | Downloads the drawing as a PNG. | yes |
| Copy PNG | Puts the drawing on the clipboard as a PNG. | yes |
| Full screen | Fills the window with this chart. | yes |