Improve the javadocs for font and fill related colourings, and add another tests to check it all works as expected

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

src/documentation/content/xdocs/changes.xml

@@ -35,7 +35,8 @@
     </devs>
 
 		<!-- Don't forget to update status.xml too! -->
-        <release version="3.0.2-FINAL" date="2007-??-??">
+        <release version="3.0.2-FINAL" date="2008-??-??">
+            <action dev="POI-DEVELOPERS" type="fix">Improve JavaDocs relating to hssf font and fill colourings</action>
             <action dev="POI-DEVELOPERS" type="add">44095, 44097, 44099 - [PATCH] Support for Mid, Replace and Substitute excel functions</action>
             <action dev="POI-DEVELOPERS" type="add">44055 - [PATCH] Support for getting the from field from HSMF messages</action>
             <action dev="POI-DEVELOPERS" type="add">43551 - [PATCH] Support for 1904 date windowing in HSSF (previously only supported 1900 date windowing)</action>

src/documentation/content/xdocs/status.xml

@@ -32,7 +32,8 @@
 
 	<!-- Don't forget to update changes.xml too! -->
     <changes>
-        <release version="3.0.2-FINAL" date="2007-??-??">
+        <release version="3.0.2-FINAL" date="2008-??-??">
+            <action dev="POI-DEVELOPERS" type="fix">Improve JavaDocs relating to hssf font and fill colourings</action>
             <action dev="POI-DEVELOPERS" type="add">44095, 44097, 44099 - [PATCH] Support for Mid, Replace and Substitute excel functions</action>
             <action dev="POI-DEVELOPERS" type="add">44055 - [PATCH] Support for getting the from field from HSMF messages</action>
             <action dev="POI-DEVELOPERS" type="add">43551 - [PATCH] Support for 1904 date windowing in HSSF (previously only supported 1900 date windowing)</action>

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

@@ -294,10 +294,24 @@ public class HSSFCellStyle
         format.setFontIndex(fontindex);
     }
 
+    /**
+     * gets the index of the font for this style
+     * @see org.apache.poi.hssf.usermodel.HSSFWorkbook#getFontAt(short)
+     */
     public short getFontIndex()
     {
         return format.getFontIndex();
     }
+    
+    /**
+     * gets the font for this style
+     * @param parentWorkbook The HSSFWorkbook that this style belongs to
+     * @see org.apache.poi.hssf.usermodel.HSSFCellStyle#getFontIndex()
+     * @see org.apache.poi.hssf.usermodel.HSSFWorkbook#getFontAt(short)
+     */
+    public HSSFFont getFont(HSSFWorkbook parentWorkbook) {
+    	return parentWorkbook.getFontAt(getFontIndex());
+    }
 
     /**
      * set the cell's using this style to be hidden
@@ -689,7 +703,6 @@ public class HSSFCellStyle
      * @see #BORDER_MEDIUM_DASH_DOT_DOT
      * @see #BORDER_SLANTED_DASH_DOT
      */
-
     public short getBorderBottom()
     {
         return format.getBorderBottom();
@@ -697,9 +710,8 @@ public class HSSFCellStyle
 
     /**
      * set the color to use for the left border
-     * @param color
+     * @param color The index of the color definition
      */
-
     public void setLeftBorderColor(short color)
     {
         format.setLeftBorderPaletteIdx(color);
@@ -707,9 +719,9 @@ public class HSSFCellStyle
 
     /**
      * get the color to use for the left border
-     * @return color
+     * @see org.apache.poi.hssf.usermodel.HSSFPalette#getColor(short)
+     * @param color The index of the color definition
      */
-
     public short getLeftBorderColor()
     {
         return format.getLeftBorderPaletteIdx();
@@ -717,9 +729,8 @@ public class HSSFCellStyle
 
     /**
      * set the color to use for the right border
-     * @param color
+     * @param color The index of the color definition
      */
-
     public void setRightBorderColor(short color)
     {
         format.setRightBorderPaletteIdx(color);
@@ -727,9 +738,9 @@ public class HSSFCellStyle
 
     /**
      * get the color to use for the left border
-     * @return color
+     * @see org.apache.poi.hssf.usermodel.HSSFPalette#getColor(short)
+     * @param color The index of the color definition
      */
-
     public short getRightBorderColor()
     {
         return format.getRightBorderPaletteIdx();
@@ -737,9 +748,8 @@ public class HSSFCellStyle
 
     /**
      * set the color to use for the top border
-     * @param color
+     * @param color The index of the color definition
      */
-
     public void setTopBorderColor(short color)
     {
         format.setTopBorderPaletteIdx(color);
@@ -747,9 +757,9 @@ public class HSSFCellStyle
 
     /**
      * get the color to use for the top border
-     * @return color
+     * @see org.apache.poi.hssf.usermodel.HSSFPalette#getColor(short)
+     * @param color The index of the color definition
      */
-
     public short getTopBorderColor()
     {
         return format.getTopBorderPaletteIdx();
@@ -757,9 +767,8 @@ public class HSSFCellStyle
 
     /**
      * set the color to use for the bottom border
-     * @param color
+     * @param color The index of the color definition
      */
-
     public void setBottomBorderColor(short color)
     {
         format.setBottomBorderPaletteIdx(color);
@@ -767,9 +776,9 @@ public class HSSFCellStyle
 
     /**
      * get the color to use for the left border
-     * @return color
+     * @see org.apache.poi.hssf.usermodel.HSSFPalette#getColor(short)
+     * @param color The index of the color definition
      */
-
     public short getBottomBorderColor()
     {
         return format.getBottomBorderPaletteIdx();
@@ -871,9 +880,9 @@ public class HSSFCellStyle
 
     /**
      * get the background fill color
+     * @see org.apache.poi.hssf.usermodel.HSSFPalette#getColor(short)
      * @return fill color
      */
-
     public short getFillBackgroundColor()
     {
     	short result = format.getFillBackground();
@@ -889,7 +898,6 @@ public class HSSFCellStyle
      * <i>Note: Ensure Foreground color is set prior to background color.</i>
      * @param bg  color
      */
-
     public void setFillForegroundColor(short bg)
     {
         format.setFillForeground(bg);
@@ -898,12 +906,11 @@ public class HSSFCellStyle
 
     /**
      * get the foreground fill color
+     * @see org.apache.poi.hssf.usermodel.HSSFPalette#getColor(short)
      * @return fill color
      */
-
     public short getFillForegroundColor()
     {
         return format.getFillForeground();
     }
-
 }

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

@@ -281,8 +281,8 @@ public class HSSFFont
      * @return color to use
      * @see #COLOR_NORMAL
      * @see #COLOR_RED
+     * @see org.apache.poi.hssf.usermodel.HSSFPalette#getColor(short)
      */
-
     public short getColor()
     {
         return font.getColorPaletteIndex();

src/testcases/org/apache/poi/hssf/usermodel/TestHSSFPalette.java

@@ -95,6 +95,71 @@ public class TestHSSFPalette extends TestCase
         assertEquals(msg, (short) 100, actualRGB[2]);
     }
     
+    /**
+     * Uses the palette from cell stylings
+     */
+    public void testPaletteFromCellColours() throws Exception {
+        String dir = System.getProperty("HSSF.testdata.path");
+        File sample = new File(dir + "/SimpleWithColours.xls");
+        assertTrue("SimpleWithColours.xls exists and is readable", sample.canRead());
+        FileInputStream fis = new FileInputStream(sample);
+        HSSFWorkbook book = new HSSFWorkbook(fis);
+        fis.close();
+    	
+        HSSFPalette p = book.getCustomPalette();
+        
+        HSSFCell cellA = book.getSheetAt(0).getRow(0).getCell((short)0);
+        HSSFCell cellB = book.getSheetAt(0).getRow(1).getCell((short)0);
+        HSSFCell cellC = book.getSheetAt(0).getRow(2).getCell((short)0);
+        HSSFCell cellD = book.getSheetAt(0).getRow(3).getCell((short)0);
+        HSSFCell cellE = book.getSheetAt(0).getRow(4).getCell((short)0);
+        
+        // Plain
+        assertEquals("I'm plain", cellA.getStringCellValue());
+        assertEquals(64, cellA.getCellStyle().getFillForegroundColor());
+        assertEquals(64, cellA.getCellStyle().getFillBackgroundColor());
+        assertEquals(HSSFFont.COLOR_NORMAL, cellA.getCellStyle().getFont(book).getColor());
+        assertEquals(0, cellA.getCellStyle().getFillPattern());
+        assertEquals("0:0:0", p.getColor((short)64).getHexString());
+        assertEquals(null, p.getColor((short)32767));
+        
+        // Red
+        assertEquals("I'm red", cellB.getStringCellValue());
+        assertEquals(64, cellB.getCellStyle().getFillForegroundColor());
+        assertEquals(64, cellB.getCellStyle().getFillBackgroundColor());
+        assertEquals(10, cellB.getCellStyle().getFont(book).getColor());
+        assertEquals(0, cellB.getCellStyle().getFillPattern());
+        assertEquals("0:0:0", p.getColor((short)64).getHexString());
+        assertEquals("FFFF:0:0", p.getColor((short)10).getHexString());
+        
+        // Red + green bg
+        assertEquals("I'm red with a green bg", cellC.getStringCellValue());
+        assertEquals(11, cellC.getCellStyle().getFillForegroundColor());
+        assertEquals(64, cellC.getCellStyle().getFillBackgroundColor());
+        assertEquals(10, cellC.getCellStyle().getFont(book).getColor());
+        assertEquals(1, cellC.getCellStyle().getFillPattern());
+        assertEquals("0:FFFF:0", p.getColor((short)11).getHexString());
+        assertEquals("FFFF:0:0", p.getColor((short)10).getHexString());
+        
+        // Pink with yellow
+        assertEquals("I'm pink with a yellow pattern (none)", cellD.getStringCellValue());
+        assertEquals(13, cellD.getCellStyle().getFillForegroundColor());
+        assertEquals(64, cellD.getCellStyle().getFillBackgroundColor());
+        assertEquals(14, cellD.getCellStyle().getFont(book).getColor());
+        assertEquals(0, cellD.getCellStyle().getFillPattern());
+        assertEquals("FFFF:FFFF:0", p.getColor((short)13).getHexString());
+        assertEquals("FFFF:0:FFFF", p.getColor((short)14).getHexString());
+        
+        // Pink with yellow - full
+        assertEquals("I'm pink with a yellow pattern (full)", cellE.getStringCellValue());
+        assertEquals(13, cellE.getCellStyle().getFillForegroundColor());
+        assertEquals(64, cellE.getCellStyle().getFillBackgroundColor());
+        assertEquals(14, cellE.getCellStyle().getFont(book).getColor());
+        assertEquals(0, cellE.getCellStyle().getFillPattern());
+        assertEquals("FFFF:FFFF:0", p.getColor((short)13).getHexString());
+        assertEquals("FFFF:0:FFFF", p.getColor((short)14).getHexString());
+    }
+    
     /**
      * Verifies that the generated gnumeric-format string values match the
      * hardcoded values in the HSSFColor default color palette