Update some more documentation, and put in a workaround for needing to create a RichTextString, without wanting to know the concrete type, but Java interfaces are crap

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

src/documentation/content/xdocs/spreadsheet/quick-guide.xml

@@ -115,7 +115,8 @@
 
     // Or do it on one line.
     row.createCell((short)1).setCellValue(1.2);
-    row.createCell((short)2).setCellValue("This is a string");
+    row.createCell((short)2).setCellValue(
+         cell.createRichTextString("This is a string"));
     row.createCell((short)3).setCellValue(true);
 
     // Write the output to a file

src/examples/src/org/apache/poi/ss/usermodel/examples/FromQuickGuide.java

@@ -0,0 +1,94 @@
+/* ====================================================================
+   Licensed to the Apache Software Foundation (ASF) under one or more
+   contributor license agreements.  See the NOTICE file distributed with
+   this work for additional information regarding copyright ownership.
+   The ASF licenses this file to You under the Apache License, Version 2.0
+   (the "License"); you may not use this file except in compliance with
+   the License.  You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+==================================================================== */
+package org.apache.poi.ss.usermodel.examples;
+
+import java.io.FileOutputStream;
+import java.io.IOException;
+
+import org.apache.poi.hssf.usermodel.HSSFWorkbook;
+import org.apache.poi.ss.usermodel.Cell;
+import org.apache.poi.ss.usermodel.RichTextString;
+import org.apache.poi.ss.usermodel.Row;
+import org.apache.poi.ss.usermodel.Sheet;
+import org.apache.poi.ss.usermodel.Workbook;
+import org.apache.poi.xssf.usermodel.XSSFWorkbook;
+
+/**
+ * Various things from the quick guide documentation
+ */
+public class FromQuickGuide {
+	public void newWorkbook() throws IOException {
+		boolean doHSSF = true;
+		boolean doXSSF = true;
+		
+		if(doHSSF) {
+		    Workbook wb = new HSSFWorkbook();
+		    FileOutputStream fileOut = new FileOutputStream("workbook.xls");
+		    wb.write(fileOut);
+		    fileOut.close();
+		}
+		if(doXSSF) {
+		    Workbook wb = new XSSFWorkbook();
+		    FileOutputStream fileOut = new FileOutputStream("workbook.xlsx");
+		    wb.write(fileOut);
+		    fileOut.close();
+		}
+	}
+	
+	public void newSheet() throws IOException {
+		Workbook[] wbs = new Workbook[] {
+				new HSSFWorkbook(), new XSSFWorkbook()
+		};
+		
+		for (int i = 0; i < wbs.length; i++) {
+			Workbook wb = wbs[i];
+		    Sheet sheet1 = wb.createSheet("new sheet");
+		    Sheet sheet2 = wb.createSheet("second sheet");
+		    FileOutputStream fileOut = new FileOutputStream("workbook.xls");
+		    wb.write(fileOut);
+		    fileOut.close();
+		}
+	}
+	
+	public void newCells() throws IOException {
+		Workbook[] wbs = new Workbook[] {
+				new HSSFWorkbook(), new XSSFWorkbook()
+		};
+		
+		for (int i = 0; i < wbs.length; i++) {
+			Workbook wb = wbs[i];
+		    Sheet sheet = wb.createSheet("new sheet");
+
+		    // Create a row and put some cells in it. Rows are 0 based.
+		    Row row = sheet.createRow((short)0);
+		    // Create a cell and put a value in it.
+		    Cell cell = row.createCell((short)0);
+		    cell.setCellValue(1);
+
+		    // Or do it on one line.
+		    row.createCell((short)1).setCellValue(1.2);
+		    row.createCell((short)2).setCellValue(
+		    		cell.createRichTextString("This is a string"));
+		    row.createCell((short)3).setCellValue(true);
+
+		    // Write the output to a file
+		    FileOutputStream fileOut = new FileOutputStream("workbook.xls");
+		    wb.write(fileOut);
+		    fileOut.close();
+		}
+	}
+}

src/java/org/apache/poi/hssf/usermodel/HSSFCell.java

@@ -1141,4 +1141,11 @@ public class HSSFCell implements Cell
         int eofLoc = sheet.findFirstRecordLocBySid( EOFRecord.sid );
         sheet.getRecords().add( eofLoc, link.record );
     }
+
+    /**
+     * Creates a new HSSFRichTextString for you.
+     */
+	public RichTextString createRichTextString(String text) {
+		return new HSSFRichTextString(text);
+	}
 }

src/ooxml/interfaces-jdk15/org/apache/poi/ss/usermodel/Cell.java

@@ -153,6 +153,17 @@ public interface Cell {
 
     String getCellFormula();
 
+    /**
+     * Creates a RichTextString, which you can then pass to
+     *  {@link #setCellValue(RichTextString)}. This is required
+     *  because Java is broken, and won't allow you to define
+     *  static methods or constructors on interfaces, and without
+     *  that there's no way to get a RichTextString without
+     *  creating the appropriate concrete class. 
+     * @param text The text to initialise the RichTextString with
+     */
+    RichTextString createRichTextString(String text);
+    
     /**
      * get the value of the cell as a number.  For strings we throw an exception.
      * For blank cells we return a 0.

src/ooxml/interfaces-jdk15/org/apache/poi/ss/usermodel/RichTextString.java

@@ -17,12 +17,17 @@
 
 package org.apache.poi.ss.usermodel;
 
-
+/**
+ * Rich text unicode string.  These strings can have fonts 
+ *  applied to arbitary parts of the string.
+ *  
+ * @author Glen Stampoultzis (glens at apache.org)
+ * @author Jason Height (jheight at apache.org)
+ */
 public interface RichTextString {
-
     /** Place holder for indicating that NO_FONT has been applied here */
     public static final short NO_FONT = 0;
-
+    
     /**
      * Applies a font to the specified characters of a string.
      *

src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFCell.java

@@ -316,5 +316,10 @@ public class XSSFCell implements Cell {
       }
     }
 
-    
+    /**
+     * Creates an XSSFRichTextString for you.
+     */
+	public RichTextString createRichTextString(String text) {
+		return new XSSFRichTextString(text);
+	}
 }