Struct xlsxwriter::chart::Chart

pub struct Chart<'a> { /* private fields */ }

The Chart object represents an Excel chart. It provides functions for adding data series to the chart and for configuring the chart.

A Chart object isn’t created directly. Instead a chart is created by calling the Workbook.add_chart function from a Workbook object. For example:

use xlsxwriter::prelude::*;
let workbook = Workbook::new("test-chart.xlsx")?;
let mut worksheet = workbook.add_worksheet(None)?;
write_worksheet(&mut worksheet)?; // write worksheet contents
let mut chart = workbook.add_chart(ChartType::Column);
chart.add_series(None, Some("=Sheet1!$A$1:$A$5"))?;
chart.add_series(None, Some("=Sheet1!$B$1:$B$5"))?;
chart.add_series(None, Some("=Sheet1!$C$1:$C$5"))?;
worksheet.insert_chart(1, 3, &chart)?;
workbook.close()

The chart in the worksheet will look like this:

The basic procedure for adding a chart to a worksheet is:

Create the chart with Workbook.add_chart. Add one or more data series to the chart which refers to data in the workbook using Chart.add_series. Configure the chart with the other available functions shown below. Insert the chart into a worksheet using Worksheet.insert_chart.

Implementations

impl<'a> Chart<'a>

pub fn add_series( &mut self, categories: Option<&str>, values: Option<&str> ) -> Result<ChartSeries<'a>, XlsxError>

In Excel a chart series is a collection of information that defines which data is plotted such as the categories and values. It is also used to define the formatting for the data.

For an libxlsxwriter chart object the chart_add_series function is used to set the categories and values of the series:

chart.add_series(Some("=Sheet1!$A$1:$A$5"), Some("=Sheet1!$B$1:$B$5"))?;

The series parameters are:

*categories: This sets the chart category labels. The category is more or less the same as the X axis. In most Excel chart types the categories property is optional and the chart will just assume a sequential series from 1..n:

chart.add_series(None, Some("=Sheet1!$B$1:$B$5"))?;

• values: This is the most important property of a series and is the only mandatory option for every chart object. This parameter links the chart with the worksheet data that it displays.

The categories and values should be a string formula like “=Sheet1!$A$2:$A$7” in the same way it is represented in Excel. This is convenient when recreating a chart from an example in Excel but it is trickier to generate programmatically. For these cases you can set the categories and values to None and use the ChartSeries.set_categories and ChartSeries.set_values functions:

let mut series = chart.add_series(None, None)?;
series.set_categories("Sheet1", 0, 0, 4, 0); // "=Sheet1!$A$1:$A$5"
series.set_values("Sheet1", 0, 1, 4, 1);     // "=Sheet1!$B$1:$B$5"

As shown in the previous example the return value from Chart.add_series is a ChartSeries struct. This can be used in other functions that configure a series.

More than one series can be added to a chart. The series numbering and order in the Excel chart will be the same as the order in which they are added in libxlsxwriter:

chart.add_series(None, Some("=Sheet1!$A$1:$A$5"));
chart.add_series(None, Some("=Sheet1!$B$1:$B$5"));
chart.add_series(None, Some("=Sheet1!$C$1:$C$5"));

It is also possible to specify non-contiguous ranges:

chart.add_series(Some("=(Sheet1!$A$1:$A$5,Sheet1!$A$10:$A$18)"), Some("=(Sheet1!$B$1:$B$5,Sheet1!$B$10:$B$18)"))?;

pub fn add_title(&mut self, title: &str) -> Result<(), XlsxError>

The chart_title_set_name function sets the name (title) for the chart. The name is displayed above the chart. The name parameter can also be a formula such as =Sheet1!$A$1 to point to a cell in the workbook that contains the name. The Excel default is to have no chart title.