cond format: add data bar docs and examples

examples/app_conditional_formatting.rs

@@ -11,8 +11,9 @@
 use rust_xlsxwriter::{
     ConditionalFormat2ColorScale, ConditionalFormat3ColorScale, ConditionalFormatAverage,
     ConditionalFormatAverageCriteria, ConditionalFormatCell, ConditionalFormatCellCriteria,
-    ConditionalFormatDuplicate, ConditionalFormatText, ConditionalFormatTextCriteria,
-    ConditionalFormatTop, Format, Workbook, XlsxError,
+    ConditionalFormatDataBar, ConditionalFormatDataBarDirection, ConditionalFormatDuplicate,
+    ConditionalFormatText, ConditionalFormatTextCriteria, ConditionalFormatTop, Format, Workbook,
+    XlsxError,
 };
 
 fn main() -> Result<(), XlsxError> {
@@ -330,13 +331,13 @@ fn main() -> Result<(), XlsxError> {
     worksheet.write(0, 1, caption)?;
 
     // Write the worksheet data.
-    let scale_data = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
-    worksheet.write_column(2, 1, scale_data)?;
-    worksheet.write_column(2, 3, scale_data)?;
-    worksheet.write_column(2, 5, scale_data)?;
-    worksheet.write_column(2, 7, scale_data)?;
-    worksheet.write_column(2, 9, scale_data)?;
-    worksheet.write_column(2, 11, scale_data)?;
+    let data = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+    worksheet.write_column(2, 1, data)?;
+    worksheet.write_column(2, 3, data)?;
+    worksheet.write_column(2, 5, data)?;
+    worksheet.write_column(2, 7, data)?;
+    worksheet.write_column(2, 9, data)?;
+    worksheet.write_column(2, 11, data)?;
 
     // Set the column widths for clarity.
     for col_num in 0..=12u16 {
@@ -392,13 +393,13 @@ fn main() -> Result<(), XlsxError> {
     worksheet.write(0, 1, caption)?;
 
     // Write the worksheet data.
-    let scale_data = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
-    worksheet.write_column(2, 1, scale_data)?;
-    worksheet.write_column(2, 3, scale_data)?;
-    worksheet.write_column(2, 5, scale_data)?;
-    worksheet.write_column(2, 7, scale_data)?;
-    worksheet.write_column(2, 9, scale_data)?;
-    worksheet.write_column(2, 11, scale_data)?;
+    let data = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+    worksheet.write_column(2, 1, data)?;
+    worksheet.write_column(2, 3, data)?;
+    worksheet.write_column(2, 5, data)?;
+    worksheet.write_column(2, 7, data)?;
+    worksheet.write_column(2, 9, data)?;
+    worksheet.write_column(2, 11, data)?;
 
     // Set the column widths for clarity.
     for col_num in 0..=12u16 {
@@ -448,6 +449,50 @@ fn main() -> Result<(), XlsxError> {
 
     worksheet.add_conditional_format(2, 11, 11, 11, &conditional_format)?;
 
+    // -----------------------------------------------------------------------
+    // Example 9. Examples of data bars.
+    // -----------------------------------------------------------------------
+    let caption = "Examples of data bars";
+
+    // Add a worksheet to the workbook.
+    let worksheet = workbook.add_worksheet();
+
+    // Write the caption.
+    worksheet.write(0, 1, caption)?;
+    worksheet.write(1, 1, "Default")?;
+    worksheet.write(1, 3, "Default negative")?;
+    worksheet.write(1, 5, "User color")?;
+    worksheet.write(1, 7, "Changed direction")?;
+
+    // Write the worksheet data.
+    let data1 = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+    let data2 = [6, 4, 2, -2, -4, -6, -4, -2, 2, 4];
+    worksheet.write_column(2, 1, data1)?;
+    worksheet.write_column(2, 3, data2)?;
+    worksheet.write_column(2, 5, data1)?;
+    worksheet.write_column(2, 7, data1)?;
+
+    // Write a standard Excel data bar.
+    let conditional_format = ConditionalFormatDataBar::new();
+
+    worksheet.add_conditional_format(2, 1, 11, 1, &conditional_format)?;
+
+    // Write a standard Excel data bar with negative data
+    let conditional_format = ConditionalFormatDataBar::new();
+
+    worksheet.add_conditional_format(2, 3, 11, 3, &conditional_format)?;
+
+    // Write a data bar with a user defined fill color.
+    let conditional_format = ConditionalFormatDataBar::new().set_fill_color("009933");
+
+    worksheet.add_conditional_format(2, 5, 11, 5, &conditional_format)?;
+
+    // Write a data bar with the direction changed.
+    let conditional_format = ConditionalFormatDataBar::new()
+        .set_direction(ConditionalFormatDataBarDirection::RightToLeft);
+
+    worksheet.add_conditional_format(2, 7, 11, 7, &conditional_format)?;
+
     // -----------------------------------------------------------------------
     // Save and close the file.
     // -----------------------------------------------------------------------

examples/doc_conditional_format_2color.rs

@@ -2,7 +2,7 @@
 //
 // Copyright 2022-2023, John McNamara, [email protected]
 
-//! Example of adding 2 color scale type conditional formatting to a worksheet.
+//! Example of adding a 2 color scale type conditional formatting to a worksheet.
 //! Note, the colors in the fifth example (yellow to green) are the default
 //! colors and could be omitted.
 
@@ -14,13 +14,13 @@ fn main() -> Result<(), XlsxError> {
     let worksheet = workbook.add_worksheet();
 
     // Write the worksheet data.
-    let scale_data = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
-    worksheet.write_column(2, 1, scale_data)?;
-    worksheet.write_column(2, 3, scale_data)?;
-    worksheet.write_column(2, 5, scale_data)?;
-    worksheet.write_column(2, 7, scale_data)?;
-    worksheet.write_column(2, 9, scale_data)?;
-    worksheet.write_column(2, 11, scale_data)?;
+    let data = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+    worksheet.write_column(2, 1, data)?;
+    worksheet.write_column(2, 3, data)?;
+    worksheet.write_column(2, 5, data)?;
+    worksheet.write_column(2, 7, data)?;
+    worksheet.write_column(2, 9, data)?;
+    worksheet.write_column(2, 11, data)?;
 
     // Set the column widths for clarity.
     for col_num in 0..=12u16 {

examples/doc_conditional_format_2color_set_color.rs

@@ -2,7 +2,7 @@
 //
 // Copyright 2022-2023, John McNamara, [email protected]
 
-//! Example of adding 2 color scale type conditional formatting to a worksheet
+//! Example of adding a 2 color scale type conditional formatting to a worksheet
 //! with user defined minimum and maximum colors.
 
 use rust_xlsxwriter::{ConditionalFormat2ColorScale, Workbook, XlsxError};
@@ -13,11 +13,11 @@ fn main() -> Result<(), XlsxError> {
     let worksheet = workbook.add_worksheet();
 
     // Write the worksheet data.
-    let scale_data = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+    let data = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
     worksheet.write(1, 1, "Default colors")?;
     worksheet.write(1, 3, "User colors")?;
-    worksheet.write_column(2, 1, scale_data)?;
-    worksheet.write_column(2, 3, scale_data)?;
+    worksheet.write_column(2, 1, data)?;
+    worksheet.write_column(2, 3, data)?;
 
     // Write a 2 color scale formats with standard Excel colors.
     let conditional_format = ConditionalFormat2ColorScale::new();

examples/doc_conditional_format_2color_set_minimum.rs

@@ -2,7 +2,7 @@
 //
 // Copyright 2022-2023, John McNamara, [email protected]
 
-//! Example of adding 2 color scale type conditional formatting to a worksheet
+//! Example of adding a 2 color scale type conditional formatting to a worksheet
 //! with user defined minimum and maximum values.
 
 use rust_xlsxwriter::{ConditionalFormat2ColorScale, ConditionalFormatType, Workbook, XlsxError};
@@ -13,9 +13,9 @@ fn main() -> Result<(), XlsxError> {
     let worksheet = workbook.add_worksheet();
 
     // Write the worksheet data.
-    let scale_data = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
-    worksheet.write_column(2, 1, scale_data)?;
-    worksheet.write_column(2, 3, scale_data)?;
+    let data = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+    worksheet.write_column(2, 1, data)?;
+    worksheet.write_column(2, 3, data)?;
 
     // Write a 2 color scale formats with standard Excel colors. The conditional
     // format is applied from the lowest to the highest value.

examples/doc_conditional_format_3color.rs

@@ -14,13 +14,13 @@ fn main() -> Result<(), XlsxError> {
     let worksheet = workbook.add_worksheet();
 
     // Write the worksheet data.
-    let scale_data = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
-    worksheet.write_column(2, 1, scale_data)?;
-    worksheet.write_column(2, 3, scale_data)?;
-    worksheet.write_column(2, 5, scale_data)?;
-    worksheet.write_column(2, 7, scale_data)?;
-    worksheet.write_column(2, 9, scale_data)?;
-    worksheet.write_column(2, 11, scale_data)?;
+    let data = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+    worksheet.write_column(2, 1, data)?;
+    worksheet.write_column(2, 3, data)?;
+    worksheet.write_column(2, 5, data)?;
+    worksheet.write_column(2, 7, data)?;
+    worksheet.write_column(2, 9, data)?;
+    worksheet.write_column(2, 11, data)?;
 
     // Set the column widths for clarity.
     for col_num in 0..=12u16 {

examples/doc_conditional_format_3color_set_color.rs

@@ -13,11 +13,11 @@ fn main() -> Result<(), XlsxError> {
     let worksheet = workbook.add_worksheet();
 
     // Write the worksheet data.
-    let scale_data = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+    let data = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
     worksheet.write(1, 1, "Default colors")?;
     worksheet.write(1, 3, "User colors")?;
-    worksheet.write_column(2, 1, scale_data)?;
-    worksheet.write_column(2, 3, scale_data)?;
+    worksheet.write_column(2, 1, data)?;
+    worksheet.write_column(2, 3, data)?;
 
     // Write a 3 color scale formats with standard Excel colors.
     let conditional_format = ConditionalFormat3ColorScale::new();

examples/doc_conditional_format_3color_set_minimum.rs

@@ -13,9 +13,9 @@ fn main() -> Result<(), XlsxError> {
     let worksheet = workbook.add_worksheet();
 
     // Write the worksheet data.
-    let scale_data = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
-    worksheet.write_column(2, 1, scale_data)?;
-    worksheet.write_column(2, 3, scale_data)?;
+    let data = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+    worksheet.write_column(2, 1, data)?;
+    worksheet.write_column(2, 3, data)?;
 
     // Write a 3 color scale formats with standard Excel colors. The conditional
     // format is applied from the lowest to the highest value.

examples/doc_conditional_format_databar.rs

@@ -0,0 +1,55 @@
+// SPDX-License-Identifier: MIT OR Apache-2.0
+//
+// Copyright 2022-2023, John McNamara, [email protected]
+
+//! Example of adding data bar type conditional formatting to a worksheet.
+
+use rust_xlsxwriter::{
+    ConditionalFormatDataBar, ConditionalFormatDataBarDirection, Workbook, XlsxError,
+};
+
+fn main() -> Result<(), XlsxError> {
+    // Create a new Excel file object.
+    let mut workbook = Workbook::new();
+    let worksheet = workbook.add_worksheet();
+
+    // Write some captions.
+    worksheet.write(1, 1, "Default")?;
+    worksheet.write(1, 3, "Default negative")?;
+    worksheet.write(1, 5, "User color")?;
+    worksheet.write(1, 7, "Changed direction")?;
+
+    // Write the worksheet data.
+    let data1 = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+    let data2 = [6, 4, 2, -2, -4, -6, -4, -2, 2, 4];
+    worksheet.write_column(2, 1, data1)?;
+    worksheet.write_column(2, 3, data2)?;
+    worksheet.write_column(2, 5, data1)?;
+    worksheet.write_column(2, 7, data1)?;
+
+    // Write a standard Excel data bar.
+    let conditional_format = ConditionalFormatDataBar::new();
+
+    worksheet.add_conditional_format(2, 1, 11, 1, &conditional_format)?;
+
+    // Write a standard Excel data bar with negative data
+    let conditional_format = ConditionalFormatDataBar::new();
+
+    worksheet.add_conditional_format(2, 3, 11, 3, &conditional_format)?;
+
+    // Write a data bar with a user defined fill color.
+    let conditional_format = ConditionalFormatDataBar::new().set_fill_color("009933");
+
+    worksheet.add_conditional_format(2, 5, 11, 5, &conditional_format)?;
+
+    // Write a data bar with the direction changed.
+    let conditional_format = ConditionalFormatDataBar::new()
+        .set_direction(ConditionalFormatDataBarDirection::RightToLeft);
+
+    worksheet.add_conditional_format(2, 7, 11, 7, &conditional_format)?;
+
+    // Save the file.
+    workbook.save("conditional_format.xlsx")?;
+
+    Ok(())
+}

examples/doc_conditional_format_databar_set_axis_color.rs

@@ -0,0 +1,34 @@
+// SPDX-License-Identifier: MIT OR Apache-2.0
+//
+// Copyright 2022-2023, John McNamara, [email protected]
+
+//! Example of adding a data bar type conditional formatting to a worksheet with
+//! a user defined axis color.
+
+use rust_xlsxwriter::{ConditionalFormatDataBar, Workbook, XlsxError};
+
+fn main() -> Result<(), XlsxError> {
+    // Create a new Excel file object.
+    let mut workbook = Workbook::new();
+    let worksheet = workbook.add_worksheet();
+
+    // Write the worksheet data.
+    let data = [6, 4, 2, -2, -4, -6, -4, -2, 2, 4];
+    worksheet.write_column(2, 1, data)?;
+    worksheet.write_column(2, 3, data)?;
+
+    // Write a standard Excel data bar.
+    let conditional_format = ConditionalFormatDataBar::new();
+
+    worksheet.add_conditional_format(2, 1, 11, 1, &conditional_format)?;
+
+    // Write a data bar with a user defined axis color.
+    let conditional_format = ConditionalFormatDataBar::new().set_axis_color("FF0000");
+
+    worksheet.add_conditional_format(2, 3, 11, 3, &conditional_format)?;
+
+    // Save the file.
+    workbook.save("conditional_format.xlsx")?;
+
+    Ok(())
+}

examples/doc_conditional_format_databar_set_axis_position.rs

@@ -0,0 +1,51 @@
+// SPDX-License-Identifier: MIT OR Apache-2.0
+//
+// Copyright 2022-2023, John McNamara, [email protected]
+
+//! Example of adding a data bar type conditional formatting to a worksheet
+//! with different axis positions.
+
+use rust_xlsxwriter::{
+    ConditionalFormatDataBar, ConditionalFormatDataBarAxisPosition, Workbook, XlsxError,
+};
+
+fn main() -> Result<(), XlsxError> {
+    // Create a new Excel file object.
+    let mut workbook = Workbook::new();
+    let worksheet = workbook.add_worksheet();
+
+    // Write the worksheet data.
+    let data1 = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+    let data2 = [6, 4, 2, -2, -4, -6, -4, -2, 2, 4];
+    worksheet.write_column(2, 1, data1)?;
+    worksheet.write_column(2, 3, data1)?;
+    worksheet.write_column(2, 5, data2)?;
+    worksheet.write_column(2, 7, data2)?;
+
+    // Write a standard Excel data bar.
+    let conditional_format = ConditionalFormatDataBar::new();
+
+    worksheet.add_conditional_format(2, 1, 11, 1, &conditional_format)?;
+
+    // Write a data bar with a midpoint axis.
+    let conditional_format = ConditionalFormatDataBar::new()
+        .set_axis_position(ConditionalFormatDataBarAxisPosition::Midpoint);
+
+    worksheet.add_conditional_format(2, 3, 11, 3, &conditional_format)?;
+
+    // Write a standard Excel data bar with negative data
+    let conditional_format = ConditionalFormatDataBar::new();
+
+    worksheet.add_conditional_format(2, 5, 11, 5, &conditional_format)?;
+
+    // Write a data bar without an axis.
+    let conditional_format = ConditionalFormatDataBar::new()
+        .set_axis_position(ConditionalFormatDataBarAxisPosition::None);
+
+    worksheet.add_conditional_format(2, 7, 11, 7, &conditional_format)?;
+
+    // Save the file.
+    workbook.save("conditional_format.xlsx")?;
+
+    Ok(())
+}