Added example of setting a watermark in Excel.

.gitignore

@@ -38,8 +38,7 @@ docs/latex
 _temp.c
 examples/*
 !examples/*.c
-!examples/logo.png
+!examples/*.png
-!examples/logo_small.png
 !examples/Makefile
 !examples/vbaProject.bin
 cov-int

dev/release/fix_example_docs.pl

@@ -42,6 +42,7 @@ my @examples = (
     [ 'defined_name.c',         'Example of how to create defined names' ],
     [ 'outline.c',              'Example of grouping and outlines' ],
     [ 'outline_collapsed.c',    'Example of grouping and collapsed outlines' ],
+    [ 'watermark.c',            'Example of how to set a watermark image for a worksheet' ],
     [ 'background.c',           'Example of how to set the background image for a worksheet' ],
     [ 'tab_colors.c',           'Example of how to set worksheet tab colors' ],
     [ 'diagonal_border.c',      'Example of how to set a worksheet cell diagonal border.' ],

docs/src/examples.dox

@@ -509,7 +509,7 @@ Example of how to generate Excel outlines and grouping.
 <table  width="600">
 <tr>
   <td>@ref outline.c "&lt;&lt; outline.c"</td>
-  <td align="right">@ref background.c "background.c &gt;&gt;"</td>
+  <td align="right">@ref watermark.c "watermark.c &gt;&gt;"</td>
 </tr>
 </table>
 
@@ -521,11 +521,29 @@ mainly on collapsed outlines.
 
 
 
-@example background.c
+@example watermark.c
 
 <table  width="600">
 <tr>
   <td>@ref outline_collapsed.c "&lt;&lt; outline_collapsed.c"</td>
+  <td align="right">@ref background.c "background.c &gt;&gt;"</td>
+</tr>
+</table>
+
+Example of how to a watermark image for a worksheet using the method suggested
+in the Microsoft documentation:
+https://support.microsoft.com/en-us/office/add-a-watermark-in-excel-a372182a-d733-484e-825c-18ddf3edf009
+
+@image html worksheet_watermark.png
+
+
+
+
+@example background.c
+
+<table  width="600">
+<tr>
+  <td>@ref watermark.c "&lt;&lt; watermark.c"</td>
   <td align="right">@ref tab_colors.c "tab_colors.c &gt;&gt;"</td>
 </tr>
 </table>

docs/src/examples.txt

@@ -239,6 +239,15 @@ mainly on collapsed outlines.
 
 @image html outline2.png
 
+##############################################################
+@example watermark.c
+
+Example of how to a watermark image for a worksheet using the method suggested
+in the Microsoft documentation:
+https://support.microsoft.com/en-us/office/add-a-watermark-in-excel-a372182a-d733-484e-825c-18ddf3edf009
+
+@image html worksheet_watermark.png
+
 ##############################################################
 @example background.c
 

examples/watermark.c

@@ -0,0 +1,26 @@
+/*
+ * An example of adding a worksheet watermark image using libxlsxwriter. This
+ * is based on the method of putting an image in the worksheet header as
+ * suggested in the Microsoft documentation:
+ * https://support.microsoft.com/en-us/office/add-a-watermark-in-excel-a372182a-d733-484e-825c-18ddf3edf009
+ *
+ * Copyright 2014-2021, John McNamara, jmcnamara@cpan.org
+ *
+ */
+
+#include "xlsxwriter.h"
+
+int main() {
+
+    lxw_workbook  *workbook  = workbook_new("watermark.xlsx");
+    lxw_worksheet *worksheet = workbook_add_worksheet(workbook, NULL);
+
+
+    /* Set a worksheet header with the watermark image. */
+    lxw_header_footer_options header_options = {.image_center = "watermark.png"};
+    worksheet_set_header_opt(worksheet, "&C&[Picture]", &header_options);
+
+    workbook_close(workbook);
+
+    return 0;
+}

test/functional/src/test_header_image20.c

@@ -0,0 +1,22 @@
+/*****************************************************************************
+ * Test cases for libxlsxwriter.
+ *
+ * Test to compare output against Excel files.
+ *
+ * Copyright 2014-2022, John McNamara, jmcnamara@cpan.org
+ *
+ */
+
+#include "xlsxwriter.h"
+
+int main() {
+
+    lxw_workbook  *workbook  = workbook_new("test_header_image20.xlsx");
+    lxw_worksheet *worksheet = workbook_add_worksheet(workbook, NULL);
+
+    lxw_header_footer_options header_options = {.image_center = "images/watermark.png"};
+
+    worksheet_set_header_opt(worksheet, "&C&G", &header_options);
+
+    return workbook_close(workbook);
+}

test/functional/test_header_image.py

@@ -100,6 +100,10 @@ class TestCompareXLSXFiles(base_test_class.XLSXBaseTest):
         self.ignore_elements = {'xl/worksheets/sheet1.xml': ['<pageMargins', '<pageSetup']}
         self.run_exe_test('test_header_image19')
 
+    def test_header_image20(self):
+        self.ignore_elements = {'xl/worksheets/sheet1.xml': ['<pageMargins', '<pageSetup']}
+        self.run_exe_test('test_header_image20')
+                          
     # Test format strings with &[Picture] instead of &G.
     def test_header_image51(self):
         self.ignore_elements = {'xl/worksheets/sheet1.xml': ['<pageMargins', '<pageSetup']}