From 81a095fa5e3a653d2c6b5d8438ffb497faa0715b Mon Sep 17 00:00:00 2001
From: Yegor Kozlov <yegor@apache.org>
Date: Sun, 13 Sep 2009 14:53:51 +0000
Subject: [PATCH] added javadoc how to avoid Excel crash when creating too many
 HSSFRichTextString cells, see Bugzilla 47543

git-svn-id: https://svn.apache.org/repos/asf/poi/trunk@814324 13f79535-47bb-0310-9956-ffa450edef68
---
 src/documentation/content/xdocs/status.xml    |  1 +
 .../hssf/usermodel/HSSFRichTextString.java    | 38 +++++++++++++++++++
 2 files changed, 39 insertions(+)

diff --git a/src/documentation/content/xdocs/status.xml b/src/documentation/content/xdocs/status.xml
index c40967161..7fd8eccf4 100644
--- a/src/documentation/content/xdocs/status.xml
+++ b/src/documentation/content/xdocs/status.xml
@@ -33,6 +33,7 @@
 
     <changes>
         <release version="3.5-beta7" date="2009-??-??">
+           <action dev="POI-DEVELOPERS" type="fix">47543 - added javadoc how to avoid Excel crash when creating too many HSSFRichTextString cells</action>
            <action dev="POI-DEVELOPERS" type="fix">47813 - fixed problems with XSSFWorkbook.removeSheetAt when workbook contains chart</action>
            <action dev="POI-DEVELOPERS" type="fix">47737 - adjust sheet indices of named ranges when deleting sheets</action>
            <action dev="POI-DEVELOPERS" type="fix">47770 - built-in positive formats don't need starting '('</action>
diff --git a/src/java/org/apache/poi/hssf/usermodel/HSSFRichTextString.java b/src/java/org/apache/poi/hssf/usermodel/HSSFRichTextString.java
index dee0a455a..269cabe42 100644
--- a/src/java/org/apache/poi/hssf/usermodel/HSSFRichTextString.java
+++ b/src/java/org/apache/poi/hssf/usermodel/HSSFRichTextString.java
@@ -28,6 +28,44 @@ import org.apache.poi.ss.usermodel.RichTextString;
  * Rich text unicode string.  These strings can have fonts applied to
  * arbitary parts of the string.
  *
+ * <p>
+ * Note, that in certain cases creating too many HSSFRichTextString cells may cause Excel 2003 and lower to crash
+ * when changing the color of the cells and then saving the Excel file. Compare two snippets that produce equivalent output:
+ *
+ * <p><blockquote><pre>
+ *  HSSFCell hssfCell = row.createCell(idx);
+ *  //rich text consists of two runs
+ *  HSSFRichTextString richString = new HSSFRichTextString( "Hello, World!" );
+ *  richString.applyFont( 0, 6, font1 );
+ *  richString.applyFont( 6, 13, font2 );
+ *  hssfCell.setCellValue( richString );
+ * </pre></blockquote>
+ *
+ * and
+ *
+ * <p><blockquote><pre>
+ *  //create a cell style and assign the first font to it
+ *  HSSFCellStyle style = workbook.createCellStyle();
+ *  style.setFont(font1);
+ *
+ *  HSSFCell hssfCell = row.createCell(idx);
+ *  hssfCell.setCellStyle(style);
+ *
+ *  //rich text consists of one run overriding the cell style
+ *  HSSFRichTextString richString = new HSSFRichTextString( "Hello, World!" );
+ *  richString.applyFont( 6, 13, font2 );
+ *  hssfCell.setCellValue( richString );
+ * </pre></blockquote><p>
+ *
+ * Excel always uses the latter approach: for a reach text containing N runs Excel saves the font of the first run in the cell's
+ * style and subsequent N-1 runs override this font.
+ *
+ * <p> For more information regarding this behavior please consult Bugzilla 47543:
+ *
+ * <a href="https://issues.apache.org/bugzilla/show_bug.cgi?id=47543">
+ * https://issues.apache.org/bugzilla/show_bug.cgi?id=47543</a>
+ * <p>
+ *
  * @author Glen Stampoultzis (glens at apache.org)
  * @author Jason Height (jheight at apache.org)
  */