Added advanced cell comments sample code.

dev/release/fix_example_docs.pl

@@ -43,6 +43,8 @@ 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' ],
+    [ 'comments1.c',            'Example of adding cell comments to a worksheet' ],
+    [ 'comments2.c',            'Example of adding cell comments with options' ],
     [ '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' ],

docs/src/examples.dox

@@ -516,7 +516,7 @@ Example of setting Excel worksheet protection.
 <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>
+  <td align="right">@ref comments1.c "comments1.c &gt;&gt;"</td>
 </tr>
 </table>
 
@@ -527,11 +527,44 @@ Example adding a VBA macro to a workbook.
 
 
 
-@example hide_row_col.c
+@example comments1.c
 
 <table  width="600">
 <tr>
   <td>@ref macro.c "&lt;&lt; macro.c"</td>
+  <td align="right">@ref comments2.c "comments2.c &gt;&gt;"</td>
+</tr>
+</table>
+
+A simple example of adding cell comments to a worksheet.
+
+@image html comments1.png
+
+
+
+
+@example comments2.c
+
+<table  width="600">
+<tr>
+  <td>@ref comments1.c "&lt;&lt; comments1.c"</td>
+  <td align="right">@ref hide_row_col.c "hide_row_col.c &gt;&gt;"</td>
+</tr>
+</table>
+
+Another example of adding cell comments to a worksheet. This example
+demonstrates most of the available comment formatting options.
+
+@image html comments2.png
+
+
+
+
+@example hide_row_col.c
+
+<table  width="600">
+<tr>
+  <td>@ref comments2.c "&lt;&lt; comments2.c"</td>
   <td align="right">@ref panes.c "panes.c &gt;&gt;"</td>
 </tr>
 </table>

docs/src/examples.txt

@@ -236,6 +236,21 @@ Example adding a VBA macro to a workbook.
 
 @image html macros.png
 
+##############################################################
+@example comments1.c
+
+A simple example of adding cell comments to a worksheet.
+
+@image html comments1.png
+
+##############################################################
+@example comments2.c
+
+Another example of adding cell comments to a worksheet. This example
+demonstrates most of the available comment formatting options.
+
+@image html comments2.png
+
 ##############################################################
 @example hide_row_col.c
 

examples/comments2.c

@@ -0,0 +1,281 @@
+/*
+ * An example of writing cell comments to a worksheet using libxlsxwriter.
+ *
+ * Each of the worksheets demonstrates different features of cell comments.
+ *
+ * Copyright 2014-2019, John McNamara, jmcnamara@cpan.org
+ *
+ */
+
+#include "xlsxwriter.h"
+
+int main() {
+
+    lxw_workbook  *workbook   = workbook_new("comments2.xlsx");
+    lxw_worksheet *worksheet1 = workbook_add_worksheet(workbook, NULL);
+    lxw_worksheet *worksheet2 = workbook_add_worksheet(workbook, NULL);
+    lxw_worksheet *worksheet3 = workbook_add_worksheet(workbook, NULL);
+    lxw_worksheet *worksheet4 = workbook_add_worksheet(workbook, NULL);
+    lxw_worksheet *worksheet5 = workbook_add_worksheet(workbook, NULL);
+    lxw_worksheet *worksheet6 = workbook_add_worksheet(workbook, NULL);
+    lxw_worksheet *worksheet7 = workbook_add_worksheet(workbook, NULL);
+    lxw_worksheet *worksheet8 = workbook_add_worksheet(workbook, NULL);
+
+    lxw_format *text_wrap = workbook_add_format(workbook);
+    format_set_text_wrap(text_wrap);
+    format_set_align(text_wrap, LXW_ALIGN_VERTICAL_TOP);
+
+
+    /*
+     * Example 1. Demonstrates a simple cell comments without formatting.
+     */
+
+    /* Set up some worksheet formatting. */
+    worksheet_set_column(worksheet1, 2, 2, 25, NULL);
+    worksheet_set_row(worksheet1, 2, 50, NULL);
+
+
+    worksheet_write_string(worksheet1, CELL("C3"),
+                           "Hold the mouse over this cell to see the comment.",
+                           text_wrap);
+
+    worksheet_write_comment(worksheet1, CELL("C3"), "This is a comment.");
+
+
+    /*
+     * Example 2. Demonstrates visible and hidden comments.
+     */
+
+    /* Set up some worksheet formatting. */
+    worksheet_set_column(worksheet2, 2, 2, 25, NULL);
+    worksheet_set_row(worksheet2, 2, 50, NULL);
+    worksheet_set_row(worksheet2, 2, 50, NULL);
+
+
+    worksheet_write_string(worksheet2, CELL("C3"),
+                           "This cell comment is visible.",
+                           text_wrap);
+
+    /* Use an option to make the comment visible. */
+    lxw_comment_options options2 = {.visible = LXW_COMMENT_DISPLAY_VISIBLE};
+    worksheet_write_comment_opt(worksheet2, CELL("C3"), "Hello.", &options2);
+
+
+    worksheet_write_string(worksheet2, CELL("C6"),
+                           "This cell comment isn't visible until you pass "
+                           "the mouse over it (the default).",
+                           text_wrap);
+
+    worksheet_write_comment(worksheet2, CELL("C6"), "Hello.");
+
+
+    /*
+     * Example 3. Demonstrates visible and hidden comments, set at the
+     * worksheet level.
+     */
+    worksheet_set_column(worksheet3, 2, 2, 25, NULL);
+    worksheet_set_row(worksheet3, 2, 50, NULL);
+    worksheet_set_row(worksheet3, 5, 50, NULL);
+    worksheet_set_row(worksheet3, 8, 50, NULL);
+
+    /* Make all comments on the worksheet visible. */
+    worksheet_show_comments(worksheet3);
+
+
+    worksheet_write_string(worksheet3, CELL("C3"),
+                           "This cell comment is visible, explicitly.",
+                           text_wrap);
+
+    lxw_comment_options options3a = {.visible = LXW_COMMENT_DISPLAY_VISIBLE};
+    worksheet_write_comment_opt(worksheet3, 2, 2, "Hello", &options3a);
+
+
+    worksheet_write_string(worksheet3, CELL("C6"),
+                           "This cell comment is also visible because "
+                           "we used worksheet_show_comments().",
+                           text_wrap);
+
+    worksheet_write_comment(worksheet3, CELL("C6"), "Hello");
+
+
+    worksheet_write_string(worksheet3, CELL("C9"),
+                           "However, we can still override it locally.",
+                           text_wrap);
+
+    lxw_comment_options options3b = {.visible = LXW_COMMENT_DISPLAY_HIDDEN};
+    worksheet_write_comment_opt(worksheet3, CELL("C9"), "Hello", &options3b);
+
+
+    /*
+     * Example 4. Demonstrates changes to the comment box dimensions.
+     */
+    worksheet_set_column(worksheet4, 2, 2, 25, NULL);
+    worksheet_set_row(worksheet4, 2, 50, NULL);
+    worksheet_set_row(worksheet4, 5, 50, NULL);
+    worksheet_set_row(worksheet4, 8, 50, NULL);
+    worksheet_set_row(worksheet4, 15, 50, NULL);
+    worksheet_set_row(worksheet4, 18, 50, NULL);
+
+    worksheet_show_comments(worksheet4);
+
+
+    worksheet_write_string(worksheet4, CELL("C3"),
+                           "This cell comment is default size.",
+                           text_wrap);
+
+    worksheet_write_comment_opt(worksheet4, 2, 2, "Hello", NULL);
+
+
+    worksheet_write_string(worksheet4, CELL("C6"),
+                           "This cell comment is twice as wide.",
+                           text_wrap);
+
+    lxw_comment_options options4a = {.x_scale = 2.0};
+    worksheet_write_comment_opt(worksheet4, CELL("C6"), "Hello", &options4a);
+
+
+    worksheet_write_string(worksheet4, CELL("C9"),
+                           "This cell comment is twice as high.",
+                           text_wrap);
+
+    lxw_comment_options options4b = {.y_scale = 2.0};
+    worksheet_write_comment_opt(worksheet4, CELL("C9"), "Hello", &options4b);
+
+
+    worksheet_write_string(worksheet4, CELL("C16"),
+                           "This cell comment is scaled in both directions.",
+                           text_wrap);
+
+    lxw_comment_options options4c = {.x_scale = 1.2, .y_scale = 0.5};
+    worksheet_write_comment_opt(worksheet4, CELL("C16"), "Hello", &options4c);
+
+
+    worksheet_write_string(worksheet4, CELL("C19"),
+                           "This cell comment has width and height specified in pixels.",
+                           text_wrap);
+
+    lxw_comment_options options4d = {.width = 200, .height = 50};
+    worksheet_write_comment_opt(worksheet4, CELL("C19"), "Hello", &options4d);
+
+
+    /*
+     * Example 5. Demonstrates changes to the cell comment position.
+     */
+    worksheet_set_column(worksheet5, 2, 2, 25, NULL);
+    worksheet_set_row(worksheet5, 2, 50, NULL);
+    worksheet_set_row(worksheet5, 5, 50, NULL);
+    worksheet_set_row(worksheet5, 8, 50, NULL);
+
+    worksheet_show_comments(worksheet5);
+
+    worksheet_write_string(worksheet5, CELL("C3"),
+                           "This cell comment is in the default position.",
+                           text_wrap);
+
+    worksheet_write_comment(worksheet5, 2, 2, "Hello");
+
+
+    worksheet_write_string(worksheet5, CELL("C6"),
+                           "This cell comment has been moved to another cell.",
+                           text_wrap);
+
+    lxw_comment_options options5a = {.start_row = 3, .start_col = 4};
+    worksheet_write_comment_opt(worksheet5, CELL("C6"), "Hello", &options5a);
+
+
+    worksheet_write_string(worksheet5, CELL("C9"),
+                           "This cell comment has been shifted within its default cell.",
+                           text_wrap);
+
+    lxw_comment_options options5b = {.x_offset = 30, .y_offset = 12};
+    worksheet_write_comment_opt(worksheet5, CELL("C9"), "Hello", &options5b);
+
+
+    /*
+     * Example 6. Demonstrates changes to the comment background color.
+     */
+    worksheet_set_column(worksheet6, 2, 2, 25, NULL);
+    worksheet_set_row(worksheet6, 2, 50, NULL);
+    worksheet_set_row(worksheet6, 5, 50, NULL);
+    worksheet_set_row(worksheet6, 8, 50, NULL);
+
+    worksheet_show_comments(worksheet6);
+
+    worksheet_write_string(worksheet6, CELL("C3"),
+                           "This cell comment has a different color.",
+                           text_wrap);
+
+    lxw_comment_options options6a = {.color = LXW_COLOR_GREEN};
+    worksheet_write_comment_opt(worksheet6, 2, 2, "Hello", &options6a);
+
+
+    worksheet_write_string(worksheet6, CELL("C6"),
+                           "This cell comment has the default color.",
+                           text_wrap);
+
+    worksheet_write_comment(worksheet6, CELL("C6"), "Hello");
+
+
+    worksheet_write_string(worksheet6, CELL("C9"),
+                           "This cell comment has a different color.",
+                           text_wrap);
+
+    lxw_comment_options options6b = {.color = 0xFF6600};
+    worksheet_write_comment_opt(worksheet6, CELL("C9"), "Hello", &options6b);
+
+
+    /*
+     * Example 7. Demonstrates how to set the cell comment author.
+     */
+    worksheet_set_column(worksheet7, 2, 2, 30, NULL);
+    worksheet_set_row(worksheet7, 2, 50, NULL);
+    worksheet_set_row(worksheet7, 5, 60, NULL);
+
+    worksheet_write_string(worksheet7, CELL("C3"),
+                           "Move the mouse over this cell and you will see 'Cell C3 "
+                           "commented by' (blank) in the status bar at the bottom.",
+                           text_wrap);
+
+    worksheet_write_comment(worksheet7, CELL("C3"), "Hello");
+
+
+    worksheet_write_string(worksheet7, CELL("C6"),
+                           "Move the mouse over this cell and you will see 'Cell C6 "
+                           "commented by libxlsxwriter' in the status bar at the bottom.",
+                           text_wrap);
+
+    lxw_comment_options options7a = {.author = "libxlsxwriter"};
+    worksheet_write_comment_opt(worksheet7, CELL("C6"), "Hello", &options7a);
+
+
+    /*
+     * Example 8. Demonstrates the need to explicitly set the row height.
+     */
+    worksheet_set_column(worksheet8, 2, 2, 25, NULL);
+    worksheet_set_row(worksheet8, 2, 80, NULL);
+
+    worksheet_show_comments(worksheet8);
+
+    worksheet_write_string(worksheet8, CELL("C3"),
+                           "The height of this row has been adjusted explicitly using "
+                           "worksheet_set_row(). The size of the comment box is "
+                           "adjusted accordingly by libxlsxwriter",
+                           text_wrap);
+
+    worksheet_write_comment(worksheet8, CELL("C3"), "Hello");
+
+
+    worksheet_write_string(worksheet8, CELL("C6"),
+                           "The height of this row has been adjusted by Excel when the "
+                           "file is opened due to the text wrap property being set. "
+                           "Unfortunately this means that the height of the row is "
+                           "unknown to libxlsxwriter at run time and thus the comment "
+                           "box is stretched as well.\n\n"
+                           "Use worksheet_set_row() to specify the row height explicitly "
+                           "to avoid this problem.",
+                           text_wrap);
+
+    worksheet_write_comment(worksheet8, CELL("C6"), "Hello");
+
+    return workbook_close(workbook);
+}