Add docs for rich strings.

Issue #37

dev/release/fix_example_docs.pl

@@ -23,10 +23,12 @@ my @examples = (
     [ 'dates_and_times02.c',    'Writing dates and times with datetime' ],
     [ 'dates_and_times03.c',    'Dates and times with different formats' ],
     [ 'hyperlinks.c',           'A example of writing urls/hyperlinks' ],
+    [ 'rich_strings.c',         'A example of writing "rich" multi-format strings' ],
     [ 'array_formula.c',        'A example of using array formulas' ],
     [ 'utf8.c',                 'A example of some UTF-8 text' ],
     [ 'constant_memory.c',      'Write a large file with constant memory usage' ],
     [ 'merge_range.c',          'Create a merged range of cells' ],
+    [ 'merge_rich_string.c',    'Create a merged range with a rich string' ],
     [ 'autofilter.c',           'An example of a worksheet autofilter' ],
     [ 'data_validate.c',        'Examples of worksheet data validation and drop down lists' ],
     [ 'images.c',               'Example of adding images to a worksheet.' ],

docs/src/examples.dox

@@ -190,7 +190,7 @@ Example of writing dates and times in Excel using different date formats.
 <table  width="600">
 <tr>
   <td>@ref dates_and_times03.c "&lt;&lt; dates_and_times03.c"</td>
-  <td align="right">@ref array_formula.c "array_formula.c &gt;&gt;"</td>
+  <td align="right">@ref rich_strings.c "rich_strings.c &gt;&gt;"</td>
 </tr>
 </table>
 
@@ -201,11 +201,28 @@ Example of writing urls/hyperlinks to a worksheet.
 
 
 
-@example array_formula.c
+@example rich_strings.c
 
 <table  width="600">
 <tr>
   <td>@ref hyperlinks.c "&lt;&lt; hyperlinks.c"</td>
+  <td align="right">@ref array_formula.c "array_formula.c &gt;&gt;"</td>
+</tr>
+</table>
+
+Example of writing "rich" multi-format strings to a worksheet.
+
+@image html rich_strings.png
+
+
+
+
+
+@example array_formula.c
+
+<table  width="600">
+<tr>
+  <td>@ref rich_strings.c "&lt;&lt; rich_strings.c"</td>
   <td align="right">@ref utf8.c "utf8.c &gt;&gt;"</td>
 </tr>
 </table>
@@ -254,7 +271,7 @@ mode.
 <table  width="600">
 <tr>
   <td>@ref constant_memory.c "&lt;&lt; constant_memory.c"</td>
-  <td align="right">@ref autofilter.c "autofilter.c &gt;&gt;"</td>
+  <td align="right">@ref merge_rich_string.c "merge_rich_string.c &gt;&gt;"</td>
 </tr>
 </table>
 
@@ -265,11 +282,27 @@ Example of merging cells in a worksheet.
 
 
 
-@example autofilter.c
+@example merge_rich_string.c
 
 <table  width="600">
 <tr>
   <td>@ref merge_range.c "&lt;&lt; merge_range.c"</td>
+  <td align="right">@ref autofilter.c "autofilter.c &gt;&gt;"</td>
+</tr>
+</table>
+
+Example of merging cells with a rich string in a worksheet.
+
+@image html merge_rich.png
+
+
+
+
+@example autofilter.c
+
+<table  width="600">
+<tr>
+  <td>@ref merge_rich_string.c "&lt;&lt; merge_rich_string.c"</td>
   <td align="right">@ref data_validate.c "data_validate.c &gt;&gt;"</td>
 </tr>
 </table>

docs/src/examples.txt

@@ -90,6 +90,14 @@ Example of writing urls/hyperlinks to a worksheet.
 
 @image html hyperlinks.png
 
+##############################################################
+@example rich_strings.c
+
+Example of writing "rich" multi-format strings to a worksheet.
+
+@image html rich_strings.png
+
+
 ##############################################################
 @example array_formula.c
 
@@ -118,6 +126,13 @@ Example of merging cells in a worksheet.
 
 @image html merge_range.png
 
+##############################################################
+@example merge_rich_string.c
+
+Example of merging cells with a rich string in a worksheet.
+
+@image html merge_rich.png
+
 ##############################################################
 @example autofilter.c
 

examples/merge_rich_string.c

@@ -0,0 +1,49 @@
+/*
+ * An example of merging cells containing a rich string using libxlsxwriter.
+ *
+ * Copyright 2014-2018, John McNamara, jmcnamara@cpan.org
+ *
+ */
+
+#include "xlsxwriter.h"
+
+int main() {
+
+    lxw_workbook  *workbook  = workbook_new("merge_rich_string.xlsx");
+    lxw_worksheet *worksheet = workbook_add_worksheet(workbook, NULL);
+
+    /* Configure a format for the merged range. */
+    lxw_format *merge_format = workbook_add_format(workbook);
+    format_set_align(merge_format, LXW_ALIGN_CENTER);
+    format_set_align(merge_format, LXW_ALIGN_VERTICAL_CENTER);
+    format_set_border(merge_format, LXW_BORDER_THIN);
+
+    /* Configure formats for the rich string. */
+    lxw_format *red = workbook_add_format(workbook);
+    format_set_font_color(red, LXW_COLOR_RED);
+
+    lxw_format *blue = workbook_add_format(workbook);
+    format_set_font_color(blue, LXW_COLOR_BLUE);
+
+    /* Create the fragments for the rich string. */
+    lxw_rich_string_tuple fragment1 = {.format = NULL, .string = "This is "     };
+    lxw_rich_string_tuple fragment2 = {.format = red,  .string = "red"          };
+    lxw_rich_string_tuple fragment3 = {.format = NULL, .string = " and this is "};
+    lxw_rich_string_tuple fragment4 = {.format = blue, .string = "blue"         };
+
+    lxw_rich_string_tuple *rich_string[] = {&fragment1, &fragment2,
+                                            &fragment3, &fragment4, NULL};
+
+
+    /* Write an empty string to the merged range. */
+    worksheet_merge_range(worksheet, 1, 1, 4, 3, "", merge_format);
+
+    /* We then overwrite the first merged cell with a rich string. Note that
+     * we must also pass the cell format used in the merged cells format at
+     * the end. */
+    worksheet_write_rich_string(worksheet, 1, 1, rich_string, merge_format);
+
+    workbook_close(workbook);
+
+    return 0;
+}

examples/rich_strings.c

@@ -32,17 +32,20 @@ int main() {
     lxw_format *superscript = workbook_add_format(workbook);
     format_set_font_script(superscript, LXW_FONT_SUPERSCRIPT);
 
-    /* Make the first column wide for clarity. */
+    /* Make the first column wider for clarity. */
     worksheet_set_column(worksheet, 0, 0, 30, NULL);
 
 
-    /* Create and write some rich strings with multiple formats. */
+    /*
+     * Create and write some rich strings with multiple formats.
+     */
 
     /* Example 1. Some bold and italic in the same string. */
-    lxw_rich_string_tuple fragment11 = {.format = NULL,   .string = "This is "};
-    lxw_rich_string_tuple fragment12 = {.format = bold,   .string = "bold"};
+    lxw_rich_string_tuple fragment11 = {.format = NULL,   .string = "This is "     };
+    lxw_rich_string_tuple fragment12 = {.format = bold,   .string = "bold"         };
     lxw_rich_string_tuple fragment13 = {.format = NULL,   .string = " and this is "};
-    lxw_rich_string_tuple fragment14 = {.format = italic, .string = "italic"};
+    lxw_rich_string_tuple fragment14 = {.format = italic, .string = "italic"       };
+
     lxw_rich_string_tuple *rich_string1[] = {&fragment11, &fragment12,
                                              &fragment13, &fragment14, NULL};
 
@@ -50,10 +53,11 @@ int main() {
 
 
     /* Example 2. Some red and blue coloring in the same string. */
-    lxw_rich_string_tuple fragment21 = {.format = NULL,   .string = "This is "};
-    lxw_rich_string_tuple fragment22 = {.format = red,    .string = "red"};
-    lxw_rich_string_tuple fragment23 = {.format = NULL,   .string = " and this is "};
-    lxw_rich_string_tuple fragment24 = {.format = blue,   .string = "blue"};
+    lxw_rich_string_tuple fragment21 = {.format = NULL, .string = "This is "     };
+    lxw_rich_string_tuple fragment22 = {.format = red,  .string = "red"          };
+    lxw_rich_string_tuple fragment23 = {.format = NULL, .string = " and this is "};
+    lxw_rich_string_tuple fragment24 = {.format = blue, .string = "blue"         };
+
     lxw_rich_string_tuple *rich_string2[] = {&fragment21, &fragment22,
                                              &fragment23, &fragment24, NULL};
 
@@ -61,19 +65,21 @@ int main() {
 
 
     /* Example 3. A rich string plus cell formatting. */
-    lxw_rich_string_tuple fragment31 = {.format = NULL,   .string = "Some "};
-    lxw_rich_string_tuple fragment32 = {.format = bold,   .string = "bold text"};
-    lxw_rich_string_tuple fragment33 = {.format = NULL,   .string = " centered"};
+    lxw_rich_string_tuple fragment31 = {.format = NULL, .string = "Some "    };
+    lxw_rich_string_tuple fragment32 = {.format = bold, .string = "bold text"};
+    lxw_rich_string_tuple fragment33 = {.format = NULL, .string = " centered"};
+
     lxw_rich_string_tuple *rich_string3[] = {&fragment31, &fragment32,
                                              &fragment33, NULL};
 
-    /* Note that this example also can a "center" cell format. */
+    /* Note that this example also has a "center" cell format. */
     worksheet_write_rich_string(worksheet, CELL("A5"), rich_string3, center);
 
 
     /* Example 4. A math example with a superscript. */
-    lxw_rich_string_tuple fragment41 = {.format = italic,      .string = "j =k"};
+    lxw_rich_string_tuple fragment41 = {.format = italic,      .string = "j =k" };
     lxw_rich_string_tuple fragment42 = {.format = superscript, .string = "(n-1)"};
+
     lxw_rich_string_tuple *rich_string4[] = {&fragment41, &fragment42, NULL};
 
     worksheet_write_rich_string(worksheet, CELL("A7"), rich_string4, center);

include/xlsxwriter/worksheet.h

@@ -642,8 +642,22 @@ typedef struct lxw_protection {
     char hash[5];
 } lxw_protection;
 
+/**
+ * @brief Struct to represent a rich string format/string pair.
+ *
+ * Arrays of this struct are used to define "rich" multi-format strings that
+ * are passed to `worksheet_write_rich_string()`. Each struct represents a
+ * fragment of the rich multi-format string with a lxw_format to define the
+ * format for the string part. If the string fragment is unformatted then
+ * `NULL` can be used for the format.
+ */
 typedef struct lxw_rich_string_tuple {
+
+    /** The format for a string fragment in a rich string. NULL if the string
+     *  isn't formatted. */
     lxw_format *format;
+
+    /** The string fragment. */
     char *string;
 } lxw_rich_string_tuple;
 
@@ -1321,10 +1335,79 @@ lxw_error worksheet_write_formula_num(lxw_worksheet *worksheet,
                                       const char *formula,
                                       lxw_format *format, double result);
 
+/**
+ * @brief Write a "Rich" multi-format string to a worksheet cell.
+ *
+ * @param worksheet   pointer to a lxw_worksheet instance to be updated.
+ * @param row         The zero indexed row number.
+ * @param col         The zero indexed column number.
+ * @param rich_string An array of format/string lxw_rich_string_tuple fragments.
+ * @param format      A pointer to a Format instance or NULL.
+ *
+ * @return A #lxw_error code.
+ *
+ * The `%worksheet_write_rich_string()` function is used to write strings with
+ * multiple formats. For example to write the string 'This is **bold**
+ * and this is *italic*' you would use the following:
+ *
+ * @code
+ *     lxw_format *bold = workbook_add_format(workbook);
+ *     format_set_bold(bold);
+ *
+ *     lxw_format *italic = workbook_add_format(workbook);
+ *     format_set_italic(italic);
+ *
+ *     lxw_rich_string_tuple fragment11 = {.format = NULL,   .string = "This is "     };
+ *     lxw_rich_string_tuple fragment12 = {.format = bold,   .string = "bold"         };
+ *     lxw_rich_string_tuple fragment13 = {.format = NULL,   .string = " and this is "};
+ *     lxw_rich_string_tuple fragment14 = {.format = italic, .string = "italic"       };
+ *
+ *     lxw_rich_string_tuple *rich_string1[] = {&fragment11, &fragment12,
+ *                                              &fragment13, &fragment14, NULL};
+ *
+ *     worksheet_write_rich_string(worksheet, CELL("A1"), rich_string1, NULL);
+ *
+ * @endcode
+ *
+ * @image html rich_strings_small.png
+ *
+ * The basic rule is to break the string into fragments and put a lxw_format
+ * object before the fragment that you want to format. So if we look at the
+ * above example again:
+ *
+ * This is **bold** and this is *italic*
+ *
+ * The would be broken down into 4 fragments:
+ *
+ *      default: |This is |
+ *      bold:    |bold|
+ *      default: | and this is |
+ *      italic:  |italic|
+ *
+ * This in then converted to the lxw_rich_string_tuple fragments shown in the
+ * example above. For the default format we use `NULL`.
+ *
+ * The fragments are passed to `%worksheet_write_rich_string()` as a `NULL`
+ * terminated array:
+ *
+ * @code
+ *     lxw_rich_string_tuple *rich_string1[] = {&fragment11, &fragment12,
+ *                                              &fragment13, &fragment14, NULL};
+ *
+ *     worksheet_write_rich_string(worksheet, CELL("A1"), rich_string1, NULL);
+ *
+ * @endcode
+ *
+ * **Note**:
+ * Excel doesn't allow the use of two consecutive formats in a rich string or
+ * an empty string fragment. For either of these conditions a warning is
+ * raised and the input to `%worksheet_write_rich_string()` is ignored.
+ *
+ */
 lxw_error worksheet_write_rich_string(lxw_worksheet *worksheet,
-                                      lxw_row_t row_num,
-                                      lxw_col_t col_num,
-                                      lxw_rich_string_tuple *rich_strings[],
+                                      lxw_row_t row,
+                                      lxw_col_t col,
+                                      lxw_rich_string_tuple *rich_string[],
                                       lxw_format *format);
 
 /**