docs: add secondary and combined chart docs

examples/Readme.md

@@ -33,6 +33,9 @@ documentation and generally show how an individual function works.
 * `app_chart_column.rs` - An example of creating column charts using the
   rust_xlsxwriter library.
 
+* `app_chart_combined.rs` - An example of creating combined charts using
+  the rust_xlsxwriter library.
+
 * `app_chart_data_table.rs` - An example of creating Excel Column charts
   with data tables using the rust_xlsxwriter library.
 
@@ -48,6 +51,9 @@ documentation and generally show how an individual function works.
 * `app_chart_line.rs` - An example of creating line charts using the
   rust_xlsxwriter library.
 
+* `app_chart_pareto.rs` - An example of creating a Pareto chart using the
+  rust_xlsxwriter library.
+
 * `app_chart_pattern.rs` - An example of creating column charts with fill
   patterns using the rust_xlsxwriter library.
 
@@ -60,6 +66,9 @@ documentation and generally show how an individual function works.
 * `app_chart_scatter.rs` - An example of creating scatter charts using the
   rust_xlsxwriter library.
 
+* `app_chart_secondary_axis.rs` - An example of creating an Excel Line
+  chart with a secondary axis using the rust_xlsxwriter library.
+
 * `app_chart_stock.rs` - An example of creating Stock charts using the
   rust_xlsxwriter library. Note, Volume variants of the Excel stock charts
   aren't currently supported but will be in a future release.
@@ -285,6 +294,13 @@ documentation and generally show how an individual function works.
 * `doc_chart_border_formatting.rs` - An example of formatting the border in
   a chart element.
 
+* `doc_chart_combine1.rs` - An example of creating a combined Column and
+  Line chart. In this example they share the same primary Y axis.
+
+* `doc_chart_combine2.rs` - An example of creating a combined Column and
+  Line chart. In this example the Column values are on the primary Y axis
+  and the Line chart values are on the secondary Y2 axis.
+
 * `doc_chart_data_labels.rs` - An example of adding data labels to a chart
   series.
 
@@ -440,6 +456,9 @@ documentation and generally show how an individual function works.
 * `doc_chart_series_set_values.rs` - A chart example demonstrating setting
   the chart series values.
 
+* `doc_chart_series_set_y2_axis.rs` - A chart example demonstrating setting
+  a secondary Y axis.
+
 * `doc_chart_set_chart_area_format.rs` - An example of formatting the chart
   "area" of a chart. In Excel the chart area is the background area behind
   the chart.

examples/doc_chart_combine1.rs

@@ -0,0 +1,54 @@
+// SPDX-License-Identifier: MIT OR Apache-2.0
+//
+// Copyright 2022-2024, John McNamara, [email protected]
+
+//! An example of creating a combined Column and Line chart. In this example
+//! they share the same primary Y axis.
+
+use rust_xlsxwriter::{Chart, ChartType, Workbook, XlsxError};
+
+fn main() -> Result<(), XlsxError> {
+    let mut workbook = Workbook::new();
+    let worksheet = workbook.add_worksheet();
+
+    // Add the worksheet data that the charts will refer to.
+    let data = [
+        [2, 3, 4, 5, 6, 7],
+        [10, 40, 50, 20, 10, 50],
+        [30, 60, 70, 50, 40, 30],
+    ];
+    worksheet.write_column_matrix(0, 0, data)?;
+
+    // Create a new Column chart. This will be the primary chart.
+    let mut column_chart = Chart::new(ChartType::Column);
+
+    // Configure the data series for the primary chart.
+    column_chart
+        .add_series()
+        .set_categories("Sheet1!$A$1:$A$6")
+        .set_values("Sheet1!$B$1:$B$6");
+
+    // Create a new line chart. This will use this as the secondary chart.
+    let mut line_chart = Chart::new(ChartType::Line);
+
+    // Configure the data series for the secondary chart.
+    line_chart
+        .add_series()
+        .set_categories("Sheet1!$A$1:$A$6")
+        .set_values("Sheet1!$C$1:$C$6");
+
+    // Combine the charts.
+    column_chart.combine(&line_chart);
+
+    // Add some axis labels. Note, this is done via the primary chart.
+    column_chart.x_axis().set_name("X axis");
+    column_chart.y_axis().set_name("Y axis");
+
+    // Add the primary chart to the worksheet.
+    worksheet.insert_chart_with_offset(0, 3, &column_chart, 5, 5)?;
+
+    // Save the file to disk.
+    workbook.save("chart.xlsx")?;
+
+    Ok(())
+}

examples/doc_chart_combine2.rs

@@ -0,0 +1,59 @@
+// SPDX-License-Identifier: MIT OR Apache-2.0
+//
+// Copyright 2022-2024, John McNamara, [email protected]
+
+//! An example of creating a combined Column and Line chart. In this example the
+//! Column values are on the primary Y axis and the Line chart values are on the
+//! secondary Y2 axis.
+use rust_xlsxwriter::{Chart, ChartType, Workbook, XlsxError};
+
+fn main() -> Result<(), XlsxError> {
+    let mut workbook = Workbook::new();
+    let worksheet = workbook.add_worksheet();
+
+    // Add the worksheet data that the charts will refer to.
+    let data = [
+        [2, 3, 4, 5, 6, 7],
+        [10, 40, 50, 20, 10, 50],
+        [30, 60, 70, 50, 40, 30],
+    ];
+    worksheet.write_column_matrix(0, 0, data)?;
+
+    // Create a new Column chart. This will be the primary chart.
+    let mut column_chart = Chart::new(ChartType::Column);
+
+    // Configure the data series for the primary chart.
+    column_chart
+        .add_series()
+        .set_categories("Sheet1!$A$1:$A$6")
+        .set_values("Sheet1!$B$1:$B$6");
+
+    // Create a new line chart. This will use this as the secondary chart.
+    let mut line_chart = Chart::new(ChartType::Line);
+
+    // Configure the data series for the secondary chart. This series is also
+    // assigned to the secondary Y2 axis.
+    line_chart
+        .add_series()
+        .set_categories("Sheet1!$A$1:$A$6")
+        .set_values("Sheet1!$C$1:$C$6")
+        .set_y2_axis(true);
+
+    // Combine the charts.
+    column_chart.combine(&line_chart);
+
+    // Add some axis labels. Note, this is done via the primary chart.
+    column_chart.x_axis().set_name("X axis");
+    column_chart.y_axis().set_name("Y axis");
+
+    // The y2 axis properties are set also via the primary chart.
+    column_chart.y2_axis().set_name("Y2 axis");
+
+    // Add the primary chart to the worksheet.
+    worksheet.insert_chart_with_offset(0, 3, &column_chart, 5, 5)?;
+
+    // Save the file to disk.
+    workbook.save("chart.xlsx")?;
+
+    Ok(())
+}

examples/doc_chart_series_set_y2_axis.rs

@@ -0,0 +1,42 @@
+// SPDX-License-Identifier: MIT OR Apache-2.0
+//
+// Copyright 2022-2024, John McNamara, [email protected]
+
+//! A chart example demonstrating setting a secondary Y axis.
+
+use rust_xlsxwriter::{Chart, ChartLegendPosition, ChartType, Workbook, XlsxError};
+
+fn main() -> Result<(), XlsxError> {
+    let mut workbook = Workbook::new();
+    let worksheet = workbook.add_worksheet();
+
+    // Add the worksheet data that the charts will refer to.
+    worksheet.write_column(0, 0, [2, 3, 4, 5, 6, 7])?;
+    worksheet.write_column(0, 1, [10, 40, 50, 20, 10, 50])?;
+
+    // Create a new line chart.
+    let mut chart = Chart::new(ChartType::Line);
+
+    // Configure a series that defaults to the primary axis.
+    chart.add_series().set_values("Sheet1!$A$1:$A$6");
+
+    // Configure another series with a secondary axis.
+    chart
+        .add_series()
+        .set_values("Sheet1!$B$1:$B$6")
+        .set_y2_axis(true);
+
+    // Add some axis labels.
+    chart.y_axis().set_name("Y axis");
+    chart.y2_axis().set_name("Y2 axis");
+
+    // Move the legend to the bottom for clarity.
+    chart.legend().set_position(ChartLegendPosition::Bottom);
+
+    // Add the chart to the worksheet.
+    worksheet.insert_chart_with_offset(0, 2, &chart, 5, 5)?;
+
+    workbook.save("chart.xlsx")?;
+
+    Ok(())
+}