javadocs and Quick page improvements for XSSF Header/Footer

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

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

@@ -22,12 +22,20 @@ import org.apache.poi.xssf.usermodel.extensions.XSSFHeaderFooter;
 import org.openxmlformats.schemas.spreadsheetml.x2006.main.CTHeaderFooter;
 
 /**
- * 
+ * <p>
  * 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. 
- *
+ * </p><p>
+ * The even footer is activated by the "Different Even/Odd" Header/Footer property for the sheet.
+ * If this property is not set, the even footer is ignored, and the odd footer is used instead.
+ * </p><p>
+ * Creating an even header or footer sets this property by default, so all you need to do to
+ * get an even header or footer to display is to create one. Likewise, if both the even header
+ * and footer are usnset, then this property is unset, and the odd header and footer are used 
+ * for even pages.
+ * </p>
  */
 public class XSSFEvenFooter extends XSSFHeaderFooter implements Footer{
     
@@ -45,15 +53,20 @@ public class XSSFEvenFooter extends XSSFHeaderFooter implements Footer{
      * Get the content text representing the footer
      * @return text
      */
+    @Override
     public String getText() {
         return getHeaderFooter().getEvenFooter();
     }
     
     /**
-     * Set a text for the footer. If null unset the value.
+     * Set a text for the footer. If null, unset the value. If unsetting and there is no
+     * Even Header for this sheet, the "DifferentEvenOdd" property for this sheet is
+     * unset.
+     * 
      * @see XSSFHeaderFooter to see how to create a string with Header/Footer Formatting Syntax
      * @param text - a string representing the footer. 
      */
+    @Override
     public void setText(String text) {
     	if(text == null) {
     		getHeaderFooter().unsetEvenFooter();

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

@@ -27,13 +27,21 @@ import org.openxmlformats.schemas.spreadsheetml.x2006.main.CTHeaderFooter;
  * 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><p>
+ * The even header is activated by the "Different Even/Odd" Header/Footer property for the sheet.
+ * If this property is not set, the even header is ignored, and the odd footer is used instead.
+ * </p><p>
+ * Creating an even header or footer sets this property by default, so all you need to do to
+ * get an even header or footer to display is to create it. Likewise, if both the even header
+ * and footer are usnset, then this property is unset, and the odd header and footer are used
+ * for even pages.
  * </p>
- *
  */
 public class XSSFEvenHeader extends XSSFHeaderFooter implements Header {
 
     /**
-     * Create an instance of XSSFEvenHeader from the supplied XML bean
+     * Create an instance of XSSFEvenHeader from the supplied XML bean. If an even
+     * header is created, The property "DifferentOddEven" is set for this sheet as well.
      * 
      * @see XSSFSheet#getEvenHeader()
      * @param headerFooter
@@ -48,18 +56,22 @@ public class XSSFEvenHeader extends XSSFHeaderFooter implements Header {
      * 
      * @return text
      */
+    @Override
     public String getText() {
         return getHeaderFooter().getEvenHeader();
     }
 
     /**
-     * Set a text for the header. If null unset the value
+     * Set a text for the header. If null, unset the value. If unsetting and there is no
+     * Even Footer for this sheet, the "DifferentEvenOdd" property for this sheet is
+     * unset.
      * 
      * @see XSSFHeaderFooter to see how to create a string with Header/Footer
      *      Formatting Syntax
      * @param text
      *            - a string representing the header.
      */
+    @Override
     public void setText(String text) {
         if (text == null) {
             getHeaderFooter().unsetEvenHeader();

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

@@ -22,11 +22,19 @@ import org.apache.poi.xssf.usermodel.extensions.XSSFHeaderFooter;
 import org.openxmlformats.schemas.spreadsheetml.x2006.main.CTHeaderFooter;
 
 /**
- * 
+ * <p>
  * 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.
- * 
+ * </p><p>
+ * The first page footer is activated by the "Different First" Header/Footer property for the sheet.
+ * If this property is not set, the first page footer is ignored.
+ * </p><p>
+ * Creating a first page header or footer sets this property by default, so all you need to do to
+ * get an first page header or footer to display is to create one. Likewise, if both the first page
+ * header and footer are usnset, then this property is unset, and the first page header and footer
+ * are ignored.
+ * </p>
  */
 public class XSSFFirstFooter extends XSSFHeaderFooter implements Footer{
 
@@ -44,15 +52,19 @@ public class XSSFFirstFooter extends XSSFHeaderFooter implements Footer{
      * Get the content text representing the footer
      * @return text
      */
+    @Override
     public String getText() {
         return getHeaderFooter().getFirstFooter();
     }
     
     /**
-     * Set a text for the footer. If null unset the value.
+     * Set a text for the footer. If null unset the value. If unsetting this header results 
+     * in no First Header, or footer for the sheet, the 'differentFirst' property is unset as well.
+     *  
      * @see XSSFHeaderFooter to see how to create a string with Header/Footer Formatting Syntax
      * @param text - a string representing the footer. 
      */
+    @Override
     public void setText(String text) {
     	if(text == null) {
     		getHeaderFooter().unsetFirstFooter();

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

@@ -22,11 +22,19 @@ import org.apache.poi.xssf.usermodel.extensions.XSSFHeaderFooter;
 import org.openxmlformats.schemas.spreadsheetml.x2006.main.CTHeaderFooter;
 
 /**
- * 
+ * <p>
  * 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.
- *
+ * </p><p>
+ * The first page header is activated by the "Different First" Header/Footer property for the sheet.
+ * If this property is not set, the first page header is ignored.
+ * </p><p>
+ * Creating a first page header or footer sets this property by default, so all you need to do to
+ * get an first page header or footer to display is to create one. Likewise, if both the first page
+ * header and footer are usnset, then this property is unset, and the first page header and footer
+ * are ignored.
+ * </p>
  */
 public class XSSFFirstHeader extends XSSFHeaderFooter implements Header{
 
@@ -44,15 +52,19 @@ public class XSSFFirstHeader extends XSSFHeaderFooter implements Header{
      * Get the content text representing this header
      * @return text
      */
+    @Override
     public String getText() {
         return getHeaderFooter().getFirstHeader();
     }
     
     /**
-     * Set a text for the header. If null unset the value
+     * Set a text for the header. If null unset the value. If unsetting this header results 
+     * in no First Header, or footer for the sheet, the 'differentFirst' property is unset as well.
+     *  
      * @see XSSFHeaderFooter to see how to create a string with Header/Footer Formatting Syntax
      * @param text - a string representing the header. 
      */
+    @Override
     public void setText(String text) {
     	if(text == null) {
     		getHeaderFooter().unsetFirstHeader();

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

@@ -21,12 +21,18 @@ import org.apache.poi.util.Internal;
 import org.openxmlformats.schemas.spreadsheetml.x2006.main.CTHeaderFooter;
 
 /**
+ * <p>
+ * All Header/Footer properties for a sheet are scoped to the sheet. This includes Different First Page,
+ * and Different Even/Odd. These properties can be set or unset explicitly in this class. Note that while
+ * Scale With Document and Align With Margins default to unset, Different First, and Different Even/Odd
+ * are updated automatically as headers and footers are added and removed. 
+ * </p>
  */
 public class XSSFHeaderFooterProperties {
 	private CTHeaderFooter headerFooter;
 
 	/**
-	 * Create an instance of XSSFAbstractHeaderFooter from the supplied XML bean
+	 * Create an instance of XSSFHeaderFooterProperties from the supplied XML bean
 	 *
 	 * @param headerFooter
 	 */

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

@@ -42,6 +42,7 @@ public class XSSFOddFooter extends XSSFHeaderFooter implements Footer{
      * Get the content text representing the footer
      * @return text
      */
+    @Override
     public String getText() {
         return getHeaderFooter().getOddFooter();
     }
@@ -51,6 +52,7 @@ public class XSSFOddFooter extends XSSFHeaderFooter implements Footer{
      * @see XSSFHeaderFooter to see how to create a string with Header/Footer Formatting Syntax
      * @param text - a string representing the footer. 
      */
+    @Override
     public void setText(String text) {
     	if(text == null) {
     		getHeaderFooter().unsetOddFooter();

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

@@ -42,6 +42,7 @@ public class XSSFOddHeader extends XSSFHeaderFooter implements Header{
      * Get the content text representing this header
      * @return text
      */
+    @Override
     public String getText() {
         return getHeaderFooter().getOddHeader();
     }
@@ -51,6 +52,7 @@ public class XSSFOddHeader extends XSSFHeaderFooter implements Header{
      * @see XSSFHeaderFooter to see how to create a string with Header/Footer Formatting Syntax
      * @param text - a string representing the header. 
      */
+    @Override
     public void setText(String text) {
     	if(text == null) {
     		getHeaderFooter().unsetOddHeader();

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

@@ -146,6 +146,11 @@ public abstract class XSSFHeaderFooter implements HeaderFooter {
 		return this.headerFooter;
 	}
 
+    /**
+     * Returns the value of the header or footer.
+     *
+     * @return the value of the header or footer.
+     */
 	public String getValue() {
 		String value = getText();
 		if (value == null)
@@ -187,6 +192,7 @@ public abstract class XSSFHeaderFooter implements HeaderFooter {
 	/**
 	 * get the text representing the center part of this element
 	 */
+	@Override
 	public String getCenter() {
 		String text = helper.getCenterSection(getText());
 		if (stripFields)
@@ -197,6 +203,7 @@ public abstract class XSSFHeaderFooter implements HeaderFooter {
 	/**
 	 * get the text representing the left part of this element
 	 */
+	@Override
 	public String getLeft() {
 		String text = helper.getLeftSection(getText());
 		if (stripFields)
@@ -207,6 +214,7 @@ public abstract class XSSFHeaderFooter implements HeaderFooter {
 	/**
 	 * get the text representing the right part of this element
 	 */
+	@Override
 	public String getRight() {
 		String text = helper.getRightSection(getText());
 		if (stripFields)
@@ -217,6 +225,7 @@ public abstract class XSSFHeaderFooter implements HeaderFooter {
 	/**
 	 * set a centered string value for this element
 	 */
+	@Override
 	public void setCenter(String newCenter) {
 		setText(helper.setCenterSection(getText(), newCenter));
 	}
@@ -224,6 +233,7 @@ public abstract class XSSFHeaderFooter implements HeaderFooter {
 	/**
 	 * set a left string value for this element
 	 */
+	@Override
 	public void setLeft(String newLeft) {
 		setText(helper.setLeftSection(getText(), newLeft));
 	}
@@ -231,6 +241,7 @@ public abstract class XSSFHeaderFooter implements HeaderFooter {
 	/**
 	 * set a right string value for this element
 	 */
+	@Override
 	public void setRight(String newRight) {
 		setText(helper.setRightSection(getText(), newRight));
 	}