image: add docs for background images

CHANGELOG.md

@@ -21,7 +21,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   See [Grouping and outlining data].
 
   [Grouping and outlining data]: https://docs.rs/rust_xlsxwriter/latest/rust_xlsxwriter/worksheet/index.html#grouping-and-outlining-data
-
+  <br>
+  <br>
 
 - Added support for ignoring Excel worksheet cell errors.
 
@@ -38,6 +39,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
   [`Worksheet::ignore_error()`]: https://docs.rs/rust_xlsxwriter/latest/rust_xlsxwriter/worksheet/struct.Worksheet.html#method.ignore_error
   [`Worksheet::ignore_error_range()`]: https://docs.rs/rust_xlsxwriter/latest/rust_xlsxwriter/worksheet/struct.Worksheet.html#method.ignore_error_range
+  <br>
+  <br>
+
+- Added support for worksheet background images via the [`Worksheet::insert_background_image()`] method.
+
+  <img src="https://rustxlsxwriter.github.io/images/app_background_image.png">
+
+  [`Worksheet::insert_background_image()`]: https://docs.rs/rust_xlsxwriter/latest/rust_xlsxwriter/worksheet/struct.Worksheet.html#method.insert_background_image
+
 
 
 ## [0.82.0] - 2025-01-29

README.md

@@ -145,7 +145,8 @@ frequently.
 Recent changes:
 
 - Added worksheet outline groupings.
-- Added support for Worksheet checkboxes.
+- Added worksheet background images.
+- Added support for worksheet checkboxes.
 - Added `constant_memory` mode.
 
 See the full [Release Notes and Changelog].

examples/Readme.md

@@ -13,14 +13,20 @@ documentation and generally show how an individual function works.
   write simple array formulas.
 
 * `app_autofilter.rs` - An example of how to create autofilters with the
-  `rust_xlsxwriter` library. An autofilter is a way of adding drop down lists
-  to the headers of a 2D range of worksheet data. This allows users to
-  filter the data based on simple criteria so that some data is shown and
-  some is hidden.
+  `rust_xlsxwriter` library. An autofilter is a way of adding drop down
+  lists to the headers of a 2D range of worksheet data. This allows users
+  to filter the data based on simple criteria so that some data is shown
+  and some is hidden.
 
 * `app_autofit.rs` - An example of using simulated autofit to automatically
   adjust the width of worksheet columns based on the data in the cells.
 
+* `app_background_image.rs` - An example of inserting a background image
+  into a worksheet using `rust_xlsxwriter`. See also the `app_watermark.rs`
+  example which shows how to set a watermark via the header image of a
+  worksheet. That is the way that the Microsoft documentation recommends to
+  set a watermark in Excel.
+
 * `app_chart.rs` - A simple chart example using the `rust_xlsxwriter`
   library.
 
@@ -78,12 +84,12 @@ documentation and generally show how an individual function works.
   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.
+  `rust_xlsxwriter` library. Note, Volume variants of the Excel stock
+  charts aren't currently supported but will be in a future release.
 
 * `app_chart_styles.rs` - An example showing all 48 default chart styles
-  available in Excel 2007 using `rust_xlsxwriter`. Note, these styles are not
-  the same as the styles available in Excel 2013 and later.
+  available in Excel 2007 using `rust_xlsxwriter`. Note, these styles are
+  not the same as the styles available in Excel 2013 and later.
 
 * `app_chart_tutorial1.rs` - An example of creating a simple chart using
   the `rust_xlsxwriter` library.
@@ -107,9 +113,9 @@ documentation and generally show how an individual function works.
   available in the `rust_xlsxwriter` library.
 
 * `app_conditional_formatting.rs` - Example of how to add conditional
-  formatting to a worksheet using the `rust_xlsxwriter` library. Conditional
-  formatting allows you to apply a format to a cell or a range of cells
-  based on user defined rule.
+  formatting to a worksheet using the `rust_xlsxwriter` library.
+  Conditional formatting allows you to apply a format to a cell or a range
+  of cells based on user defined rule.
 
 * `app_data_validation.rs` - Example of how to add data validation and
   dropdown lists using the `rust_xlsxwriter` library. Data validation is a
@@ -146,8 +152,8 @@ documentation and generally show how an individual function works.
   in an in memory Vec<u8> buffer using the `rust_xlsxwriter` library.
 
 * `app_formatting.rs` - An example of the various cell formatting options
-  that are available in the `rust_xlsxwriter` library. These are laid out on
-  worksheets that correspond to the sections of the Excel "Format Cells"
+  that are available in the `rust_xlsxwriter` library. These are laid out
+  on worksheets that correspond to the sections of the Excel "Format Cells"
   dialog.
 
 * `app_grouped_columns.rs` - An example of how to group columns into
@@ -191,9 +197,9 @@ documentation and generally show how an individual function works.
   used to extract the `vbaProject.bin` file.
 
 * `app_memory_test.rs` - Simple performance test and memory usage program
-  for `rust_xlsxwriter`. It writes alternate cells of strings and numbers. It
-  defaults to 4,000 rows x 40 columns. The number of rows and the "constant
-  memory" mode can be optionally set. usage:
+  for `rust_xlsxwriter`. It writes alternate cells of strings and numbers.
+  It defaults to 4,000 rows x 40 columns. The number of rows and the
+  "constant memory" mode can be optionally set. usage:
   ./target/release/examples/app_perf_test [num_rows] [--constant-memory]
 
 * `app_merge_range.rs` - An example of creating merged ranges in a
@@ -205,10 +211,10 @@ documentation and generally show how an individual function works.
 * `app_panes.rs` - A simple example of setting some "freeze" panes in
   worksheets using the `rust_xlsxwriter` library.
 
-* `app_perf_test.rs` - Simple performance test program for `rust_xlsxwriter`.
-  It writes alternate cells of strings and numbers. It defaults to 4,000
-  rows x 40 columns. usage: ./target/release/examples/app_perf_test
-  [num_rows]
+* `app_perf_test.rs` - Simple performance test program for
+  `rust_xlsxwriter`. It writes alternate cells of strings and numbers. It
+  defaults to 4,000 rows x 40 columns. usage:
+  ./target/release/examples/app_perf_test [num_rows]
 
 * `app_rich_strings.rs` - An example of using the `rust_xlsxwriter` library
   to write "rich" multi-format strings in worksheet cells.
@@ -259,8 +265,8 @@ documentation and generally show how an individual function works.
   spreadsheet using `rust_xlsxwriter`. Part 5 of a tutorial.
 
 * `app_watermark.rs` - An example of adding a worksheet watermark image
-  using the `rust_xlsxwriter` library. This is based on the method of putting
-  an image in the worksheet header as suggested in the Microsoft
+  using the `rust_xlsxwriter` library. This is based on the method of
+  putting an image in the worksheet header as suggested in the Microsoft
   documentation.
 
 * `app_worksheet_protection.rs` - Example of cell locking and formula
@@ -597,8 +603,8 @@ documentation and generally show how an individual function works.
 * `doc_chart_set_width.rs` - A simple chart example using the
   `rust_xlsxwriter` library.
 
-* `doc_chart_simple.rs` - A simple chart example using the `rust_xlsxwriter`
-  library.
+* `doc_chart_simple.rs` - A simple chart example using the
+  `rust_xlsxwriter` library.
 
 * `doc_chart_solid_fill.rs` - An example of setting a solid fill for a
   chart element.

examples/app_background_image.rs

@@ -0,0 +1,34 @@
+// SPDX-License-Identifier: MIT OR Apache-2.0
+//
+// Copyright 2022-2025, John McNamara, [email protected]
+
+//! An example of inserting a background image into a worksheet using
+//! `rust_xlsxwriter`.
+//!
+//! See also the `app_watermark.rs` example which shows how to set a watermark
+//! via the header image of a worksheet. That is the way that the Microsoft
+//! documentation recommends to set a watermark in Excel.
+
+use rust_xlsxwriter::{Image, Workbook, XlsxError};
+
+fn main() -> Result<(), XlsxError> {
+    // Create a new Excel file object.
+    let mut workbook = Workbook::new();
+
+    // Add a worksheet to the workbook.
+    let worksheet = workbook.add_worksheet();
+
+    // The image may not be visible unless the view is large.
+    worksheet.write(0, 0, "Scroll down and right to see the background image")?;
+
+    // Create a new image object.
+    let image = Image::new("examples/watermark.png")?;
+
+    // Insert the background image.
+    worksheet.insert_background_image(&image);
+
+    // Save the file to disk.
+    workbook.save("background_image.xlsx")?;
+
+    Ok(())
+}

src/cookbook.rs

@@ -30,44 +30,45 @@ cargo run --example app_demo  # or any other example
 15. [Insert images: Embedding an image in a cell](#insert-images-embedding-an-image-in-a-cell)
 16. [Insert images: Inserting images to fit a cell](#insert-images-inserting-images-to-fit-a-cell)
 17. [Adding a watermark: Adding a watermark to a worksheet by adding an image to the header](#adding-a-watermark-adding-a-watermark-to-a-worksheet-by-adding-an-image-to-the-header)
-18. [Chart: Simple: Simple getting started chart example](#chart-simple-simple-getting-started-chart-example)
-19. [Chart: Area: Excel Area chart example](#chart-area-excel-area-chart-example)
-20. [Chart: Bar: Excel Bar chart example](#chart-bar-excel-bar-chart-example)
-21. [Chart: Column: Excel Column chart example](#chart-column-excel-column-chart-example)
-22. [Chart: Line: Excel Line chart example](#chart-line-excel-line-chart-example)
-23. [Chart: Scatter: Excel Scatter chart example](#chart-scatter-excel-scatter-chart-example)
-24. [Chart: Pie: Excel Pie chart example](#chart-pie-excel-pie-chart-example)
-25. [Chart: Doughnut: Excel Doughnut chart example](#chart-doughnut-excel-doughnut-chart-example)
-26. [Chart: Radar: Excel Radar chart example](#chart-radar-excel-radar-chart-example)
-27. [Chart: Stock: Excel Stock chart example](#chart-stock-excel-stock-chart-example)
-28. [Chart: Using a secondary axis](#chart-using-a-secondary-axis)
-29. [Chart: Create a combined chart](#chart-create-a-combined-chart)
-30. [Chart: Create a combined pareto chart](#chart-create-a-combined-pareto-chart)
-31. [Chart: Pattern Fill: Example of a chart with Pattern Fill](#chart-pattern-fill-example-of-a-chart-with-pattern-fill)
-32. [Chart: Gradient Fill: Example of a chart with Gradient Fill](#chart-gradient-fill-example-of-a-chart-with-gradient-fill)
-33. [Chart: Styles: Example of setting default chart styles](#chart-styles-example-of-setting-default-chart-styles)
-34. [Chart: Chart data table](#chart-chart-data-table)
-35. [Chart: Chart data tools](#chart-chart-data-tools)
-36. [Chart: Gauge Chart](#chart-gauge-chart)
-37. [Chart: Chartsheet](#chart-chartsheet)
-38. [Grouped Rows: Create a grouped row outline](#grouped-rows-create-a-grouped-row-outline)
-39. [Grouped Columns: Create a grouped column outline](#grouped-columns-create-a-grouped-column-outline)
-40. [Textbox: Inserting Checkboxes in worksheets](#textbox-inserting-checkboxes-in-worksheets)
-41. [Textbox: Inserting Textboxes in worksheets](#textbox-inserting-textboxes-in-worksheets)
-42. [Textbox: Ignore Excel cell errors](#textbox-ignore-excel-cell-errors)
-43. [Sparklines: simple example](#sparklines-simple-example)
-44. [Sparklines: advanced example](#sparklines-advanced-example)
-45. [Traits: Extending generic `write()` to handle user data types](#traits-extending-generic-write-to-handle-user-data-types)
-46. [Macros: Adding macros to a workbook](#macros-adding-macros-to-a-workbook)
-47. [Defined names: using user defined variable names in worksheets](#defined-names-using-user-defined-variable-names-in-worksheets)
-48. [Cell Protection: Setting cell protection in a worksheet](#cell-protection-setting-cell-protection-in-a-worksheet)
-49. [Document Properties: Setting document metadata properties for a workbook](#document-properties-setting-document-metadata-properties-for-a-workbook)
-50. [Document Properties: Setting the Sensitivity Label](#document-properties-setting-the-sensitivity-label)
-51. [Headers and Footers: Shows how to set headers and footers](#headers-and-footers-shows-how-to-set-headers-and-footers)
-52. [Hyperlinks: Add hyperlinks to a worksheet](#hyperlinks-add-hyperlinks-to-a-worksheet)
-53. [Freeze Panes: Example of setting freeze panes in worksheets](#freeze-panes-example-of-setting-freeze-panes-in-worksheets)
-54. [Dynamic array formulas: Examples of dynamic arrays and formulas](#dynamic-array-formulas-examples-of-dynamic-arrays-and-formulas)
-55. [Excel `LAMBDA()` function: Example of using the Excel 365 `LAMBDA()` function](#excel-lambda-function-example-of-using-the-excel-365-lambda-function)
+18. [Adding a watermark: Adding a watermark to a worksheet by adding a background image](#adding-a-watermark-adding-a-watermark-to-a-worksheet-by-adding-a-background-image)
+19. [Chart: Simple: Simple getting started chart example](#chart-simple-simple-getting-started-chart-example)
+20. [Chart: Area: Excel Area chart example](#chart-area-excel-area-chart-example)
+21. [Chart: Bar: Excel Bar chart example](#chart-bar-excel-bar-chart-example)
+22. [Chart: Column: Excel Column chart example](#chart-column-excel-column-chart-example)
+23. [Chart: Line: Excel Line chart example](#chart-line-excel-line-chart-example)
+24. [Chart: Scatter: Excel Scatter chart example](#chart-scatter-excel-scatter-chart-example)
+25. [Chart: Pie: Excel Pie chart example](#chart-pie-excel-pie-chart-example)
+26. [Chart: Doughnut: Excel Doughnut chart example](#chart-doughnut-excel-doughnut-chart-example)
+27. [Chart: Radar: Excel Radar chart example](#chart-radar-excel-radar-chart-example)
+28. [Chart: Stock: Excel Stock chart example](#chart-stock-excel-stock-chart-example)
+29. [Chart: Using a secondary axis](#chart-using-a-secondary-axis)
+30. [Chart: Create a combined chart](#chart-create-a-combined-chart)
+31. [Chart: Create a combined pareto chart](#chart-create-a-combined-pareto-chart)
+32. [Chart: Pattern Fill: Example of a chart with Pattern Fill](#chart-pattern-fill-example-of-a-chart-with-pattern-fill)
+33. [Chart: Gradient Fill: Example of a chart with Gradient Fill](#chart-gradient-fill-example-of-a-chart-with-gradient-fill)
+34. [Chart: Styles: Example of setting default chart styles](#chart-styles-example-of-setting-default-chart-styles)
+35. [Chart: Chart data table](#chart-chart-data-table)
+36. [Chart: Chart data tools](#chart-chart-data-tools)
+37. [Chart: Gauge Chart](#chart-gauge-chart)
+38. [Chart: Chartsheet](#chart-chartsheet)
+39. [Grouped Rows: Create a grouped row outline](#grouped-rows-create-a-grouped-row-outline)
+40. [Grouped Columns: Create a grouped column outline](#grouped-columns-create-a-grouped-column-outline)
+41. [Textbox: Inserting Checkboxes in worksheets](#textbox-inserting-checkboxes-in-worksheets)
+42. [Textbox: Inserting Textboxes in worksheets](#textbox-inserting-textboxes-in-worksheets)
+43. [Textbox: Ignore Excel cell errors](#textbox-ignore-excel-cell-errors)
+44. [Sparklines: simple example](#sparklines-simple-example)
+45. [Sparklines: advanced example](#sparklines-advanced-example)
+46. [Traits: Extending generic `write()` to handle user data types](#traits-extending-generic-write-to-handle-user-data-types)
+47. [Macros: Adding macros to a workbook](#macros-adding-macros-to-a-workbook)
+48. [Defined names: using user defined variable names in worksheets](#defined-names-using-user-defined-variable-names-in-worksheets)
+49. [Cell Protection: Setting cell protection in a worksheet](#cell-protection-setting-cell-protection-in-a-worksheet)
+50. [Document Properties: Setting document metadata properties for a workbook](#document-properties-setting-document-metadata-properties-for-a-workbook)
+51. [Document Properties: Setting the Sensitivity Label](#document-properties-setting-the-sensitivity-label)
+52. [Headers and Footers: Shows how to set headers and footers](#headers-and-footers-shows-how-to-set-headers-and-footers)
+53. [Hyperlinks: Add hyperlinks to a worksheet](#hyperlinks-add-hyperlinks-to-a-worksheet)
+54. [Freeze Panes: Example of setting freeze panes in worksheets](#freeze-panes-example-of-setting-freeze-panes-in-worksheets)
+55. [Dynamic array formulas: Examples of dynamic arrays and formulas](#dynamic-array-formulas-examples-of-dynamic-arrays-and-formulas)
+56. [Excel `LAMBDA()` function: Example of using the Excel 365 `LAMBDA()` function](#excel-lambda-function-example-of-using-the-excel-365-lambda-function)
 
 
 # Hello World: Simple getting started example
@@ -2607,6 +2608,48 @@ fn main() -> Result<(), XlsxError> {
 ```
 
 
+# Adding a watermark: Adding a watermark to a worksheet by adding a background image
+
+An example of adding a background image to a worksheet. In this case it is used as a watermark.
+
+See also the previous example where a watermark is created by putting an image
+in the worksheet header.
+
+**Image of the output file:**
+
+<img src="https://rustxlsxwriter.github.io/images/app_background_image.png">
+
+**Code to generate the output file:**
+
+```rust
+// Sample code from examples/app_background_image.rs
+
+use rust_xlsxwriter::{Image, Workbook, XlsxError};
+
+fn main() -> Result<(), XlsxError> {
+    // Create a new Excel file object.
+    let mut workbook = Workbook::new();
+
+    // Add a worksheet to the workbook.
+    let worksheet = workbook.add_worksheet();
+
+    // The image may not be visible unless the view is large.
+    worksheet.write(0, 0, "Scroll down and right to see the background image")?;
+
+    // Create a new image object.
+    let image = Image::new("examples/watermark.png")?;
+
+    // Insert the background image.
+    worksheet.insert_background_image(&image);
+
+    // Save the file to disk.
+    workbook.save("background_image.xlsx")?;
+
+    Ok(())
+}
+```
+
+
 # Chart: Simple: Simple getting started chart example
 
 Getting started example of creating simple Excel charts.
@@ -6580,7 +6623,7 @@ fn main() -> Result<(), XlsxError> {
         .set_company("Rust Solutions Inc")
         .set_category("Sample spreadsheets")
         .set_keywords("Sample, Example, Properties")
-        .set_comment("Created with Rust and rust_xlsxwriter");
+        .set_comment("Created with Rust and `rust_xlsxwriter`");
 
     workbook.set_properties(&properties);