Working with Cell Comments

Cell comments are a way of adding notation to cells in Excel. For example:

#include "xlsxwriter.h"
 
int main() {
 
    lxw_workbook  *workbook  = workbook_new("comments1.xlsx");
    lxw_worksheet *worksheet = workbook_add_worksheet(workbook, NULL);
 
    worksheet_write_string( worksheet, 0, 0, "Hello" , NULL);
 
    worksheet_write_comment(worksheet, 0, 0, "This is a comment");
 
    return workbook_close(workbook);
}

Setting Comment Properties

The properties of the cell comment can be modified by passing an optional lxw_comment_options struct to worksheet_write_comment_opt() control the format of the comment. For example:

lxw_comment_options options = {.x_scale = 1.2, .y_scale = 0.5};
 
worksheet_write_comment_opt(worksheet, CELL("C6"), "Hello", &options);

The following options are available in lxw_comment_options:

• author
• visible
• width
• height
• x_scale
• y_scale
• color
• font_name
• font_size
• start_row
• start_col
• x_offset
• y_offset

The options are explained in detail below and shown in comments2.c.

Cell comments: author

This author option is used to indicate who is the author of the cell comment. Excel displays the author of the comment in the status bar at the bottom of the worksheet. This is usually of interest in corporate environments where several people might review and provide comments to a workbook:

lxw_comment_options options = {.author = "Ian McEwan"};
 
worksheet_write_comment_opt(worksheet, CELL("C6"), "Atonement", &options);

The default author for all cell comments in a worksheet can be set using the worksheet_set_comments_author() function:

worksheet_set_comments_author(worksheet, "Jane Gloriana Villanueva")

Cell comments: visible

The visible 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. In libxlsxwriter individual comments can be made visible as follows:

lxw_comment_options options = {.visible = LXW_COMMENT_DISPLAY_VISIBLE};
 
worksheet_write_comment_opt(worksheet, CELL("C6"), "Hello.", &options);

The visible property should be set with one of the enum values from lxw_comment_display_types.

It is possible to make all comments in a worksheet visible using the worksheet_show_comments() worksheet function. Alternatively, if all of the cell comments have been made visible you can hide individual comments:

lxw_comment_options options = {.visible = LXW_COMMENT_DISPLAY_HIDDEN};
 
worksheet_write_comment_opt(worksheet, CELL("C6"), "Hello", &options);

Cell comments: width

The width option is used to set the width of the cell comment box explicitly in pixels:

lxw_comment_options options = {.width = 200};
 
worksheet_write_comment_opt(worksheet, CELL("C6"), "Hello", &options);

The width and height can be adjusted together:

lxw_comment_options options = {.width = 200, .height = 50};

Cell comments: height

The height option is used to set the height of the cell comment box explicitly in pixels:

lxw_comment_options options = {.height = 50};
 
worksheet_write_comment_opt(worksheet, CELL("C6"), "Hello", &options);

The width and height can be adjusted together:

lxw_comment_options options = {.width = 200, .height = 50};

Cell comments: x_scale

The x_scale option is used to set the width of the cell comment box as a factor of the default width:

lxw_comment_options options = {.x_scale = 2.0};
 
worksheet_write_comment_opt(worksheet, CELL("C6"), "Hello", &options);

Cell comments: y_scale

The y_scale option is used to set the height of the cell comment box as a factor of the default height:

lxw_comment_options options = {.y_scale = 2.0};
 
worksheet_write_comment_opt(worksheet, CELL("C6"), "Hello", &options);

Cell comments: color

The color option is used to set the background color of cell comment box. The color should be an RGB integer value, see Working with Colors.

lxw_comment_options options1 = {.color = LXW_COLOR_GREEN};
lxw_comment_options options2 = {.color = 0xFF6600};
 
worksheet_write_comment_opt(worksheet, CELL("C6"), "Hello", &options1);
worksheet_write_comment_opt(worksheet, CELL("C7"), "Hello", &options2);

Cell comments: font_name

The font_name option is used to set the font for the comment:

lxw_comment_options options = {.font_name = "Courier"};

The default font is 'Tahoma'.

Cell comments: font_size

The font_size option is used to set the font size for the comment:

lxw_comment_options options = {.font_name = "Courier", .font_size = 10};

The default font size is 8.

Cell comments: start_row

The start_row 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 row is zero indexed:

lxw_comment_options options = {.start_row = 3, .start_col = 4};
 
worksheet_write_comment_opt(worksheet, CELL("C6"), "Hello", &options);

See Notes on scaling of cell comments

Cell comments: start_col

The start_col option is used to set the column 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 column is zero indexed:

lxw_comment_options options = {.start_row = 3, .start_col = 4};
 
worksheet_write_comment_opt(worksheet, CELL("C6"), "Hello", &options);

See Notes on scaling of cell comments

Cell comments: x_offset

The x_offset option is used to change the x offset, in pixels, of a comment within a cell:

lxw_comment_options options = {.x_offset = 30, .y_offset = 12};
 
worksheet_write_comment_opt(worksheet, CELL("C6"), "Hello", &options);

See Notes on scaling of cell comments

Cell comments: y_offset

The y_offset option is used to change the y offset, in pixels, of a comment within a cell:

lxw_comment_options options = {.x_offset = 30, .y_offset = 12};
 
worksheet_write_comment_opt(worksheet, CELL("C6"), "Hello", &options);

See Notes on scaling of cell comments

Notes on scaling of cell comments

Note on options that move a cell position:

Excel only displays offset cell comments when they are displayed as visible. Excel does not display hidden cells as displaced when you mouse over them. Please note this when using options that adjust the position of the cell comment such as start_row, start_col, x_offset and y_offset.

Note on row height and comments:

If you specify the height of a row that contains a comment then libxlsxwriter will adjust the height of the comment to maintain the default or user specified dimensions. However, the height of a row can also be adjusted automatically by Excel if the text wrap property is set or large fonts are used in the cell. This means that the height of the row is unknown to the library at run time and thus the comment box is stretched with the row. Use the worksheet_set_row() function to specify the row height explicitly and avoid this problem. See Example 8 of comments2.c.

Next: Working with Memory and Performance