libxlsxwriter
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:

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:

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

workbook_close
lxw_error workbook_close(lxw_workbook *workbook)
Close the Workbook object and write the XLSX file.
lxw_comment_options::visible
uint8_t visible
Definition: worksheet.h:1828
lxw_comment_options
Options for inserted comments.
Definition: worksheet.h:1819
workbook_new
lxw_workbook * workbook_new(const char *filename)
Create a new workbook object.
lxw_comment_options::y_scale
double y_scale
Definition: worksheet.h:1853
lxw_comment_options::height
uint16_t height
Definition: worksheet.h:1845
lxw_comment_options::x_offset
int32_t x_offset
Definition: worksheet.h:1886
lxw_worksheet
Struct to represent an Excel worksheet.
Definition: worksheet.h:2107
lxw_comment_options::x_scale
double x_scale
Definition: worksheet.h:1849
lxw_comment_options::font_name
char * font_name
Definition: worksheet.h:1862
lxw_comment_options::author
char * author
Definition: worksheet.h:1835
LXW_COMMENT_DISPLAY_VISIBLE
@ LXW_COMMENT_DISPLAY_VISIBLE
Definition: worksheet.h:224
lxw_comment_options::start_row
lxw_row_t start_row
Definition: worksheet.h:1877
worksheet_write_comment_opt
lxw_error worksheet_write_comment_opt(lxw_worksheet *worksheet, lxw_row_t row, lxw_col_t col, const char *string, lxw_comment_options *options)
Write a comment to a worksheet cell with options.
LXW_COLOR_GREEN
@ LXW_COLOR_GREEN
Definition: format.h:196
worksheet_set_comments_author
void worksheet_set_comments_author(lxw_worksheet *worksheet, const char *author)
Set the default author of the cell comments.
lxw_workbook
Struct to represent an Excel workbook.
Definition: workbook.h:292
worksheet_write_string
lxw_error worksheet_write_string(lxw_worksheet *worksheet, lxw_row_t row, lxw_col_t col, const char *string, lxw_format *format)
Write a string to a worksheet cell.
CELL
#define CELL(cell)
Convert an Excel A1 cell string into a (row, col) pair.
Definition: utility.h:45
workbook_add_worksheet
lxw_worksheet * workbook_add_worksheet(lxw_workbook *workbook, const char *sheetname)
Add a new worksheet to a workbook.
lxw_comment_options::width
uint16_t width
Definition: worksheet.h:1840
LXW_COMMENT_DISPLAY_HIDDEN
@ LXW_COMMENT_DISPLAY_HIDDEN
Definition: worksheet.h:220
worksheet_write_comment
lxw_error worksheet_write_comment(lxw_worksheet *worksheet, lxw_row_t row, lxw_col_t col, const char *string)
Write a comment to a worksheet cell.