libxlsxwriter/docs/src/working_with_comments.dox

/**
@page working_with_comments Working with Cell Comments

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

@code
    #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);
    }
@endcode

@image html comments1.png



@section ww_comments_properties 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:


@code
    lxw_comment_options options = {.x_scale = 1.2, .y_scale = 0.5};

    worksheet_write_comment_opt(worksheet, CELL("C6"), "Hello", &options);
@endcode

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 @ref comments2.c.

@subsection ww_comments_author 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:

@code
    lxw_comment_options options = {.author = "Ian McEwan"};

    worksheet_write_comment_opt(worksheet, CELL("C6"), "Atonement", &options);
@endcode

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

@code
    worksheet_set_comments_author(worksheet, "Jane Gloriana Villanueva")
@endcode

@subsection ww_comments_visible 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:

@code
    lxw_comment_options options = {.visible = LXW_COMMENT_DISPLAY_VISIBLE};

    worksheet_write_comment_opt(worksheet, CELL("C6"), "Hello.", &options);
@endcode

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:

@code
    lxw_comment_options options = {.visible = LXW_COMMENT_DISPLAY_HIDDEN};

    worksheet_write_comment_opt(worksheet, CELL("C6"), "Hello", &options);
@endcode


@subsection ww_comments_width Cell comments: width

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

@code
    lxw_comment_options options = {.width = 200};

    worksheet_write_comment_opt(worksheet, CELL("C6"), "Hello", &options);
@endcode

The width and height can be adjusted together:

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


@subsection ww_comments_height Cell comments: height

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

@code
    lxw_comment_options options = {.height = 50};

    worksheet_write_comment_opt(worksheet, CELL("C6"), "Hello", &options);
@endcode

The width and height can be adjusted together:

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


@subsection ww_comments_x_scale 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:

@code
    lxw_comment_options options = {.x_scale = 2.0};

    worksheet_write_comment_opt(worksheet, CELL("C6"), "Hello", &options);
@endcode


@subsection ww_comments_y_scale 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:

@code
    lxw_comment_options options = {.y_scale = 2.0};

    worksheet_write_comment_opt(worksheet, CELL("C6"), "Hello", &options);
@endcode


@subsection ww_comments_color 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 @ref
working_with_colors.

@code
    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);
@endcode


@subsection ww_comments_font_name Cell comments: font_name

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

@code
    lxw_comment_options options = {.font_name = "Courier"};
@endcode

The default font is 'Tahoma'.


@subsection ww_comments_font_size Cell comments: font_size

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

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

The  default font size is 8.


@subsection ww_comments_start_row 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:

@code
    lxw_comment_options options = {.start_row = 3, .start_col = 4};

    worksheet_write_comment_opt(worksheet, CELL("C6"), "Hello", &options);
@endcode

See @ref ww_comments_notes

@subsection ww_comments_start_col 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:

@code
    lxw_comment_options options = {.start_row = 3, .start_col = 4};

    worksheet_write_comment_opt(worksheet, CELL("C6"), "Hello", &options);
@endcode

See @ref ww_comments_notes

@subsection ww_comments_x_offset Cell comments: x_offset

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

@code
    lxw_comment_options options = {.x_offset = 30, .y_offset = 12};

    worksheet_write_comment_opt(worksheet, CELL("C6"), "Hello", &options);
@endcode

See @ref ww_comments_notes

@subsection ww_comments_y_offset Cell comments: y_offset

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

@code
    lxw_comment_options options = {.x_offset = 30, .y_offset = 12};

    worksheet_write_comment_opt(worksheet, CELL("C6"), "Hello", &options);
@endcode

See @ref ww_comments_notes


@subsection ww_comments_notes Notes on scaling of cell comments

<b>Note on options that move a cell position:</b>

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`.

<b>Note on row height and comments:</b>

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 @ref comments2.c.





Next: @ref working_with_memory

*/