Add option to set read-only mode when opening a file.

Added the worksheet read_only_recommended() method to set the Excel
"Read-only Recommended" option that is available when saving a file.

include/xlsxwriter/app.h

@@ -46,6 +46,7 @@ typedef struct lxw_app {
 
     uint32_t num_heading_pairs;
     uint32_t num_part_names;
+    uint8_t doc_security;
 
 } lxw_app;
 

include/xlsxwriter/workbook.h

@@ -314,6 +314,7 @@ typedef struct lxw_workbook {
     uint16_t fill_count;
     uint8_t optimize;
     uint16_t max_url_length;
+    uint8_t read_only;
 
     uint8_t has_png;
     uint8_t has_jpeg;
@@ -984,6 +985,27 @@ lxw_error workbook_add_vba_project(lxw_workbook *workbook,
  */
 lxw_error workbook_set_vba_name(lxw_workbook *workbook, const char *name);
 
+/**
+ * @brief Add a recommendation to open the file in "read-only" mode.
+ *
+ * @param workbook
+ *
+ * This function can be used to set the Excel "Read-only Recommended" option
+ * that is available when saving a file. This presents the user of the file
+ * with an option to open it in "read-only" mode. This means that any changes
+ * to the file can't be saved back to the same file and must be saved to a new
+ * file. It can be set as follows:
+ *
+ * @code
+ *     workbook_read_only_recommended(workbook);
+ * @endcode
+ *
+ * Which will raise a dialog like the following when opening the file:
+ *
+ * @image html read_only.png
+ */
+void workbook_read_only_recommended(lxw_workbook *workbook);
+
 void lxw_workbook_free(lxw_workbook *workbook);
 void lxw_workbook_assemble_xml_file(lxw_workbook *workbook);
 void lxw_workbook_set_default_xf_indices(lxw_workbook *workbook);

src/app.c

@@ -132,7 +132,10 @@ _write_application(lxw_app *self)
 STATIC void
 _write_doc_security(lxw_app *self)
 {
-    lxw_xml_data_element(self->file, "DocSecurity", "0", NULL);
+    if (self->doc_security == 2)
+        lxw_xml_data_element(self->file, "DocSecurity", "2", NULL);
+    else
+        lxw_xml_data_element(self->file, "DocSecurity", "0", NULL);
 }
 
 /*

src/packager.c

@@ -706,6 +706,8 @@ _write_app_file(lxw_packager *self)
     /* Set the app/doc properties. */
     app->properties = workbook->properties;
 
+    app->doc_security = workbook->read_only;
+
     lxw_app_assemble_xml_file(app);
 
     err = _add_file_to_zip(self, app->file, "docProps/app.xml");

src/workbook.c

@@ -1410,6 +1410,26 @@ _write_file_version(lxw_workbook *self)
     LXW_FREE_ATTRIBUTES();
 }
 
+/*
+ * Write the <fileSharing> element.
+ */
+STATIC void
+_workbook_write_file_sharing(lxw_workbook *self)
+{
+    struct xml_attribute_list attributes;
+    struct xml_attribute *attribute;
+
+    if (self->read_only == 0)
+        return;
+
+    LXW_INIT_ATTRIBUTES();
+    LXW_PUSH_ATTRIBUTES_STR("readOnlyRecommended", "1");
+
+    lxw_xml_empty_tag(self->file, "fileSharing", &attributes);
+
+    LXW_FREE_ATTRIBUTES();
+}
+
 /*
  * Write the <workbookPr> element.
  */
@@ -1608,6 +1628,9 @@ lxw_workbook_assemble_xml_file(lxw_workbook *self)
     /* Write the XLSX file version. */
     _write_file_version(self);
 
+    /* Write the fileSharing element. */
+    _workbook_write_file_sharing(self);
+
     /* Write the workbook properties. */
     _write_workbook_pr(self);
 
@@ -2543,3 +2566,12 @@ workbook_set_vba_name(lxw_workbook *self, const char *name)
 
     return LXW_NO_ERROR;
 }
+
+/*
+ * Set the Excel "Read-only recommended" save option.
+ */
+void
+workbook_read_only_recommended(lxw_workbook *self)
+{
+    self->read_only = 2;
+}

test/functional/src/test_protect07.c

@@ -0,0 +1,20 @@
+/*****************************************************************************
+ * Test cases for libxlsxwriter.
+ *
+ * Test to compare output against Excel files.
+ *
+ * Copyright 2014-2020, John McNamara, jmcnamara@cpan.org
+ *
+ */
+
+#include "xlsxwriter.h"
+
+int main() {
+
+    lxw_workbook  *workbook  = workbook_new("test_protect07.xlsx");
+    workbook_add_worksheet(workbook, NULL);
+
+    workbook_read_only_recommended(workbook);
+
+    return workbook_close(workbook);
+}

test/functional/test_protect.py

@@ -21,3 +21,6 @@ class TestCompareXLSXFiles(base_test_class.XLSXBaseTest):
 
     def test_protect03(self):
         self.run_exe_test('test_protect03')
+
+    def test_protect07(self):
+        self.run_exe_test('test_protect07')