Method: Writexlsx::Worksheet#write_comment
- Defined in:
- lib/write_xlsx/worksheet.rb
#write_comment(*args) ⇒ Object
:call-seq:
write_comment(row, column, string, = {})
Write a comment to the specified row and column (zero indexed).
write_comment methods return:
Returns 0 : normal termination
The write_comment() method is used to add a comment to a cell. A cell comment is indicated in Excel by a small red triangle in the upper right-hand corner of the cell. Moving the cursor over the red triangle will reveal the comment.
The following example shows how to add a comment to a cell:
worksheet.write( 2, 2, 'Hello')
worksheet.write_comment(2, 2, 'This is a comment.')
As usual you can replace the row and column parameters with an A1 cell reference. See the note about “Cell notation”.
worksheet.write( 'C3', 'Hello')
worksheet.write_comment('C3', 'This is a comment.')
The write_comment() method will also handle strings in UTF-8 format.
worksheet.write_comment('C3', "\x{263a}") # Smiley
worksheet.write_comment('C4', 'Comment ca va?')
In addition to the basic 3 argument form of write_comment() you can pass in several optional key/value pairs to control the format of the comment. For example:
worksheet.write_comment('C3', 'Hello', :visible => 1, :author => 'Perl')
Most of these options are quite specific and in general the default comment behaviour will be all that you need. However, should you need greater control over the format of the cell comment the following options are available:
:author
:visible
:x_scale
:width
:y_scale
:height
:color
:start_cell
:start_row
:start_col
:x_offset
:y_offset
Option: author
This 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.
worksheet.write_comment('C3', 'Atonement', :author => 'Ian McEwan')
The default author for all cell comments can be set using the set_comments_author() method.
worksheet.('Ruby')
Option: visible
This option is used to make a cell comment visible when the worksheet is opened. The default behaviour in Excel is that comments are initially hidden. However, it is also possible in Excel to make individual or all comments visible. In WriteXLSX individual comments can be made visible as follows:
worksheet.write_comment('C3', 'Hello', :visible => 1 )
It is possible to make all comments in a worksheet visible using the show_comments() worksheet method. Alternatively, if all of the cell comments have been made visible you can hide individual comments:
worksheet.write_comment('C3', 'Hello', :visible => 0)
Option: x_scale
This option is used to set the width of the cell comment box as a factor of the default width.
worksheet.write_comment('C3', 'Hello', :x_scale => 2)
worksheet.write_comment('C4', 'Hello', :x_scale => 4.2)
Option: width
This option is used to set the width of the cell comment box explicitly in pixels.
worksheet.write_comment('C3', 'Hello', :width => 200)
Option: y_scale
This option is used to set the height of the cell comment box as a factor of the default height.
worksheet.write_comment('C3', 'Hello', :y_scale => 2)
worksheet.write_comment('C4', 'Hello', :y_scale => 4.2)
Option: height
This option is used to set the height of the cell comment box explicitly in pixels.
worksheet.write_comment('C3', 'Hello', :height => 200)
Option: color
This option is used to set the background colour of cell comment box. You can use one of the named colours recognised by WriteXLSX or a colour index. See “COLOURS IN EXCEL”.
worksheet.write_comment('C3', 'Hello', :color => 'green')
worksheet.write_comment('C4', 'Hello', :color => 0x35) # Orange
Option: start_cell
This option is used to set the cell 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. However, you can change this behaviour if you wish. In the following example the comment which would appear by default in cell D2 is moved to E2.
worksheet.write_comment('C3', 'Hello', :start_cell => 'E2')
Option: start_row
This option is used to set the row in which the comment will appear. See the start_cell option above. The row is zero indexed.
worksheet.write_comment('C3', 'Hello', :start_row => 0)
Option: start_col
This option is used to set the column in which the comment will appear. See the start_cell option above. The column is zero indexed.
worksheet.write_comment('C3', 'Hello', :start_col => 4)
Option: x_offset
This option is used to change the x offset, in pixels, of a comment within a cell:
worksheet.write_comment('C3', comment, :x_offset => 30)
Option: y_offset
This option is used to change the y offset, in pixels, of a comment within a cell:
worksheet.write_comment('C3', comment, :x_offset => 30)
You can apply as many of these options as you require.
Note about using options that adjust the position of the cell comment such as start_cell, start_row, start_col, x_offset and y_offset: Excel only displays offset cell comments when they are displayed as “visible”. Excel does not display hidden cells as moved when you mouse over them.
Note about row height and comments. If you specify the height of a row that contains a comment then WriteXLSX 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 module at run time and thus the comment box is stretched with the row. Use the set_row() method to specify the row height explicitly and avoid this problem.
2039 2040 2041 2042 2043 2044 2045 2046 2047 2048 2049 2050 |
# File 'lib/write_xlsx/worksheet.rb', line 2039 def write_comment(*args) # Check for a cell reference in A1 notation and substitute row and column row, col, string, = row_col_notation(args) raise WriteXLSXInsufficientArgumentError if [row, col, string].include?(nil) # Check that row and col are valid and store max and min values check_dimensions(row, col) store_row_col_max_min_values(row, col) # Process the properties of the cell comment. @comments.add(Package::Comment.new(@workbook, self, row, col, string, )) end |