You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@poi.apache.org by jm...@apache.org on 2017/11/19 01:35:07 UTC
svn commit: r1815706 - in /poi:
site/src/documentation/content/xdocs/spreadsheet/
trunk/src/ooxml/java/org/apache/poi/xssf/usermodel/
trunk/src/ooxml/java/org/apache/poi/xssf/usermodel/extensions/
Author: jmarkmurphy
Date: Sun Nov 19 01:35:07 2017
New Revision: 1815706
URL: http://svn.apache.org/viewvc?rev=1815706&view=rev
Log:
javadocs and Quick page improvements for XSSF Header/Footer
Modified:
poi/site/src/documentation/content/xdocs/spreadsheet/quick-guide.xml
poi/trunk/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFEvenFooter.java
poi/trunk/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFEvenHeader.java
poi/trunk/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFFirstFooter.java
poi/trunk/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFFirstHeader.java
poi/trunk/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFHeaderFooterProperties.java
poi/trunk/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFOddFooter.java
poi/trunk/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFOddHeader.java
poi/trunk/src/ooxml/java/org/apache/poi/xssf/usermodel/extensions/XSSFHeaderFooter.java
Modified: poi/site/src/documentation/content/xdocs/spreadsheet/quick-guide.xml
URL: http://svn.apache.org/viewvc/poi/site/src/documentation/content/xdocs/spreadsheet/quick-guide.xml?rev=1815706&r1=1815705&r2=1815706&view=diff
==============================================================================
--- poi/site/src/documentation/content/xdocs/spreadsheet/quick-guide.xml (original)
+++ poi/site/src/documentation/content/xdocs/spreadsheet/quick-guide.xml Sun Nov 19 01:35:07 2017
@@ -60,6 +60,7 @@
<li><link href="#Splits">Create split and freeze panes</link></li>
<li><link href="#Repeating">Repeating rows and columns</link></li>
<li><link href="#HeaderFooter">Headers and Footers</link></li>
+ <li><link href="#XSSFHeaderFooter">XSSF enhancement for Headers and Footers</link></li>
<li><link href="#DrawingShapes">Drawing Shapes</link></li>
<li><link href="#StylingShapes">Styling Shapes</link></li>
<li><link href="#Graphics2d">Shapes and Graphics2d</link></li>
@@ -989,6 +990,58 @@ Examples:
wb.write(fileOut);
fileOut.close();
</source>
+ </section>
+ <anchor id="XSSFHeaderFooter"/>
+ <section><title>XSSF Enhancement for Headers and Footers</title>
+ <p>
+ Example is for headers but applies directly to footers. Note, the above example for
+ basic headers and footers applies to XSSF Workbooks as well as HSSF Workbooks. The HSSFHeader
+ stuff does not work for XSSF Workbooks.
+ </p>
+ <p>
+ XSSF has the ability to handle First page headers and footers, as well as Even/Odd
+ headers and footers. All Header/Footer Property flags can be handled in XSSF as well.
+ The odd header and footer is the default header and footer. It is displayed on all
+ pages that do not display either a first page header or an even page header. That is,
+ if the Even header/footer does not exist, then the odd header/footer is displayed on
+ even pages. If the first page header/footer does not exist, then the odd header/footer
+ is displayed on the first page. If the even/odd property is not set, that is the same as
+ the even header/footer not existing. If the first page property does not exist, that is
+ the same as the first page header/footer not existing.
+ </p>
+ <source>
+ Workbook wb = new XSSFWorkbook();
+ XSSFSheet sheet = (XSSFSheet) wb.createSheet("new sheet");
+
+ // Create a first page header
+ Header header = sheet.getFirstHeader();
+ header.setCenter("Center First Page Header");
+ header.setLeft("Left First Page Header");
+ header.setRight("Right First Page Header");
+
+ // Create an even page header
+ Header header2 = sheet.getEvenHeader();
+ header2.setCenter("Center Even Page Header");
+ header2.setLeft("Left Even Page Header");
+ header2.setRight("Right Even Page Header");
+
+ // Create an odd page header
+ Header header3 = sheet.getOddHeader();
+ header3.setCenter("Center Odd Page Header");
+ header3.setLeft("Left Odd Page Header");
+ header3.setRight("Right Odd Page Header");
+
+ // Set/Remove Header properties
+ XSSFHeaderProperties prop = sheet.getHeaderFooterProperties();
+ prop.setAlignWithMargins();
+ prop.scaleWithDoc();
+ prop.removeDifferentFirstPage(); // This does not remove first page headers or footers
+ prop.removeDifferentEvenOdd(); // This does not remove even headers or footers
+
+ FileOutputStream fileOut = new FileOutputStream("workbook.xlsx");
+ wb.write(fileOut);
+ fileOut.close();
+ </source>
</section>
<anchor id="DrawingShapes"/>
Modified: poi/trunk/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFEvenFooter.java
URL: http://svn.apache.org/viewvc/poi/trunk/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFEvenFooter.java?rev=1815706&r1=1815705&r2=1815706&view=diff
==============================================================================
--- poi/trunk/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFEvenFooter.java (original)
+++ poi/trunk/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFEvenFooter.java Sun Nov 19 01:35:07 2017
@@ -22,12 +22,20 @@ import org.apache.poi.xssf.usermodel.ext
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 XSSF
* 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();
Modified: poi/trunk/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFEvenHeader.java
URL: http://svn.apache.org/viewvc/poi/trunk/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFEvenHeader.java?rev=1815706&r1=1815705&r2=1815706&view=diff
==============================================================================
--- poi/trunk/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFEvenHeader.java (original)
+++ poi/trunk/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFEvenHeader.java Sun Nov 19 01:35:07 2017
@@ -27,13 +27,21 @@ import org.openxmlformats.schemas.spread
* 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 XSSF
*
* @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();
Modified: poi/trunk/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFFirstFooter.java
URL: http://svn.apache.org/viewvc/poi/trunk/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFFirstFooter.java?rev=1815706&r1=1815705&r2=1815706&view=diff
==============================================================================
--- poi/trunk/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFFirstFooter.java (original)
+++ poi/trunk/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFFirstFooter.java Sun Nov 19 01:35:07 2017
@@ -22,11 +22,19 @@ import org.apache.poi.xssf.usermodel.ext
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 XSS
* 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();
Modified: poi/trunk/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFFirstHeader.java
URL: http://svn.apache.org/viewvc/poi/trunk/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFFirstHeader.java?rev=1815706&r1=1815705&r2=1815706&view=diff
==============================================================================
--- poi/trunk/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFFirstHeader.java (original)
+++ poi/trunk/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFFirstHeader.java Sun Nov 19 01:35:07 2017
@@ -22,11 +22,19 @@ import org.apache.poi.xssf.usermodel.ext
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 XSS
* 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();
Modified: poi/trunk/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFHeaderFooterProperties.java
URL: http://svn.apache.org/viewvc/poi/trunk/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFHeaderFooterProperties.java?rev=1815706&r1=1815705&r2=1815706&view=diff
==============================================================================
--- poi/trunk/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFHeaderFooterProperties.java (original)
+++ poi/trunk/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFHeaderFooterProperties.java Sun Nov 19 01:35:07 2017
@@ -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
*/
Modified: poi/trunk/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFOddFooter.java
URL: http://svn.apache.org/viewvc/poi/trunk/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFOddFooter.java?rev=1815706&r1=1815705&r2=1815706&view=diff
==============================================================================
--- poi/trunk/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFOddFooter.java (original)
+++ poi/trunk/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFOddFooter.java Sun Nov 19 01:35:07 2017
@@ -42,6 +42,7 @@ public class XSSFOddFooter extends XSSFH
* Get the content text representing the footer
* @return text
*/
+ @Override
public String getText() {
return getHeaderFooter().getOddFooter();
}
@@ -51,6 +52,7 @@ public class XSSFOddFooter extends XSSFH
* @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();
Modified: poi/trunk/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFOddHeader.java
URL: http://svn.apache.org/viewvc/poi/trunk/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFOddHeader.java?rev=1815706&r1=1815705&r2=1815706&view=diff
==============================================================================
--- poi/trunk/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFOddHeader.java (original)
+++ poi/trunk/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFOddHeader.java Sun Nov 19 01:35:07 2017
@@ -42,6 +42,7 @@ public class XSSFOddHeader extends XSSFH
* Get the content text representing this header
* @return text
*/
+ @Override
public String getText() {
return getHeaderFooter().getOddHeader();
}
@@ -51,6 +52,7 @@ public class XSSFOddHeader extends XSSFH
* @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();
Modified: poi/trunk/src/ooxml/java/org/apache/poi/xssf/usermodel/extensions/XSSFHeaderFooter.java
URL: http://svn.apache.org/viewvc/poi/trunk/src/ooxml/java/org/apache/poi/xssf/usermodel/extensions/XSSFHeaderFooter.java?rev=1815706&r1=1815705&r2=1815706&view=diff
==============================================================================
--- poi/trunk/src/ooxml/java/org/apache/poi/xssf/usermodel/extensions/XSSFHeaderFooter.java (original)
+++ poi/trunk/src/ooxml/java/org/apache/poi/xssf/usermodel/extensions/XSSFHeaderFooter.java Sun Nov 19 01:35:07 2017
@@ -146,6 +146,11 @@ public abstract class XSSFHeaderFooter i
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 i
/**
* 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 i
/**
* 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 i
/**
* 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 i
/**
* 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 i
/**
* 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 i
/**
* set a right string value for this element
*/
+ @Override
public void setRight(String newRight) {
setText(helper.setRightSection(getText(), newRight));
}
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@poi.apache.org
For additional commands, e-mail: commits-help@poi.apache.org