LineChart

A LineChart plots one or more numeric series over a shared X axis. Every series is a list of points, drawn with a marker and connected by a line. The value type T is any numeric type that implements Number: i8, i16, i32, i64, i128, u8, u16, u32, u64, u128, usize, isize, f32, or f64.

All series share the same columns: point i of every series is drawn at X position i, so a chart with several series compares their values at each position. The X range is as long as the longest series; shorter series simply end earlier. The vertical scale is computed from the smallest and largest values across all series.

Create one with LineChart::new (a layout and initialization flags) or with the linechart! macro. With LineChart::new, name the numeric type on the variable or with a turbofish:

let chart: LineChart<i32> = LineChart::new(layout!("d:f"), linechart::Flags::ScrollBars);
let chart = LineChart::<f64>::new(layout!("d:f"), linechart::Flags::None);

The macro takes the numeric type as its first parameter:

let c1 = linechart!("i32,d:f");
let c2 = linechart!("class:i32,x:1,y:1,w:60,h:20,flags:[ScrollBars,GroupHover]");
let c3 = linechart!("f64,d:f,scale:fit,series:[{Temp,values:[21.5,23.0,19.75]}]");

A new chart has no series. It scales points with BarScale::FromZero, shows the Y axis and its grid (6 characters wide, a label every 3 rows), and draws no X axis. Points are drawn with a small bullet marker (●), connected with a single line, and separated by 2 empty cells. Series without their own color use the theme chart colors, in order. Integer values are formatted with thousands separators. Floating-point values are formatted with two decimals.

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

Flags

• linechart::Flags::ScrollBars or ScrollBars (for macro initialization) — shows a horizontal scroll bar when the points are wider than the control. The bottom margin grows while the chart has focus so the scroll bar stays visible.
• linechart::Flags::ShowZeroLineOnYAxis or ShowZeroLineOnYAxis (for macro initialization) — draws a solid horizontal line at value zero while the Y-axis grid is visible.
• linechart::Flags::DimPointsOnSelection or DimPointsOnSelection (for macro initialization) — while a point is selected, everything except that point is drawn with the inactive chart color.
• linechart::Flags::GroupHover or GroupHover (for macro initialization) — hovering acts on a whole X position instead of a single point: the column under the mouse is highlighted with the theme hover color, and the tooltip shows the value of every series at that position.

let chart = linechart!("i32,d:f,flags:[ScrollBars,DimPointsOnSelection,GroupHover]");

Series

A series has a label, an optional line mode, an optional color, and a list of points. A series that does not set its own line mode uses the chart default, and a series without its own color uses the next theme chart color.

Data is always added to a series by its index, so a series must be added before its values. add_series returns the index of the new series:

let mut chart = LineChart::<i32>::new(layout!("d:f"), linechart::Flags::None);
let cpu = chart.add_series(linechart::Series::new("CPU"));
let ram = chart.add_series(
    linechart::SeriesBuilder::new("RAM")
        .line(linechart::LineMode::Braille)
        .attr(charattr!("yellow"))
        .values([20, 25, 30]),
);
chart.add_values(cpu, [10, 40, 25]);
chart.add_value(ram, 28);

In the series list of the macro, a dictionary describes a series. All fields are optional.

let chart = linechart!(
    "i32,d:f,
     series:[
        {CPU, values:[35,42,38,55], attr:green},
        {RAM, values:[20,22,25,24], line:Braille, attr:yellow}
     ]"
);

Points

A point is a Bar<T>, the same type used by VBarChart and HBarChart. A value of type T converts into a point, so chart.add_value(0, 10) and a bare number in values are enough for a default point. A point can also override:

• its label — a note about that value only (for example "peak"), shown in the point’s tooltip. It is not drawn under the X axis; the names of the X positions belong to the chart (see X-axis labels).
• its color (attr) — the color of its marker.
• its marker, through its draw mode: BarDrawMode::Point(...) draws a small marker and BarDrawMode::FramedPoint(...) a framed one. Any other draw mode is ignored and the chart default marker is used.

The thickness and spacing of a point are ignored: all series share the same columns.

chart.add_value(0, BarBuilder::new(80).label("peak").draw_mode(BarDrawMode::FramedPoint(BarFramedPointType::RoundSquareBullet)).build());

In the macro, a point is described with the same dictionary as a VBarChart bar:

let chart = linechart!("i32,d:f,series:[{CPU,values:[35,42,{80,label:peak,dm:FramedPoint(RoundSquareBullet),attr:red},38]}]");

Line modes

linechart::LineMode chooses how consecutive points of a series are connected. Lines are drawn first and markers on top of them. The default is Line(Single).

Line and Orthogonal take a LineType: Single, Double, SingleThick (thick), Border, Ascii, AsciiRound, SingleRound (round), or Braille. Orthogonal also takes an OrthogonalDirection: Auto (the default), HorizontalFirst, VerticalFirst, HorizontalUntilMiddle, or VerticalUntilMiddle.

chart.set_default_line(linechart::LineMode::Orthogonal(LineType::Double, OrthogonalDirection::HorizontalFirst));
chart.update_series(1, |s| {
    s.set_line(Some(linechart::LineMode::Braille));
});

Markers

linechart::Marker chooses what is drawn at every point. The default is Small(Bullet).

Small accepts Bullet (●, the default), Diamond (◆), Square (■), or a custom character.

Framed accepts:

• RoundSquare (the default), Square, DoubleLineSquare, ThickSquare — an empty frame;
• RoundSquareBullet, SquareBullet, DoubleLineSquareBullet, ThickSquareBullet — the same frames with a bullet in the middle;
• BrailleCircle, BrailleCircleBullet, BrailleFilledCircle — a circle drawn with braille dots;
• Filled, or a custom character that fills the whole marker.

Every column is as wide as the widest marker in the chart, so points of different series stay aligned. The middle row of a framed marker is on the value, and the plot keeps one free row at the top and at the bottom so a framed marker at the minimum or maximum is not cut. Lines are attached to the middle of the left and right sides of a framed marker; where a box-drawing line touches a box-drawing frame, the frame gets a junction (─┤ ● ├─).

chart.set_default_marker(linechart::Marker::Framed(BarFramedPointType::BrailleCircle));
let chart = linechart!("i32,d:f,marker:Framed(DoubleLineSquareBullet),line:Line(Double)");

Scale

scale chooses how values become rows. The same values are available from set_scale as linechart::BarScale<T>. The range covers the values of every series.

• FromZero or zero — the visible range includes zero and every value. This is the default.
• FromZeroMinRange(min, max) or zero-min-range(min, max) — same as FromZero, and the range is also expanded so that it covers min and max.
• FitData or fit — the smallest and largest values stretch across the full plot height.
• Fixed(min, max) or fix(min, max) — uses a fixed range. Values outside it are drawn at the corresponding edge of the plot.

let fit = linechart!("f64,d:f,scale:fit");
let fixed = linechart!("i32,d:f,scale:Fixed(0,100)");

X-axis labels

The names of the X positions (for example months) belong to the chart: label i names the points at index i of every series. They are shown in the hover tooltips, and under the X axis when the label mode is Labels.

chart.set_xaxis_labels(["Jan", "Feb", "Mar"]);
chart.add_xaxis_label("Apr");
chart.set_xaxis_label_mode(linechart::XAxisLabelMode::Labels);

In the macro, labels sets the names. When labels is given without xlabels, the label mode is set to Labels as well:

let chart = linechart!("i32,d:f,labels:[Jan,Feb,Mar],series:[{CPU,values:[35,42,38]}]");

xlabels chooses what is drawn under the X axis. The same modes are available from set_xaxis_label_mode as linechart::XAxisLabelMode.

• None — draws no X axis. This is the default.
• Index(start) — labels each position with start + index. Index(1) labels the first position 1, the next 2, and so on.
• Labels — uses the names set with labels / set_xaxis_labels. Positions without a name (or with an empty one) are skipped.
• A list of spans — each span covers a run of positions. A span is {start, count, label}, exactly as for VBarChart.

let by_index = linechart!("i32,d:f,xlabels:Index(2020)");
let by_span = linechart!("i32,d:f,xlabels:[{0,3,'Q1'},{3,3,'Q2'}]");

Number format

numeric-format (or set_number_format) controls the text used for Y-axis labels, the zero-line label, and hover tooltips, with the same syntax as for VBarChart.

let chart = linechart!("f64,d:f,nf:{dec,decimals:1}");

Hover and selection

Hovering a point shows a tooltip with the series name, the name of the X position and the value, and the point’s note when it has one. With GroupHover, the tooltip lists the value of every series at the hovered X position instead.

Clicking a point selects it; the selected point is outlined with the theme selection border. Clicking away from every point clears the selection. When markers overlap, the one drawn on top (the last series) is selected. From code, select_point and clear_selection change the selection without raising events.

Events

To intercept events from a LineChart, implement LineChartEvents<T> on the window that runs the event loop. The attribute events = LineChartEvents<T> generates the trait. Both methods are required.

pub trait LineChartEvents<T> {
    fn on_point_selected(&mut self, handle: Handle<LineChart<T>>, series_index: u32, point_index: u32) -> EventProcessStatus;
    fn on_clear_selection(&mut self, handle: Handle<LineChart<T>>) -> EventProcessStatus;
}

on_point_selected runs when the user selects a point that was not already selected, with a click or with the keyboard. series_index and point_index are zero-based. on_clear_selection runs when the user clears the selection, with a click outside every point or with Escape.

Methods

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

Series

On a series returned by get_series or passed into update_series:

To keep a sliding window over live data, append the new values and their X names, then drop the oldest ones from every series and from the names:

chart.update_all_series(|_, s| s.remove_first(1));
chart.remove_first_xaxis_labels(1);

The selection is not moved when points are removed this way: clear or move it with clear_selection / select_point if needed.

Key association

The following keys are processed by a LineChart when it has focus.

Mouse association

Example

The following window shows three series over twelve months. Selecting a point writes its series, month and value into the window title. Clearing the selection restores the original title.

A larger editor (series, per-point appearance, axes, scale and markers) is in examples/linechart_editor.

use appcui::prelude::*;

#[Window(events = LineChartEvents<i32>)]
struct MyWin {
    chart: Handle<LineChart<i32>>,
}

impl MyWin {
    fn new() -> Self {
        let mut win = MyWin {
            base: window!("Usage,d:f"),
            chart: Handle::None,
        };
        win.chart = win.add(linechart!(
            "type: i32, d:f, flags: ScrollBars+GroupHover, spacing: 3,
            labels: [Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec],
            series: [
                {CPU, line: Braille, attr: green,
                 values: [35, 42, 38, 55, 61, 48, 72, {80, label: peak}, 66, 58, 63, 70]},
                {RAM, line: Line(Single), attr: yellow,
                 values: [20, 22, 25, 24, 30, 33, 31, 36, 40, 38, 41, 45]},
                {Disk, line: Orthogonal(Single, HorizontalFirst), attr: aqua,
                 values: [5, 5, 10, 10, 10, 15, 15, 20, 20, 25, 25, 25]}
            ]"
        ));
        win
    }
}

impl LineChartEvents<i32> for MyWin {
    fn on_point_selected(&mut self, handle: Handle<LineChart<i32>>, series_index: u32, point_index: u32) -> EventProcessStatus {
        let mut title = String::from("Usage");
        if let Some(chart) = self.control(handle) {
            if let Some(series) = chart.get_series(series_index as usize) {
                if let Some(point) = series.get(point_index as usize) {
                    let month = chart.xaxis_label(point_index as usize).unwrap_or("");
                    title = format!("Usage - {} {} = {}", series.label(), month, point.value());
                }
            }
        }
        self.set_title(&title);
        EventProcessStatus::Processed
    }

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

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