improved work with cell comments in XSSF, also added support for cell comments to SS interfaces

git-svn-id: https://svn.apache.org/repos/asf/poi/trunk@884918 13f79535-47bb-0310-9956-ffa450edef68

2 files changed, 30 insertions, 114 deletions

diff --git a/src/documentation/content/xdocs/spreadsheet/quick-guide.xml b/src/documentation/content/xdocs/spreadsheet/quick-guide.xml
index eeca60ebe7..b2feca0679 100644
--- a/src/documentation/content/xdocs/spreadsheet/quick-guide.xml
+++ b/src/documentation/content/xdocs/spreadsheet/quick-guide.xml
@@ -43,7 +43,7 @@
                     <li><link href="#TextExtraction">Text Extraction</link></li>
                     <li><link href="#Alignment">Aligning cells</link></li>
                     <li><link href="#Borders">Working with borders</link></li>
-                    <li><link href="#FrillsAndFills">Fills and color</link></li>
+                    <li><link href="#FillsAndFrills">Fills and color</link></li>
                     <li><link href="#MergedCells">Merging cells</link></li>
                     <li><link href="#WorkingWithFonts">Working with fonts</link></li>
                     <li><link href="#CustomColors">Custom colors</link></li>
@@ -1328,123 +1328,36 @@ Examples:
             </source>
         </section>
         <anchor id="CellComments"/>
-        <section><title>Cell Comments - HSSF and XSSF (slight differences though)</title>
+        <section><title>Cell Comments - HSSF and XSSF</title>
         <p>
-  In HSSF Excel, cell comments were added to the file format as a bit of a 
-   cludge. As such, comments are a kind of a text shape, so inserting a
-   comment is very similar to placing a text box in a worksheet.
+          A comment is a rich text note that is attached to &amp;
+          associated with a cell, separate from other cell content.
+          Comment content is stored separate from the cell, and is displayed in a drawing object (like a text box)
+          that is separate from, but associated with, a cell
         </p>
-        <p>
-  In XSSF Excel, cell comments are more cleanly done. Each Sheet has a list
-   of its comments, and they can be added much like other cell properties.
-        </p>
-        <p>
-  Once you have created your comment, how you use it is very similar between
-   HSSF and XSSF. It is only the creation of a new comment where things
-   differ.
-        </p>
-        <p>
-  For HSSF, the process is:
-        </p>
-            <source>
-    HSSFWorkbook wb = new HSSFWorkbook();
-    HSSFSheet sheet = wb.createSheet("Cell comments in POI HSSF");
-    CreationHelper createHelper = wb.getCreationHelper();
-
-    // Create the drawing patriarch. This is the top level container for all shapes including cell comments.
-    HSSFPatriarch patr = sheet.createDrawingPatriarch();
-
-    // Create a cell in row 3
-    Cell cell1 = sheet.createRow(3).createCell((short)1);
-    cell1.setCellValue(new HSSFRichTextString("Hello, World"));
-
-    // Anchor defines size and position of the comment in worksheet
-    Comment comment1 = patr.createComment(new HSSFClientAnchor(0, 0, 0, 0, (short)4, 2, (short) 6, 5));
-
-     // set text in the comment
-    comment1.setString(createHelper.createRichTextString("We can set comments in POI"));
-
-    // set comment author.
-    // you can see it in the status bar when moving mouse over the commented cell
-    comment1.setAuthor("Apache Software Foundation");
-
-    // The first way to assign comment to a cell is via Cell.setCellComment method
-    cell1.setCellComment(comment1);
-
-
-    // Create another cell in row 6
-    Cell cell2 = sheet.createRow(6).createCell((short)1);
-    cell2.setCellValue(36.6);
-
-    // And a comment for it
-    HSSFComment comment2 = patr.createComment(new HSSFClientAnchor(0, 0, 0, 0, (short)4, 8, (short) 6, 11));
-    // Modify background color of the comment
-    comment2.setFillColor(204, 236, 255);
-
-    HSSFRichTextString string = new HSSFRichTextString("Normal body temperature");
-
-    // Apply custom font to the text in the comment
-    HSSFFont font = wb.createFont();
-    font.setFontName("Arial");
-    font.setFontHeightInPoints((short)10);
-    font.setBoldweight(HSSFFont.BOLDWEIGHT_BOLD);
-    font.setColor(HSSFColor.RED.index);
-    string.applyFont(font);
-
-    comment2.setString(string);
-    // By default comments are hidden. This one is always visible.
-    comment2.setVisible(true);
-
-    comment2.setAuthor("Bill Gates");
-
-
-    /**
-     * The second way to assign comment to a cell is to implicitly specify its row and column.
-     * Note, it is possible to set row and column of a non-existing cell.
-     * It works, the comment is visible.
-     */
-    comment2.setRow(6);
-    comment2.setColumn((short)1);
-
-    FileOutputStream out = new FileOutputStream("poi_comment.xls");
-    wb.write(out);
-    out.close();
-        </source>
-        <p>
-  For XSSF, the simpler process is:
-        </p>
-            <source>
-    XSSFWorkbook wb = new XSSFWorkbook();
-    XSSFSheet sheet = wb.createSheet("Cell comments in POI XSSF");
-    CreationHelper createHelper = wb.getCreationHelper();
-
-    // Create a cell in row 3
-    Cell cell1 = sheet.createRow(3).createCell((short)1);
-    cell1.setCellValue(new XSSFRichTextString("Hello, World"));
-
-    // Create a comment, and set the text and author
-    // (You can see the author in the status bar when moving mouse
-    //  over the commented cell)
-    Comment comment1 = sheet.createComment();
-    comment1.setString(createHelper.createRichTextString("We can set comments in POI"));
-    comment1.setAuthor("Apache Software Foundation");
-
-
-    // The first way to assign comment to a cell is via Cell.setCellComment method
-    cell1.setCellComment(comment1);
+        <source>
+    Workbook wb = new XSSFWorkbook(); //or new HSSFWorkbook();
 
+    CreationHelper factory = wb.getCreationHelper();
 
-	// The other way is to set the row and column
-    // This could point to a cell that isn't defined, and the comment will
-    //  will still show up all the same
-    Comment comment2 = sheet.createComment();
-    comment2.setString(createHelper.createRichTextString("Comment for missing cell"));
-    comment2.setAuthor("Apache POI");
-    comment2.setRow(11);
-    comment2.setColumn(1);
+    Sheet sheet = wb.createSheet();
+    
+    Cell cell = sheet.createRow(3).createCell(5);
+    cell.setCellValue("F4");
+    
+    Drawing drawing = sheet.createDrawingPatriarch();
 
-    // Write out
-    FileOutputStream out = new FileOutputStream("poi_comment.xls");
+    ClientAnchor anchor = factory.createClientAnchor();
+    Comment comment = drawing.createCellComment(anchor);
+    RichTextString str = factory.createRichTextString("Hello, World!");
+    comment.setString(str);
+    comment.setAuthor("Apache POI");
+    //assign the comment to the cell
+    cell.setCellComment(comment);
+
+    String fname = "comment-xssf.xls";
+    if(wb instanceof XSSFWorkbook) fname += "x";
+    FileOutputStream out = new FileOutputStream(fname);
     wb.write(out);
     out.close();
         </source>
diff --git a/src/documentation/content/xdocs/status.xml b/src/documentation/content/xdocs/status.xml
index bda9cecca0..9109c2b37e 100644
--- a/src/documentation/content/xdocs/status.xml
+++ b/src/documentation/content/xdocs/status.xml
@@ -34,7 +34,10 @@
 
     <changes>
         <release version="3.6-beta1" date="2009-??-??">
-           <action dev="POI-DEVELOPERS" type="add">Add support for creating SummaryInformation and DocumentSummaryInformation properties on POIDocuments that don't have them, via POIDocument.createInformationProperties()</action>
+          <action dev="POI-DEVELOPERS" type="fix">47188 - avoid corruption of workbook when adding cell comments </action> 
+          <action dev="POI-DEVELOPERS" type="fix">48106 - improved work with cell comments in XSSF</action> 
+          <action dev="POI-DEVELOPERS" type="add">Add support for creating SummaryInformation and DocumentSummaryInformation properties 
+            on POIDocuments that don't have them, via POIDocument.createInformationProperties()</action>
            <action dev="POI-DEVELOPERS" type="fix">48180 - be more forgiving of short chart records, which skip some unused fields</action>
            <action dev="POI-DEVELOPERS" type="fix">48274 - fix erronious wrapping of byte colours in HSSFPalette.findSimilarColor</action>
            <action dev="POI-DEVELOPERS" type="fix">48269 - fix fetching of error codes from XSSF formula cells</action>