Add docs and an example for add_vba_project.

Issue #29

Readme.md

@@ -22,6 +22,7 @@ It supports features such as:
 - Charts.
 - Data validation and drop down lists.
 - Worksheet PNG/JPEG images.
+- Support for adding Macros.
 - Memory optimization mode for writing large files.
 - Source code available on [GitHub](https://github.com/jmcnamara/libxlsxwriter).
 - FreeBSD license.

dev/release/fix_example_docs.pl

@@ -43,6 +43,7 @@ my @examples = (
     [ 'doc_custom_properties.c','Example of setting custom doc properties' ],
     [ 'worksheet_protection.c', 'Example of enabling worksheet protection' ],
     [ 'hide_row_col.c',         'Example of hiding worksheet rows and columns' ],
+    [ 'macro.c',                'Example of adding a VBA macro to a workbook' ],
     [ 'panes.c',                'Example of how to create worksheet panes' ],
     [ 'chart.c',                'Example of a simple column chart' ],
     [ 'chart_area.c',           'Examples of area charts' ],

docs/Doxyfile

@@ -775,6 +775,7 @@ INPUT                  = src/mainpage.dox                     \
                          src/working_with_data_validation.dox \
                          src/working_with_outlines.dox        \
                          src/working_with_memory.dox          \
+                         src/working_with_macros.dox          \
                          src/examples.dox                     \
                          src/running_the_tests.dox            \
                          src/faq.dox                          \

docs/src/examples.dox

@@ -500,7 +500,7 @@ non-standard document properties.
 <table  width="600">
 <tr>
   <td>@ref doc_custom_properties.c "&lt;&lt; doc_custom_properties.c"</td>
-  <td align="right">@ref hide_row_col.c "hide_row_col.c &gt;&gt;"</td>
+  <td align="right">@ref macro.c "macro.c &gt;&gt;"</td>
 </tr>
 </table>
 
@@ -511,11 +511,27 @@ Example of setting Excel worksheet protection.
 
 
 
-@example hide_row_col.c
+@example macro.c
 
 <table  width="600">
 <tr>
   <td>@ref worksheet_protection.c "&lt;&lt; worksheet_protection.c"</td>
+  <td align="right">@ref hide_row_col.c "hide_row_col.c &gt;&gt;"</td>
+</tr>
+</table>
+
+Example adding a VBA macro to a workbook.
+
+@image html macros.png
+
+
+
+
+@example hide_row_col.c
+
+<table  width="600">
+<tr>
+  <td>@ref macro.c "&lt;&lt; macro.c"</td>
   <td align="right">@ref panes.c "panes.c &gt;&gt;"</td>
 </tr>
 </table>

docs/src/examples.txt

@@ -229,6 +229,13 @@ Example of setting Excel worksheet protection.
 
 @image html worksheet_protection.png
 
+##############################################################
+@example macro.c
+
+Example adding a VBA macro to a workbook.
+
+@image html macros.png
+
 ##############################################################
 @example hide_row_col.c
 

docs/src/mainpage.dox

@@ -21,6 +21,7 @@ features such as:
 - Charts.
 - Data validation and drop down lists.
 - Worksheet PNG/JPEG images.
+- Support for adding Macros.
 - Memory optimization mode for writing large files.
 - Source code available on [GitHub](https://github.com/jmcnamara/libxlsxwriter).
 - FreeBSD @ref license.
@@ -57,6 +58,7 @@ following sections for more information:
 - @ref working_with_data_validation
 - @ref working_with_outlines
 - @ref working_with_memory
+- @ref working_with_macros
 
 - @ref examples
 - @ref running_the_tests

docs/src/working_with_macros.dox

@@ -0,0 +1,151 @@
+/**
+@page working_with_macros Working with VBA Macros
+
+@tableofcontents
+
+This section explains how to add a VBA file containing functions or macros to
+an libxlsxwriter workbook.
+
+@dontinclude macro.c
+@skipline include
+@until    return
+@skipline }
+
+
+@image html macros.png
+
+@section ww_macros_xlsm_format The Excel XLSM file format
+
+An Excel `xlsm` file is exactly the same as an `xlsx` file except that is
+contains an additional `vbaProject.bin` file which contains functions and/or
+macros. Excel uses a different extension to differentiate between the two file
+formats since files containing macros are usually subject to additional
+security checks.
+
+
+@section ww_macros_include How VBA macros are included in libxlsxwriter files
+
+The `vbaProject.bin` file is a binary OLE COM container. This was the format
+used in older `xls` versions of Excel prior to Excel 2007. Unlike all of the
+other components of an xlsx/xlsm file the data isn't stored in XML
+format. Instead the functions and macros as stored as a pre-parsed binary
+format. As such it wouldn't be feasible to define macros and create a
+`vbaProject.bin` file from scratch (at least not in the remaining lifespan and
+interest levels of the author).
+
+Instead a workaround is used to extract `vbaProject.bin` files from existing
+xlsm files and then add these to libxlsxwriter generated files.
+
+
+@section ww_macros_extract The vba_extract.py utility
+
+The `vba_extract.py` Python utility is used to extract the `vbaProject.bin`
+binary from an Excel 2007+ xlsm file. The utility is included in the
+libxlsxwriter examples directory:
+
+    $ python examples/vba_extract.py macro_file.xlsm
+    Extracted: vbaProject.bin
+
+You can also install `vba_extract.py` into your system path by installing the
+Python xlsxwriter module:
+
+    $ pip install xlsxwriter
+    ...
+    $ vba_extract.py
+    Utility to extract a vbaProject.bin binary from an
+    Excel 2007+ xlsm macro file ...
+
+
+@section ww_macros_adding Adding the VBA macros to a libxlsxwriter file
+
+Once the `vbaProject.bin` file has been extracted it can be added to the
+libxlsxwriter workbook using the `workbook_add_vba_project()` function:
+
+@code
+    workbook_add_vba_project(workbook, "./vbaProject.bin");
+@endcode
+
+@note The name doesn't have to be `vbaProject.bin`. Any suitable path/name for
+an existing VBA bin file will do.
+
+If the VBA file contains functions you can then refer to them in calculations
+using `worksheet_write_formula()`:
+
+@code
+    worksheet_write_formula(0, 0, "=MyMortgageCalc(200000, 25)")
+@endcode
+
+Excel files that contain functions and macros should use an `xlsm` extension
+or else Excel will complain and possibly not open the file:
+
+@code
+    lxw_workbook *workbook = new_workbook("macro.xlsm");
+@endcode
+
+
+@section ww_macros_codenames Setting the VBA codenames
+
+VBA macros generally refer to workbook and worksheet objects. If the VBA
+codenames aren't specified explicitly then libxlsxwriter will use the Excel
+defaults of `ThisWorkbook` and `Sheet1`, `Sheet2` etc.
+
+If the macro uses other codenames you can set them using the
+`workbook_set_vba_name()` and `worksheet_set_vba_name()` functions as follows:
+
+@code
+    // Set the VBA codenames for the workbook and any worksheets.
+    workbook_set_vba_name (workbook,  "MyWorkbook");
+    worksheet_set_vba_name(worksheet, "MySheet1");
+    worksheet_set_vba_name(worksheet, "MySheet2");
+@endcode
+
+@note This step is particularly important for macros created with non-English
+versions of Excel.
+
+You can find the names that are used in the VBA editor or by unzipping the
+`xlsm` file and grepping the files. The following shows how to do that using
+[libxml's xmllint](http://xmlsoft.org/xmllint.html) to format the XML for
+clarity:
+
+    $ unzip myfile.xlsm -d myfile
+    $ xmllint --format `find myfile -name "*.xml" | xargs` | grep "Pr.*codeName"
+
+      <workbookPr codeName="MyWorkbook" defaultThemeVersion="124226"/>
+      <sheetPr codeName="MySheet1"/>
+
+
+@section ww_macros_debugging What to do if it doesn't work
+
+The libxlsxwriter test suite contains several tests to ensure that this feature
+works and there is a working example as shown above. However, there is no
+guarantee that it will work in all cases. Some effort may be required and some
+knowledge of VBA will certainly help. If things don't work out here are some
+things to try:
+
+1. Start with a simple macro file, ensure that it works and then add complexity.
+
+2. Check the code names that macros use to refer to the workbook and
+   worksheets (see the previous section above). In general VBA uses a code
+   name of `ThisWorkbook` to refer to the current workbook and the sheet name
+   (such as `Sheet1`) to refer to the worksheets. These are the defaults used
+   by libxlsxwriter. If the macro uses other names, or the macro was extracted
+   from an non-English language version of Excel, then you can specify the
+   appropriate names using the `workbook_set_vba_name()` and
+   `worksheet_set_vba_name()` functions:
+   @code
+       // Set the VBA codenames for the workbook and any worksheets.
+       workbook_set_vba_name (workbook,  "MyWorkbook");
+       worksheet_set_vba_name(worksheet, "MySheet1");
+       worksheet_set_vba_name(worksheet, "MySheet2");
+   @endcode
+
+3. Try to extract the macros from an Excel 2007 file. The method should work
+   with macros from later versions (it was also tested with Excel 2010
+   macros). However there may be features in the macro files of more recent
+   version of Excel that aren't backward compatible.
+
+
+Next: @ref examples
+
+
+*/

docs/src/working_with_memory.dox

@@ -67,7 +67,7 @@ Currently the library isn't highly optimized. Also, the library is currently
 single threaded.
 
 
-Next: @ref examples
+Next: @ref working_with_macros
 
 
 */

examples/macro.c

@@ -0,0 +1,25 @@
+/*****************************************************************************
+ *
+ * An example of adding macros to a libxlsxwriter file using a VBA project
+ * file extracted from an existing Excel .xlsm file.
+ *
+ * The vba_extract.py utility from the libxlsxwriter examples directory can be
+ * used to extract the vbaProject.bin file.
+ *
+ * Copyright 2014-2018, John McNamara, jmcnamara@cpan.org
+ */
+
+#include "xlsxwriter.h"
+
+int main() {
+
+    lxw_workbook  *workbook  = new_workbook("macro.xlsm");
+    lxw_worksheet *worksheet = workbook_add_worksheet(workbook, NULL);
+
+    /* Add a macro that will execute when the file is opened. */
+    workbook_add_vba_project(workbook, "vbaProject.bin");
+
+    worksheet_write_string(worksheet, 0, 0, "Overwrite this", NULL);
+
+    return workbook_close(workbook);
+}

include/xlsxwriter/workbook.h

@@ -863,7 +863,19 @@ lxw_error workbook_validate_sheet_name(lxw_workbook *workbook,
  *     workbook_add_vba_project(workbook, "vbaProject.bin");
  * @endcode
  *
- * Only one `vbaProject.bin file` can be added per workbook.
+ * Only one `vbaProject.bin file` can be added per workbook. The name doesn't
+ * have to be `vbaProject.bin`. Any suitable path/name for an existing VBA bin
+ * file will do.
+ *
+ * Once you add a VBA project had been add to an libxlsxwriter workbook you
+ * should ensure that the file extension is `.xlsm` to prevent Excel from
+ * giving a warning when it opens the file:
+ *
+ * @code
+ *     lxw_workbook *workbook = new_workbook("macro.xlsm");
+ * @endcode
+ *
+ * See also @ref working_with_macros
  *
  * @return A #lxw_error.
  */
@@ -878,13 +890,17 @@ lxw_error workbook_add_vba_project(lxw_workbook *workbook,
  *
  * The `workbook_set_vba_name()` function can be used to set the VBA name for
  * the workbook. This is sometimes required when a vbaProject macro included
- * via `workbook_add_vba_project()` refers to the workbook.
+ * via `workbook_add_vba_project()` refers to the workbook by a name other
+ * than `ThisWorkbook`.
  *
  * @code
  *     workbook_set_vba_name(workbook, "MyWorkbook");
  * @endcode
  *
- * The most common Excel VBA name for a workbook is `ThisWorkbook`.
+ * If an Excel VBA name for the workbook isn't specified then libxlsxwriter
+ * will use `ThisWorkbook`.
+ *
+ * See also @ref working_with_macros
  *
  * @return A #lxw_error.
  */

include/xlsxwriter/worksheet.h

@@ -3243,7 +3243,8 @@ void worksheet_set_default_row(lxw_worksheet *worksheet, double height,
  *
  * The `worksheet_set_vba_name()` function can be used to set the VBA name for
  * the worksheet. This is sometimes required when a vbaProject macro included
- * via `workbook_add_vba_project()` refers to the worksheet.
+ * via `workbook_add_vba_project()` refers to the worksheet by a name other
+ * than the worksheet name:
  *
  * @code
  *     workbook_set_vba_name (workbook,  "MyWorkbook");
@@ -3254,6 +3255,8 @@ void worksheet_set_default_row(lxw_worksheet *worksheet, double height,
  * However, this can be changed in the VBA environment or if the the macro was
  * extracted from a foreign language version of Excel.
  *
+ * See also @ref working_with_macros
+ *
  * @return A #lxw_error.
  */
 lxw_error worksheet_set_vba_name(lxw_worksheet *worksheet, const char *name);

libxlsxwriter.podspec

@@ -18,6 +18,7 @@ Pod::Spec.new do |s|
                             * Charts.
                             * Data validation and drop down lists.
                             * Worksheet PNG/JPEG images.
+                            * Support for adding Macros.
                             * Memory optimisation mode for writing large files.
                             * Source code available on [GitHub](https://github.com/jmcnamara/libxlsxwriter).
                             * FreeBSD license.