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:
@code // The NULL category will default to 1 to 5 like in Excel. chart_add_series(chart, NULL, "Sheet1!$A$1:$A$5"); @endcode
- 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 NULL and use the chart_series_set_categories() and chart_series_set_values() functions:
@code lxw_chart_series *series = chart_add_series(chart, NULL, NULL);
// Configure the series using a syntax that is easier to define programmatically. chart_series_set_categories(series, "Sheet1", 1, 0, 6, 0); // "=Sheet1!$A$2:$A$7" chart_series_set_values( series, "Sheet1", 1, 2, 6, 2); // "=Sheet1!$C$2:$C$7" @endcode
As shown in the previous example the return value from %chart_add_series() is a lxw_chart_series pointer. 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:
@code chart_add_series(chart, NULL, "Sheet1!$A$1:$A$5"); chart_add_series(chart, NULL, "Sheet1!$B$1:$B$5"); chart_add_series(chart, NULL, "Sheet1!$C$1:$C$5"); @endcode
It is also possible to specify non-contiguous ranges:
@code chart_add_series( chart, "=(Sheet1!$A$1:$A$9,Sheet1!$A$14:$A$25)", "=(Sheet1!$B$1:$B$9,Sheet1!$B$14:$B$25)" ); @endcode
@brief Add a data series to a chart.
@param chart Pointer to a lxw_chart instance to be configured. @param categories The range of categories in the data series. @param values The range of values in the data series.
@return A lxw_chart_series object pointer.
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:
@code chart_add_series(chart, "=Sheet1!$A$2:$A$7", "=Sheet1!$C$2:$C$7"); @endcode