applied patches #46119, #46120 and #46078 by Gizella Bronzetti

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

src/examples/src/org/apache/poi/xssf/usermodel/examples/HeadersAndFooters.java

@@ -19,8 +19,10 @@ package org.apache.poi.xssf.usermodel.examples;
 import java.io.FileOutputStream;
 
 import org.apache.poi.ss.usermodel.Footer;
+import org.apache.poi.ss.usermodel.Header;
 import org.apache.poi.ss.usermodel.Sheet;
 import org.apache.poi.ss.usermodel.Workbook;
+import org.apache.poi.xssf.usermodel.XSSFSheet;
 import org.apache.poi.xssf.usermodel.XSSFWorkbook;
 
 public class HeadersAndFooters {
@@ -28,7 +30,7 @@ public class HeadersAndFooters {
 
     public static void main(String[]args) throws Exception {
         Workbook wb = new XSSFWorkbook();
-        Sheet sheet = wb.createSheet("format sheet");
+        Sheet sheet = wb.createSheet("first-header - format sheet");
         sheet.createRow(0).createCell(0).setCellValue(123);
 
         //set page numbers in the footer
@@ -37,9 +39,44 @@ public class HeadersAndFooters {
         //&N == page numbers
         footer.setRight("Page &P of &N");
 
-        // Create various cells and rows for spreadsheet.
+        
+        Header firstHeader=((XSSFSheet)sheet).getFirstHeader();
+        //&F == workbook file name
+        firstHeader.setLeft("&F ......... first header");
+        
+        for(int i=0;i<100;i=i+10){
+            sheet.createRow(i).createCell(0).setCellValue(123);
+        }
+        
+        
+        XSSFSheet sheet2 = (XSSFSheet)wb.createSheet("odd header-even footer");
+        Header oddHeader=sheet2.getOddHeader();
+        //&B == bold
+        //&E == double underline
+        //&D == date
+        oddHeader.setCenter("&B &E oddHeader     &D ");
+        
+        Footer evenFooter=sheet2.getEvenFooter();
+        evenFooter.setRight("even footer &P");
+        sheet2.createRow(10).createCell(0).setCellValue("Second sheet with an oddHeader and an evenFooter");
 
-        FileOutputStream fileOut = new FileOutputStream("pageNumerOnFooter.xlsx");
+        for(int i=0;i<200;i=i+10){
+            sheet2.createRow(i).createCell(0).setCellValue(123);
+        }
+        
+        XSSFSheet sheet3 = (XSSFSheet)wb.createSheet("odd header- odd footer");
+        sheet3.createRow(10).createCell(0).setCellValue("Third sheet with oddHeader and oddFooter");
+        Header oddH=sheet3.getOddHeader();
+        //&C == centered
+        oddH.setCenter("centered oddHeader");
+        oddH.setLeft("left ");
+        oddH.setRight("right ");
+        
+        Footer oddF=sheet3.getOddFooter();
+        oddF.setLeft("Page &P");
+        oddF.setRight("Pages &N ");
+        
+        FileOutputStream fileOut = new FileOutputStream("headerFooter.xlsx");
         wb.write(fileOut);
         fileOut.close();
 

src/examples/src/org/apache/poi/xssf/usermodel/examples/ShiftRows.java

@@ -0,0 +1,61 @@
+/* ====================================================================
+   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.xssf.usermodel.examples;
+
+import java.io.FileOutputStream;
+
+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;
+
+/**
+ * How to shift rows up or down 
+ */
+public class ShiftRows {
+
+    public static void main(String[]args) throws Exception {
+        Workbook wb = new XSSFWorkbook();
+        Sheet sheet = wb.createSheet("Sheet1");
+
+        Row row1 = sheet.createRow(1);
+        row1.createCell(0).setCellValue(1);
+
+        Row row2 = sheet.createRow(4);
+        row2.createCell(1).setCellValue(2);
+
+        Row row3 = sheet.createRow(5);
+        row3.createCell(2).setCellValue(3);
+
+        Row row4 = sheet.createRow(6);
+        row4.createCell(3).setCellValue(4);
+
+        Row row5 = sheet.createRow(9);
+        row5.createCell(4).setCellValue(5);
+
+        // Shift rows 6 - 11 on the spreadsheet to the top (rows 0 - 5)
+        sheet.shiftRows(5, 10, -4);
+
+        FileOutputStream fileOut = new FileOutputStream("shiftRows.xlsx");
+        wb.write(fileOut);
+        fileOut.close();
+
+    }
+
+
+}

src/examples/src/org/apache/poi/xssf/usermodel/examples/SplitAndFreezePanes.java

@@ -0,0 +1,50 @@
+/* ====================================================================
+   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.xssf.usermodel.examples;
+
+import org.apache.poi.ss.usermodel.Workbook;
+import org.apache.poi.ss.usermodel.Sheet;
+import org.apache.poi.xssf.usermodel.XSSFWorkbook;
+
+import java.io.FileOutputStream;
+
+/**
+ * How to set spklit and freeze panes
+ */
+public class SplitAndFreezePanes {
+    public static void main(String[]args) throws Exception {
+        Workbook wb = new XSSFWorkbook();
+        Sheet sheet1 = wb.createSheet("new sheet");
+        Sheet sheet2 = wb.createSheet("second sheet");
+        Sheet sheet3 = wb.createSheet("third sheet");
+        Sheet sheet4 = wb.createSheet("fourth sheet");
+
+        // Freeze just one row
+        sheet1.createFreezePane(0, 1, 0, 1);
+        // Freeze just one column
+        sheet2.createFreezePane(1, 0, 1, 0);
+        // Freeze the columns and rows (forget about scrolling position of the lower right quadrant).
+        sheet3.createFreezePane(2, 2);
+        // Create a split with the lower left side being the active quadrant
+        sheet4.createSplitPane(2000, 2000, 0, 0, Sheet.PANE_LOWER_LEFT);
+
+        FileOutputStream fileOut = new FileOutputStream("splitFreezePane.xlsx");
+        wb.write(fileOut);
+        fileOut.close();
+
+    }
+}

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

@@ -809,4 +809,18 @@ public final class XSSFCell implements Cell {
     public CTCell getCTCell(){
         return cell;
     }
+
+    /**
+     * update cell reference when shifting rows
+     *
+     * @param row
+     */
+    protected void modifyCellReference(XSSFRow row) {
+        this.cell.setR(new CellReference(row.getRowNum(), cellNum).formatAsString());
+
+        CTCell[] ctCells = row.getCTRow().getCArray();
+        for (CTCell ctCell : ctCells) {
+            ctCell.setR(new CellReference(row.getRowNum(), cellNum).formatAsString());
+        }
+    }
 }

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

@@ -21,16 +21,39 @@ import org.apache.poi.ss.usermodel.Footer;
 import org.apache.poi.xssf.usermodel.extensions.XSSFHeaderFooter;
 import org.openxmlformats.schemas.spreadsheetml.x2006.main.CTHeaderFooter;
 
+/**
+ * 
+ * Even page footer value. Corresponds to even printed pages. 
+ * Even page(s) in the sheet may not be printed, for example, if the print area is specified to be 
+ * a range such that it falls outside an even page's scope. 
+ * If no even footer is specified, then the odd footer's value is assumed for even page footers. 
+ *
+ */
 public class XSSFEvenFooter extends XSSFHeaderFooter implements Footer{
-
+    
+    /**
+     * Create an instance of XSSFEvenFooter from the supplied XML bean
+     * @see XSSFSheet#getEvenFooter()
+     * @param headerFooter
+     */
     public XSSFEvenFooter(CTHeaderFooter headerFooter) {
         super(headerFooter);
+        headerFooter.setDifferentOddEven(true);
     }
     
+    /**
+     * Get the content text representing the footer
+     * @return text
+     */
     public String getText() {
         return getHeaderFooter().getEvenFooter();
     }
     
+    /**
+     * Set a text for the footer. If null unset the value.
+     * @see XSSFHeaderFooter to see how to create a string with Header/Footer Formatting Syntax
+     * @param text - a string representing the footer. 
+     */
     public void setText(String text) {
     	if(text == null) {
     		getHeaderFooter().unsetEvenFooter();

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

@@ -21,22 +21,47 @@ import org.apache.poi.ss.usermodel.Header;
 import org.apache.poi.xssf.usermodel.extensions.XSSFHeaderFooter;
 import org.openxmlformats.schemas.spreadsheetml.x2006.main.CTHeaderFooter;
 
+/**
+ * <p>
+ * Even page header value. Corresponds to even printed pages.
+ * Even page(s) in the sheet may not be printed, for example, if the print area is specified to be 
+ * a range such that it falls outside an even page's scope.
+ * If no even header is specified, then odd header value is assumed for even page headers.
+ *</p>
+ *
+ */
 public class XSSFEvenHeader extends XSSFHeaderFooter implements Header{
 
+    /**
+     * Create an instance of XSSFEvenHeader from the supplied XML bean
+     * @see XSSFSheet#getEvenHeader()
+     * @param headerFooter
+     */
     public XSSFEvenHeader(CTHeaderFooter headerFooter) {
-        super(headerFooter);
+	super(headerFooter);
+	headerFooter.setDifferentOddEven(true);
     }
-    
+
+    /**
+     * Get the content text representing this header
+     * @return text
+     */
     public String getText() {
-        return getHeaderFooter().getEvenHeader();
+	return getHeaderFooter().getEvenHeader();
     }
-    
+
+    /**
+     * Set a text for the header. If null unset the value
+     * @see XSSFHeaderFooter to see how to create a string with Header/Footer Formatting Syntax
+     * @param text - a string representing the header. 
+     */
     public void setText(String text) {
-    	if(text == null) {
-    		getHeaderFooter().unsetEvenHeader();
-    	} else {
-    		getHeaderFooter().setEvenHeader(text);
-    	}
+	if(text == null) {
+	    getHeaderFooter().unsetEvenHeader();
+	} else {
+	    getHeaderFooter().setEvenHeader(text);
+	}
     }
 
+    
 }

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

@@ -21,16 +21,38 @@ import org.apache.poi.ss.usermodel.Footer;
 import org.apache.poi.xssf.usermodel.extensions.XSSFHeaderFooter;
 import org.openxmlformats.schemas.spreadsheetml.x2006.main.CTHeaderFooter;
 
+/**
+ * 
+ * First page footer content. Corresponds to first printed page.  
+ * The first logical page in the sheet may not be printed, for example, if the print area is specified to 
+ * be a range such that it falls outside the first page's scope.
+ * 
+ */
 public class XSSFFirstFooter extends XSSFHeaderFooter implements Footer{
 
+    /**
+     * Create an instance of XSSFFirstFooter from the supplied XML bean
+     * @see XSSFSheet#getFirstFooter()
+     * @param headerFooter
+     */
     protected XSSFFirstFooter(CTHeaderFooter headerFooter) {
         super(headerFooter);
+        headerFooter.setDifferentFirst(true);
     }
     
+    /**
+     * Get the content text representing the footer
+     * @return text
+     */
     public String getText() {
         return getHeaderFooter().getFirstFooter();
     }
     
+    /**
+     * Set a text for the footer. If null unset the value.
+     * @see XSSFHeaderFooter to see how to create a string with Header/Footer Formatting Syntax
+     * @param text - a string representing the footer. 
+     */
     public void setText(String text) {
     	if(text == null) {
     		getHeaderFooter().unsetFirstFooter();

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

@@ -21,16 +21,38 @@ import org.apache.poi.ss.usermodel.Header;
 import org.apache.poi.xssf.usermodel.extensions.XSSFHeaderFooter;
 import org.openxmlformats.schemas.spreadsheetml.x2006.main.CTHeaderFooter;
 
+/**
+ * 
+ * First page header content. Corresponds to first printed page.
+ * The first logical page in the sheet may not be printed, for example, if the print area is specified to 
+ * be a range such that it falls outside the first page's scope.
+ *
+ */
 public class XSSFFirstHeader extends XSSFHeaderFooter implements Header{
 
+    /**
+     * Create an instance of XSSFFirstHeader from the supplied XML bean
+     * @see XSSFSheet#getFirstHeader()
+     * @param headerFooter
+     */
     protected XSSFFirstHeader(CTHeaderFooter headerFooter) {
         super(headerFooter);
+        headerFooter.setDifferentFirst(true);
     }
     
+    /**
+     * Get the content text representing this header
+     * @return text
+     */
     public String getText() {
         return getHeaderFooter().getFirstHeader();
     }
     
+    /**
+     * Set a text for the header. If null unset the value
+     * @see XSSFHeaderFooter to see how to create a string with Header/Footer Formatting Syntax
+     * @param text - a string representing the header. 
+     */
     public void setText(String text) {
     	if(text == null) {
     		getHeaderFooter().unsetFirstHeader();

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

@@ -21,16 +21,36 @@ import org.apache.poi.ss.usermodel.Footer;
 import org.apache.poi.xssf.usermodel.extensions.XSSFHeaderFooter;
 import org.openxmlformats.schemas.spreadsheetml.x2006.main.CTHeaderFooter;
 
+/**
+ * Odd page footer value. Corresponds to odd printed pages.
+ * Odd page(s) in the sheet may not be printed, for example, if the print area is specified to be 
+ * a range such that it falls outside an odd page's scope.
+ *
+ */
 public class XSSFOddFooter extends XSSFHeaderFooter implements Footer{
 
+    /**
+     * Create an instance of XSSFOddFooter from the supplied XML bean
+     * @see XSSFSheet#getOddFooter()
+     * @param headerFooter
+     */
     public XSSFOddFooter(CTHeaderFooter headerFooter) {
         super(headerFooter);
     }
     
+    /**
+     * Get the content text representing the footer
+     * @return text
+     */
     public String getText() {
         return getHeaderFooter().getOddFooter();
     }
     
+    /**
+     * Set a text for the footer. If null unset the value.
+     * @see XSSFHeaderFooter to see how to create a string with Header/Footer Formatting Syntax
+     * @param text - a string representing the footer. 
+     */
     public void setText(String text) {
     	if(text == null) {
     		getHeaderFooter().unsetOddFooter();

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

@@ -21,16 +21,36 @@ import org.apache.poi.ss.usermodel.Header;
 import org.apache.poi.xssf.usermodel.extensions.XSSFHeaderFooter;
 import org.openxmlformats.schemas.spreadsheetml.x2006.main.CTHeaderFooter;
 
+/**
+ * Odd page header value. Corresponds to odd printed pages. 
+ * Odd page(s) in the sheet may not be printed, for example, if the print area is specified to be 
+ * a range such that it falls outside an odd page's scope.
+ *
+ */
 public class XSSFOddHeader extends XSSFHeaderFooter implements Header{
 
+    /**
+     * Create an instance of XSSFOddHeader from the supplied XML bean
+     * @see XSSFSheet#getOddHeader()
+     * @param headerFooter
+     */
     protected XSSFOddHeader(CTHeaderFooter headerFooter) {
         super(headerFooter);
     }
     
+    /**
+     * Get the content text representing this header
+     * @return text
+     */
     public String getText() {
         return getHeaderFooter().getOddHeader();
     }
     
+    /**
+     * Set a text for the header. If null unset the value
+     * @see XSSFHeaderFooter to see how to create a string with Header/Footer Formatting Syntax
+     * @param text - a string representing the header. 
+     */
     public void setText(String text) {
     	if(text == null) {
     		getHeaderFooter().unsetOddHeader();

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

@@ -267,22 +267,23 @@ public class XSSFRow implements Row, Comparable<XSSFRow> {
      * @param height the height in "twips" or  1/20th of a point. <code>-1</code>  resets to the default height
      */
     public void setHeight(short height) {
-    	if(height == -1){
-            this.row.unsetHt();
-            this.row.unsetCustomHeight();
+        if (height == -1) {
+            if (row.isSetHt()) row.unsetHt();
+            if (row.isSetCustomHeight()) row.unsetCustomHeight();
         } else {
-            this.row.setHt((double)height/20);
-            this.row.setCustomHeight(true);
+            row.setHt((double) height / 20);
+            row.setCustomHeight(true);
 
         }
     }
+
     /**
      * Set the row's height in points.
      *
      * @param height the height in points. <code>-1</code>  resets to the default height
      */
     public void setHeightInPoints(float height) {
-	    setHeight((short)(height*20));
+	    setHeight((short)(height == -1 ? -1 : (height*20)));
     }
 
     /**

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

@@ -1412,9 +1412,11 @@ public class XSSFSheet extends POIXMLDocumentPart implements Sheet {
     public void shiftRows(int startRow, int endRow, int n, boolean copyRowHeight, boolean resetOriginalRowHeight) {
         for (Iterator<Row> it = rowIterator() ; it.hasNext() ; ) {
             Row row = it.next();
+
             if (!copyRowHeight) {
                 row.setHeight((short)-1);
             }
+
             if (resetOriginalRowHeight && getDefaultRowHeight() >= 0) {
                 row.setHeight(getDefaultRowHeight());
             }
@@ -1423,6 +1425,9 @@ public class XSSFSheet extends POIXMLDocumentPart implements Sheet {
             }
             else if (row.getRowNum() >= startRow && row.getRowNum() <= endRow) {
                 row.setRowNum(row.getRowNum() + n);
+                if (row.getFirstCellNum() > -1) {
+                    modifyCellReference((XSSFRow) row);
+                }
             }
         }
         //rebuild the rows map
@@ -1431,6 +1436,16 @@ public class XSSFSheet extends POIXMLDocumentPart implements Sheet {
         rows = map;
     }
 
+
+    private void modifyCellReference(XSSFRow row) {
+        for (int i = row.getFirstCellNum(); i <= row.getLastCellNum(); i++) {
+            XSSFCell c = row.getCell(i);
+            if (c != null) {
+                c.modifyCellReference(row);
+            }
+        }
+    }
+
     /**
      * Location of the top left visible cell Location of the top left visible cell in the bottom right
      * pane (when in Left-to-Right mode).

src/ooxml/java/org/apache/poi/xssf/usermodel/extensions/XSSFHeaderFooter.java

@@ -18,6 +18,7 @@
 package org.apache.poi.xssf.usermodel.extensions;
 
 import org.apache.poi.ss.usermodel.HeaderFooter;
+import org.apache.poi.xssf.usermodel.XSSFSheet;
 import org.apache.poi.xssf.usermodel.helpers.HeaderFooterHelper;
 import org.openxmlformats.schemas.spreadsheetml.x2006.main.CTHeaderFooter;
 
@@ -26,24 +27,94 @@ import org.openxmlformats.schemas.spreadsheetml.x2006.main.CTHeaderFooter;
  * 
  * For a list of all the different fields that can be
  *  placed into a header or footer, such as page number,
- *  bold, underline etc, see 
- *  {@link org.apache.poi.hssf.usermodel.HeaderFooter}.
+ *  bold, underline etc, see the follow formatting syntax
+ *  
+ *<b> Header/Footer Formatting Syntax</b>
+ *<p>
+ * There are a number of formatting codes that can be written inline with the actual header / footer text, which
+ * affect the formatting in the header or footer.
+ *</p>
+ *
+ * This example shows the text "Center Bold Header" on the first line (center section), and the date on the second
+ * line (center section).
+ * &CCenter &"-,Bold"Bold &"-,Regular"Header_x000A_&D
+ * 
+ * <b>General Rules:</b>
+ * There is no required order in which these codes must appear.
+ * The first occurrence of the following codes turns the formatting ON, the second occurrence turns it OFF again:
+ * 
+ * <dl>
+ * <dt> &L </dt> <dd>code for "left section" (there are three header / footer locations, "left", "center", and "right"). When
+ * two or more occurrences of this section marker exist, the contents from all markers are concatenated, in the
+ * order of appearance, and placed into the left section.</dd>
+ * <dt> &P </dt> <dd> code for "current page #"</dd>
+ * <dt> &N </dt> <dd> code for "total pages"</dd>
+ * <dt>&font size </dt> <dd> code for "text font size", where font size is a font size in points.</dd>
+ * <dt> &K </dt> <dd> code for "text font color"
+ * RGB Color is specified as RRGGBB
+ * Theme Color is specifed as TTSNN where TT is the theme color Id, S is either "+" or "-" of the tint/shade
+ * value, NN is the tint/shade value.</dd>
+ * <dt> &S </dt> <dd> code for "text strikethrough" on / off</dd>
+ * <dt> &X </dt> <dd> code for "text super script" on / off</dd>
+ * <dt> &Y </dt> <dd> code for "text subscript" on / off</dd>
+ * <dt> &C </dt> <dd> code for "center section". When two or more occurrences of this section marker exist, the contents
+ * from all markers are concatenated, in the order of appearance, and placed into the center section.
+ * SpreadsheetML Reference Material - Worksheets 1966</dd>
+ * <dt> &D </dt> <dd> code for "date"</dd>
+ * <dt> &T </dt> <dd> code for "time"</dd>
+ * <dt> &G </dt> <dd> code for "picture as background"</dd>
+ * <dt> &U </dt> <dd> code for "text single underline"</dd>
+ * <dt> &E </dt> <dd> code for "double underline"</dd>
+ * <dt> &R </dt> <dd> code for "right section". When two or more occurrences of this section marker exist, the contents
+ * from all markers are concatenated, in the order of appearance, and placed into the right section.</dd>
+ * <dt> &Z </dt> <dd> code for "this workbook's file path"</dd>
+ * <dt> &F </dt> <dd> code for "this workbook's file name"</dd>
+ * <dt> &A </dt> <dd> code for "sheet tab name"</dd>
+ * <dt> &+ </dt> <dd> code for add to page #.</dd>
+ * <dt> &- </dt> <dd> code for subtract from page #.</dd>
+ * <dt> &"font name,font type" - code for "text font name" and "text font type", where font name and font type
+ * are strings specifying the name and type of the font, separated by a comma. When a hyphen appears in font
+ * name, it means "none specified". Both of font name and font type can be localized values.</dd>
+ * <dt> &"-,Bold" </dt> <dd> code for "bold font style"</dd>
+ * <dt> &B </dt> <dd> also means "bold font style"</dd>
+ * <dt> &"-,Regular" </dt> <dd> code for "regular font style"</dd>
+ * <dt> &"-,Italic" </dt> <dd> code for "italic font style"</dd>
+ * <dt> &I </dt> <dd> also means "italic font style"</dd>
+ * <dt> &"-,Bold Italic" </dt> <dd> code for "bold italic font style"</dd>
+ * <dt> &O </dt> <dd> code for "outline style"</dd>
+ * <dt> &H </dt> <dd> code for "shadow style"</dd>
+ * </dl>
+ *  
+ *  
  */
 public abstract class XSSFHeaderFooter implements HeaderFooter {
     private HeaderFooterHelper helper;
     private CTHeaderFooter headerFooter;
 
 	private boolean stripFields = false;
-	
+
+	/**
+	 * Create an instance of XSSFHeaderFooter from the supplied XML bean
+	 * @param headerFooter
+	 */
     public XSSFHeaderFooter(CTHeaderFooter headerFooter) {
        this.headerFooter = headerFooter;
        this.helper = new HeaderFooterHelper();
     }
     
+    /**
+     * Returns the underlying CTHeaderFooter xml bean 
+     *
+     * @return the underlying CTHeaderFooter xml bean
+     */
     public CTHeaderFooter getHeaderFooter() {
         return this.headerFooter;
     }
 
+    /**
+     * 
+     * @return
+     */
     public String getValue() {
         String value = getText();
         if(value == null)
@@ -69,7 +140,14 @@ public abstract class XSSFHeaderFooter implements HeaderFooter {
 	public void setAreFieldsStripped(boolean stripFields) {
 		this.stripFields = stripFields;
 	}
-	
+
+	/**
+	 * Removes any fields (eg macros, page markers etc)
+	 *  from the string.
+	 * Normally used to make some text suitable for showing
+	 *  to humans, and the resultant text should not normally
+	 *  be saved back into the document!
+	 */
 	public static String stripFields(String text) {
 		return org.apache.poi.hssf.usermodel.HeaderFooter.stripFields(text);
 	}
@@ -79,6 +157,9 @@ public abstract class XSSFHeaderFooter implements HeaderFooter {
     
     protected abstract void setText(String text);
 
+    /**
+     * get the text representing the center part of this element
+     */
     public String getCenter() {
     	String text = helper.getCenterSection(getText()); 
     	if(stripFields)
@@ -86,6 +167,9 @@ public abstract class XSSFHeaderFooter implements HeaderFooter {
         return text;
     }
 
+    /**
+     * get the text representing the left part of this element
+     */
     public String getLeft() {
         String text = helper.getLeftSection(getText());
     	if(stripFields)
@@ -93,6 +177,9 @@ public abstract class XSSFHeaderFooter implements HeaderFooter {
         return text;
     }
 
+    /**
+     * get the text representing the right part of this element
+     */
     public String getRight() {
         String text = helper.getRightSection(getText());
     	if(stripFields)
@@ -100,14 +187,23 @@ public abstract class XSSFHeaderFooter implements HeaderFooter {
         return text;
     }
 
+    /**
+     * set a centered string value for this element 
+     */
     public void setCenter(String newCenter) {
         setText(helper.setCenterSection(getText(), newCenter));
     }
 
+    /**
+     * set a left string value for this element 
+     */
     public void setLeft(String newLeft) {
         setText(helper.setLeftSection(getText(), newLeft));
     }
 
+    /**
+     * set a right string value for this element 
+     */
     public void setRight(String newRight) {
         setText(helper.setRightSection(getText(), newRight));
     }