Initial working comment support.

Issue #38

.indent.pro

@@ -84,6 +84,8 @@
 -T lxw_col_options
 -T lxw_col_t
 -T lxw_color_t
+-T lxw_comment
+-T lxw_comment_options
 -T lxw_content_types
 -T lxw_core
 -T lxw_custom
@@ -132,6 +134,8 @@
 -T lxw_styles
 -T lxw_theme
 -T lxw_tuple
+-T lxw_vml
+-T lxw_vml_obj
 -T lxw_workbook
 -T lxw_workbook_options
 -T lxw_worksheet

include/xlsxwriter/comment.h

@@ -0,0 +1,51 @@
+/*
+ * libxlsxwriter
+ *
+ * Copyright 2014-2019, John McNamara, jmcnamara@cpan.org. See LICENSE.txt.
+ *
+ * comment - A libxlsxwriter library for creating Excel XLSX comment files.
+ *
+ */
+#ifndef __LXW_COMMENT_H__
+#define __LXW_COMMENT_H__
+
+#include <stdint.h>
+
+#include "common.h"
+#include "worksheet.h"
+
+/*
+ * Struct to represent a comment object.
+ */
+typedef struct lxw_comment {
+
+    FILE *file;
+    struct lxw_comment_objs *comment_objs;
+
+} lxw_comment;
+
+
+/* *INDENT-OFF* */
+#ifdef __cplusplus
+extern "C" {
+#endif
+/* *INDENT-ON* */
+
+lxw_comment *lxw_comment_new();
+void lxw_comment_free(lxw_comment *comment);
+void lxw_comment_assemble_xml_file(lxw_comment *self);
+
+/* Declarations required for unit testing. */
+#ifdef TESTING
+
+STATIC void _comment_xml_declaration(lxw_comment *self);
+
+#endif /* TESTING */
+
+/* *INDENT-OFF* */
+#ifdef __cplusplus
+}
+#endif
+/* *INDENT-ON* */
+
+#endif /* __LXW_COMMENT_H__ */

include/xlsxwriter/common.h

@@ -94,6 +94,9 @@ typedef enum lxw_error {
     /** Unknown zip error when closing xlsx file. */
     LXW_ERROR_ZIP_CLOSE,
 
+    /** Feature is not currently supported in this configuration. */
+    LXW_ERROR_FEATURE_NOT_SUPPORTED,
+
     /** NULL function parameter ignored. */
     LXW_ERROR_NULL_PARAMETER_IGNORED,
 

include/xlsxwriter/content_types.h

@@ -53,6 +53,10 @@ void lxw_ct_add_chart_name(lxw_content_types *content_types,
                            const char *name);
 void lxw_ct_add_drawing_name(lxw_content_types *content_types,
                              const char *name);
+void lxw_ct_add_comment_name(lxw_content_types *content_types,
+                             const char *name);
+void lxw_ct_add_vml_name(lxw_content_types *content_types);
+
 void lxw_ct_add_shared_strings(lxw_content_types *content_types);
 void lxw_ct_add_calc_chain(lxw_content_types *content_types);
 void lxw_ct_add_custom_properties(lxw_content_types *content_types);

include/xlsxwriter/format.h

@@ -1206,6 +1206,8 @@ void format_set_font_extend(lxw_format *format);
 void format_set_reading_order(lxw_format *format, uint8_t value);
 void format_set_theme(lxw_format *format, uint8_t value);
 void format_set_hyperlink(lxw_format *format);
+void format_set_color_indexed(lxw_format *format, uint8_t value);
+void format_set_font_only(lxw_format *format);
 
 /* Declarations required for unit testing. */
 #ifdef TESTING

include/xlsxwriter/packager.h

@@ -29,6 +29,8 @@
 #include "format.h"
 #include "content_types.h"
 #include "relationships.h"
+#include "vml.h"
+#include "comment.h"
 
 #define LXW_ZIP_BUFFER_SIZE (16384)
 

include/xlsxwriter/vml.h

@@ -0,0 +1,54 @@
+/*
+ * libxlsxwriter
+ *
+ * Copyright 2014-2019, John McNamara, jmcnamara@cpan.org. See LICENSE.txt.
+ *
+ * vml - A libxlsxwriter library for creating Excel XLSX vml files.
+ *
+ */
+#ifndef __LXW_VML_H__
+#define __LXW_VML_H__
+
+#include <stdint.h>
+
+#include "common.h"
+#include "worksheet.h"
+
+/*
+ * Struct to represent a vml object.
+ */
+typedef struct lxw_vml {
+
+    FILE *file;
+    uint8_t type;
+    struct lxw_comment_objs *button_objs;
+    struct lxw_comment_objs *comment_objs;
+    struct lxw_comment_objs *image_objs;
+    char *vml_data_id_str;
+    uint32_t vml_shape_id;
+
+} lxw_vml;
+
+
+/* *INDENT-OFF* */
+#ifdef __cplusplus
+extern "C" {
+#endif
+/* *INDENT-ON* */
+
+lxw_vml *lxw_vml_new();
+void lxw_vml_free(lxw_vml *vml);
+void lxw_vml_assemble_xml_file(lxw_vml *self);
+
+/* Declarations required for unit testing. */
+#ifdef TESTING
+
+#endif /* TESTING */
+
+/* *INDENT-OFF* */
+#ifdef __cplusplus
+}
+#endif
+/* *INDENT-ON* */
+
+#endif /* __LXW_VML_H__ */

include/xlsxwriter/workbook.h

@@ -298,6 +298,7 @@ typedef struct lxw_workbook {
     uint16_t num_xf_formats;
     uint16_t num_format_count;
     uint16_t drawing_count;
+    uint16_t comment_count;
 
     uint16_t font_count;
     uint16_t border_count;
@@ -308,6 +309,7 @@ typedef struct lxw_workbook {
     uint8_t has_png;
     uint8_t has_jpeg;
     uint8_t has_bmp;
+    uint8_t has_vml;
 
     lxw_hash_table *used_xf_formats;
 

include/xlsxwriter/worksheet.h

@@ -55,6 +55,7 @@
 #include "format.h"
 #include "styles.h"
 #include "utility.h"
+#include "relationships.h"
 
 #define LXW_ROW_MAX           1048576
 #define LXW_COL_MAX           16384
@@ -275,6 +276,7 @@ STAILQ_HEAD(lxw_selections, lxw_selection);
 STAILQ_HEAD(lxw_data_validations, lxw_data_val_obj);
 STAILQ_HEAD(lxw_image_props, lxw_object_properties);
 STAILQ_HEAD(lxw_chart_props, lxw_object_properties);
+STAILQ_HEAD(lxw_comment_objs, lxw_vml_obj);
 
 /**
  * @brief Options for rows and columns.
@@ -658,6 +660,102 @@ typedef struct lxw_object_properties {
     STAILQ_ENTRY (lxw_object_properties) list_pointers;
 } lxw_object_properties;
 
+/**
+ * @brief Options for inserted comments.
+ *
+ * Options for modifying comments inserted via `worksheet_write_comment_opt()`.
+ *
+ */
+typedef struct lxw_comment_options {
+
+    /** This option is used to make a cell comment visible when the worksheet
+     *  is opened. The default behavior in Excel is that comments are
+     *  initially hidden. However, it is also possible in Excel to make
+     *  individual comments or all comments visible.  You can make all
+     *  comments in the worksheet visible using the
+     *  `worksheet_show_comments()` function. Defaults to LXW_FALSE.*/
+    uint8_t visible;
+
+    /** This option is used to set the row in which the comment will
+     *  appear. By default Excel displays comments one cell to the right and
+     *  one cell above the cell to which the comment relates. The `start_row`
+     *  and `start_col` options should both be set to 0 if not used.*/
+    lxw_row_t start_row;
+
+    /** This option is used to set the column in which the comment will
+     *   appear. See the `start_row` option for more information. */
+    lxw_col_t start_col;
+
+    /** This option is used to set the width of the cell comment box
+     *  explicitly in pixels. The default width is 128 pixels. */
+    uint16_t width;
+
+    /** This option is used to set the height of the cell comment box
+     *  explicitly in pixels. The default height is 74 pixels. */
+    uint16_t height;
+
+    /** X scale of the comment as a decimal. */
+    double x_scale;
+
+    /** Y scale of the comment as a decimal. */
+    double y_scale;
+
+    /** Offset from the left of the cell in pixels. */
+    int32_t x_offset;
+
+    /** Offset from the top of the cell in pixels. */
+    int32_t y_offset;
+
+    /** This option is used to set the background color of cell comment
+     *  box. The color should be an RGB integer value, see @ref
+     *  working_with_colors. */
+    lxw_color_t color;
+
+    /** This option is used to set the font for the comment. The default font
+     *  is 'Tahoma'. */
+    char *font_name;
+
+     /** This option is used to set the font size for the comment. The default
+      * is 8. */
+    double font_size;
+
+    /** This option is used to set the font family for the comment. Not
+     *  required very often. Set to NULL. */
+    char *font_family;
+
+    /** This option is used to indicate the author of the cell comment. Excel
+     *  displays the author in the status bar at the bottom of the
+     *  worksheet. The default author for all cell comments in a worksheet can
+     *  be set using the `worksheet_set_comments_author()` function. Set to
+     *  NULL if not required.*/
+    char *author;
+
+} lxw_comment_options;
+
+/* Internal structure for VML object options. */
+typedef struct lxw_vml_obj {
+
+    uint8_t visible;
+    uint32_t author_id;
+    lxw_row_t row;
+    lxw_col_t col;
+    lxw_color_t color;
+    double font_size;
+    char *author;
+    char *font_name;
+    char *font_family;
+    char *text;
+    struct lxw_drawing_coords from;
+    struct lxw_drawing_coords to;
+    uint32_t col_absolute;
+    uint32_t row_absolute;
+    uint32_t width;
+    uint32_t height;
+
+    STAILQ_ENTRY (lxw_vml_obj) list_pointers;
+
+} lxw_vml_obj;
+
 /**
  * @brief Header and footer options.
  *
@@ -790,6 +888,7 @@ typedef struct lxw_worksheet {
     struct lxw_image_props *image_props;
     struct lxw_chart_props *chart_data;
     struct lxw_drawing_rel_ids *drawing_rel_ids;
+    struct lxw_comment_objs *comment_objs;
 
     lxw_row_t dim_rowmin;
     lxw_row_t dim_rowmax;
@@ -902,6 +1001,15 @@ typedef struct lxw_worksheet {
     lxw_drawing *drawing;
     lxw_format *default_url_format;
 
+    uint8_t has_vml;
+    uint8_t has_comments;
+    uint8_t has_header_vml;
+    lxw_rel_tuple *external_vml_comment_link;
+    lxw_rel_tuple *external_comment_link;
+    char *default_comment_author;
+    char *vml_data_id_str;
+    uint32_t vml_shape_id;
+
     STAILQ_ENTRY (lxw_worksheet) list_pointers;
 
 } lxw_worksheet;
@@ -935,6 +1043,8 @@ typedef struct lxw_row {
     uint8_t row_changed;
     uint8_t data_changed;
     uint8_t height_changed;
+    uint8_t has_comments;
+
     struct lxw_table_cells *cells;
 
     /* tree management pointers for tree.h. */
@@ -947,6 +1057,7 @@ typedef struct lxw_cell {
     lxw_col_t col_num;
     enum cell_types type;
     lxw_format *format;
+    lxw_vml_obj *comment;
 
     union {
         double number;
@@ -1547,6 +1658,14 @@ lxw_error worksheet_write_rich_string(lxw_worksheet *worksheet,
                                       lxw_rich_string_tuple *rich_string[],
                                       lxw_format *format);
 
+lxw_error worksheet_write_comment_opt(lxw_worksheet *worksheet,
+                                      lxw_row_t row_num, lxw_col_t col_num,
+                                      char *string,
+                                      lxw_comment_options *options);
+
+lxw_error worksheet_write_comment(lxw_worksheet *worksheet,
+                                  lxw_row_t row, lxw_col_t col, char *string);
+
 /**
  * @brief Set the properties for a row of cells.
  *
@@ -3417,6 +3536,9 @@ void worksheet_set_default_row(lxw_worksheet *worksheet, double height,
  */
 lxw_error worksheet_set_vba_name(lxw_worksheet *worksheet, const char *name);
 
+lxw_error worksheet_set_comments_author(lxw_worksheet *worksheet,
+                                        const char *author);
+
 lxw_worksheet *lxw_worksheet_new(lxw_worksheet_init_data *init_data);
 void lxw_worksheet_free(lxw_worksheet *worksheet);
 void lxw_worksheet_assemble_xml_file(lxw_worksheet *worksheet);
@@ -3431,9 +3553,14 @@ void lxw_worksheet_prepare_chart(lxw_worksheet *worksheet,
                                  lxw_object_properties *object_props,
                                  uint8_t is_chartsheet);
 
-lxw_row *lxw_worksheet_find_row(lxw_worksheet *worksheet, lxw_row_t row_num);
-lxw_cell *lxw_worksheet_find_cell(lxw_row *row, lxw_col_t col_num);
+uint32_t lxw_worksheet_prepare_vml_objects(lxw_worksheet *worksheet,
+                                           uint32_t vml_data_id,
+                                           uint32_t vml_shape_id,
+                                           uint32_t vml_drawing_id,
+                                           uint32_t comment_id);
 
+lxw_row *lxw_worksheet_find_row(lxw_worksheet *worksheet, lxw_row_t row_num);
+lxw_cell *lxw_worksheet_find_cell_in_row(lxw_row *row, lxw_col_t col_num);
 /*
  * External functions to call intern XML methods shared with chartsheet.
  */