PieChart

A PieChart shows a single series of values as parts of a whole. Each value is a slice whose size is proportional to its share of the total. Values are u64, so a slice can not be negative. A slice with the value 0 stays in the chart (and keeps its index) but takes no space.

The chart can be drawn as a circle, an ellipse, a square, a rectangle or a triangle (with or without rounded corners), with a hole in the middle (a donut), and with labels inside the slices or around the chart. The first slice can start at any angle, and the slices can follow each other clockwise or counter-clockwise.

Create one with PieChart::new (a layout and initialization flags) or with the piechart! macro:

let chart = PieChart::new(layout!("d:f"), piechart::Flags::None);

let c1 = piechart!("d:f");
let c2 = piechart!("x:1,y:1,w:40,h:15,values:[10,20,30]");
let c3 = piechart!("d:f,shape:Ellipse,hollow:50%,labels:Outside,content:LabelAndPercentage,values:[{50,'Rust'},{30,'C++'},{20,'Go'}]");

A new chart starts empty. It is drawn as a circle with half blocks, without a hole and without labels. The first slice starts at 12 o’clock and the slices follow each other clockwise. Each slice uses a theme chart color unless it has its own attribute. Values are written with thousands separators (1,234,567).

A PieChart supports all common parameters (as they are described in Instantiate via Macros section). Besides them, the following named parameters are also accepted:

Flags

• piechart::Flags::DimSlicesOnSelection or DimSlicesOnSelection (for macro initialization) — while a slice is selected, every other slice is drawn with the inactive chart color.

let chart = piechart!("d:f,flags:DimSlicesOnSelection,values:[10,20,30]");

Slices

A slice has a value, a label (that can be empty) and an optional character attribute. Only the foreground color of the attribute is used. Without an attribute, slice i uses the theme chart color i % 4.

chart.add_value(50, "Rust", None);
chart.add_value(30, "C++", Some(CharAttribute::with_fore_color(Color::Red)));
chart.add_value(20, "", None);

The percentage of every slice is computed with two decimals, and the percentages of all slices always add up to exactly 100.00%.

In the values (or data, or slices) list, an item is either a number (a slice with no label and an automatic color) or a dictionary. value is required. The other fields are optional.

let chart = piechart!("d:f,values:[10,{20,'Rust'},{30,label:'C++',attr:red},{40,Go,color:{fore:green}}]");

Shape

shape (or set_shape) chooses the outline the chart is drawn in. The values are available from code as piechart::DrawModeShape. Every shape is fitted in the control, one character away from every edge.

Circles and squares look round and square on screen: the chart takes into account that a character is about twice as tall as it is wide. In every shape, the area of a slice is proportional to its value.

Renderer

renderer (or set_renderer) chooses how the slices are turned into characters. The values are available from code as piechart::DrawModeRenderer.

The renderers that draw one character per pixel (Solid to Custom) use a pixel that is 2 characters wide, so the shape keeps its proportions. HalfBlocks and Braille give the smoothest outlines.

let braille = piechart!("d:f,renderer:Braille");
let custom = piechart!("d:f,dm:Custom('#')");
chart.set_renderer(piechart::DrawModeRenderer::Shade50);

Hole

hollow (or set_hollow_thickness) adds a hole in the middle of the chart, so the slices are drawn in the band between the hole and the outline. The values are available from code as piechart::HollowThickness. A hole larger than the shape is capped at the shape’s size (and nothing is drawn).

let donut = piechart!("d:f,hollow:50%");
chart.set_hollow_thickness(piechart::HollowThickness::Absolute(6));

Labels

labels (or set_label_layout) chooses where the labels are drawn. The values are available from code as piechart::LabelLayout.

• None — no labels. This is the default.
• Inside — each label is centered on its slice.
• Outside — labels are drawn around the chart (above, below, left or right of their slice) and linked to it with a short line. The chart shrinks to make room for them. When the control is too small for that, the labels are not drawn.

content (or set_label_content) chooses what a label shows. The values are available from code as piechart::LabelContent.

With LabelAndValue and LabelAndPercentage, a slice with an empty label shows only its value or percentage. With Label, a slice with an empty label has no label. Slices with the value 0 are never labeled.

let chart = piechart!("d:f,labels:Inside,content:Percentage,values:[{1,'A'},{3,'B'}]");

Number format

numeric-format (or set_number_format) controls how values are written in labels and in the hover tooltip. Percentages always use two decimals. The macro uses the same syntax as numericformat!.

let chart = piechart!("d:f,labels:Outside,content:LabelAndValue,nf:{dec,group:3,suffix:' MB'}");
chart.set_number_format(FormatNumber::new(10).group(3, b',').suffix(" MB"));

Start angle and direction

angle (or set_start_angle) sets where the first slice starts, in degrees measured clockwise from 12 o’clock: 0 (the default) starts at the top, 90 on the right, 180 at the bottom and 270 on the left. 360 is the same as 0, and larger values are treated as 360.

direction (or set_direction) sets the direction in which the slices follow each other from there. The values are available from code as piechart::Direction: Clockwise (or cw, the default) and CounterClockwise (or counter-clockwise, ccw).

let chart = piechart!("d:f,angle:90,dir:ccw,values:[10,20,30]");

Selection

A slice is selected by clicking it, with the keyboard, or with set_selected_slice. The selected slice is outlined with the theme selection border and, with DimSlicesOnSelection, the other slices are dimmed. Only slices that are drawn (with a value greater than 0) can be selected.

The selection is cleared when the user clicks outside every slice, presses Escape, or when the chart loses the focus. It is also cleared when the selected slice is removed or its value becomes 0.

Events

To intercept events from a PieChart, implement PieChartEvents on the window that runs the event loop. The attribute events = PieChartEvents generates the trait. Both methods have a default implementation that returns EventProcessStatus::Ignored.

pub trait PieChartEvents {
    fn on_slice_selected(&mut self, handle: Handle<PieChart>, index: usize) -> EventProcessStatus {...}
    fn on_clear_selection(&mut self, handle: Handle<PieChart>) -> EventProcessStatus {...}
}

on_slice_selected runs when the user selects a slice (by clicking it, or with the keyboard). index is the zero-based slice index. on_clear_selection runs when the user clears the selection (by clicking outside every slice, with Escape, or when the chart loses the focus). Selecting the slice that is already selected does not raise the event again.

The events are raised only for user actions. Changing the selection from code with set_selected_slice or clear_selected_slice does not raise them.

Methods

Besides the Common methods for all Controls, a PieChart also has the following additional methods:

Key association

The following keys are processed by a PieChart when it has focus. Slices with the value 0 are skipped, and the selection wraps around.

Mouse association

Example

The following window shows the share of four languages as a donut with outside labels. Selecting a slice writes that language and its value into the window title. Clearing the selection restores the original title.

A larger editor (shape, renderer, hole, labels, rotation and the slices themselves) is in examples/piechart_editor.

use appcui::prelude::*;

#[Window(events = PieChartEvents)]
struct MyWin {
    chart: Handle<PieChart>,
}

impl MyWin {
    fn new() -> Self {
        let mut win = MyWin {
            base: window!("Languages,a:c,w:60,h:20,flags:Sizeable"),
            chart: Handle::None,
        };
        win.chart = win.add(piechart!(
            "d:f,
             flags: DimSlicesOnSelection,
             shape: Ellipse,
             hollow: 40%,
             labels: Outside,
             content: LabelAndPercentage,
             values: [{45, Rust}, {25, 'C++'}, {20, Go}, {10, Zig, attr: gray}]"
        ));
        win
    }
}

impl PieChartEvents for MyWin {
    fn on_slice_selected(&mut self, handle: Handle<PieChart>, index: usize) -> EventProcessStatus {
        if let Some(chart) = self.control(handle) {
            let title = format!(
                "Languages - {} = {}",
                chart.label(index).unwrap_or_default(),
                chart.value(index).unwrap_or_default()
            );
            self.set_title(&title);
        }
        EventProcessStatus::Processed
    }

    fn on_clear_selection(&mut self, _: Handle<PieChart>) -> EventProcessStatus {
        self.set_title("Languages");
        EventProcessStatus::Processed
    }
}

fn main() -> Result<(), appcui::system::Error> {
    App::new().window(MyWin::new).run()
}