From 9d0010088b2295278fe718f278216f129ac62c91 Mon Sep 17 00:00:00 2001 From: Mark Murphy Date: Sun, 19 Nov 2017 01:35:07 +0000 Subject: [PATCH] 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 --- .../poi/xssf/usermodel/XSSFEvenFooter.java | 19 ++++++++++++++++--- .../poi/xssf/usermodel/XSSFEvenHeader.java | 18 +++++++++++++++--- .../poi/xssf/usermodel/XSSFFirstFooter.java | 18 +++++++++++++++--- .../poi/xssf/usermodel/XSSFFirstHeader.java | 18 +++++++++++++++--- .../usermodel/XSSFHeaderFooterProperties.java | 8 +++++++- .../poi/xssf/usermodel/XSSFOddFooter.java | 2 ++ .../poi/xssf/usermodel/XSSFOddHeader.java | 2 ++ .../extensions/XSSFHeaderFooter.java | 11 +++++++++++ 8 files changed, 83 insertions(+), 13 deletions(-) diff --git a/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFEvenFooter.java b/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFEvenFooter.java index 0b2dad42cd..8234793c3e 100644 --- a/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFEvenFooter.java +++ b/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; /** - * + *

* 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. - * + *

+ * 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. + *

+ * 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. + *

*/ 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(); diff --git a/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFEvenHeader.java b/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFEvenHeader.java index c6b7444dfa..dfd9d179b8 100644 --- a/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFEvenHeader.java +++ b/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. + *

+ * 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. + *

+ * 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. *

- * */ 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(); diff --git a/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFFirstFooter.java b/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFFirstFooter.java index 711292397e..4bccf9ef1e 100644 --- a/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFFirstFooter.java +++ b/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; /** - * + *

* 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. - * + *

+ * 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. + *

+ * 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. + *

*/ 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(); diff --git a/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFFirstHeader.java b/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFFirstHeader.java index 9c5d6e8055..4cb2254d2f 100644 --- a/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFFirstHeader.java +++ b/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; /** - * + *

* 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. - * + *

+ * 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. + *

+ * 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. + *

*/ 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(); diff --git a/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFHeaderFooterProperties.java b/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFHeaderFooterProperties.java index eab6f125eb..af3f8c29fc 100644 --- a/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFHeaderFooterProperties.java +++ b/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; /** + *

+ * 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. + *

*/ 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 */ diff --git a/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFOddFooter.java b/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFOddFooter.java index 6d422dd688..1e2239d8d3 100644 --- a/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFOddFooter.java +++ b/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(); diff --git a/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFOddHeader.java b/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFOddHeader.java index ba5c1a06f6..1cce6e59be 100644 --- a/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFOddHeader.java +++ b/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(); diff --git a/src/ooxml/java/org/apache/poi/xssf/usermodel/extensions/XSSFHeaderFooter.java b/src/ooxml/java/org/apache/poi/xssf/usermodel/extensions/XSSFHeaderFooter.java index a21a4254bf..2ab58f6fa0 100644 --- a/src/ooxml/java/org/apache/poi/xssf/usermodel/extensions/XSSFHeaderFooter.java +++ b/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)); } -- 2.39.5