From: Dominik Stadler Date: Sat, 28 Mar 2020 09:49:24 +0000 (+0000) Subject: Bug 61863: Update JavaDoc to describe relation to workbook-level flag X-Git-Tag: before_ooxml_3rd_edition~352 X-Git-Url: https://source.dussan.org/?a=commitdiff_plain;h=e88fac30b85041be87d42c659fd34162e4552219;p=poi.git Bug 61863: Update JavaDoc to describe relation to workbook-level flag git-svn-id: https://svn.apache.org/repos/asf/poi/trunk@1875804 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/src/java/org/apache/poi/ss/usermodel/Sheet.java b/src/java/org/apache/poi/ss/usermodel/Sheet.java index 54b4f4303e..bc93818a5c 100644 --- a/src/java/org/apache/poi/ss/usermodel/Sheet.java +++ b/src/java/org/apache/poi/ss/usermodel/Sheet.java @@ -155,22 +155,22 @@ public interface Sheet extends Iterable { * Character width is defined as the maximum digit width * of the numbers 0, 1, 2, ... 9 as rendered * using the default font (first font in the workbook).

- * + * * Unless you are using a very special font, the default character is '0' (zero), * this is true for Arial (default font font in HSSF) and Calibri (default font in XSSF)

* * Please note, that the width set by this method includes 4 pixels of margin padding (two on each side), * plus 1 pixel padding for the gridlines (Section 3.3.1.12 of the OOXML spec). * This results is a slightly less value of visible characters than passed to this method (approx. 1/2 of a character).

- * + * * To compute the actual number of visible characters, * Excel uses the following formula (Section 3.3.1.12 of the OOXML spec):

- * + * * * width = Truncate([{Number of Visible Characters} * * {Maximum Digit Width} + {5 pixel padding}]/{Maximum Digit Width}*256)/256 * - * + * * Using the Calibri font as an example, the maximum digit width of 11 point font size is 7 pixels (at 96 dpi). * If you set a column width to be eight characters wide, e.g. setColumnWidth(columnIndex, 8*256), * then the actual value of visible characters (the value shown in Excel) is derived from the following equation: @@ -202,7 +202,7 @@ public interface Sheet extends Iterable { /** * get the width in pixel - * + * *

* Please note, that this method works correctly only for workbooks * with the default font size (Arial 10pt for .xls and Calibri 11pt for .xlsx). @@ -213,8 +213,8 @@ public interface Sheet extends Iterable { * @return width in pixels */ float getColumnWidthInPixels(int columnIndex); - - + + /** * Set the default column width for the sheet (if the columns do not define their own width) * in characters @@ -238,7 +238,7 @@ public interface Sheet extends Iterable { * @return default row height measured in twips (1/20 of a point) */ short getDefaultRowHeight(); - + /** * Get the default row height for the sheet (if the rows do not define their own height) in * points. @@ -338,7 +338,7 @@ public interface Sheet extends Iterable { * @param index of the region to unmerge */ void removeMergedRegion(int index); - + /** * Removes a number of merged regions of cells (hence letting them free) * @@ -397,10 +397,15 @@ public interface Sheet extends Iterable { /** * Whether Excel will be asked to recalculate all formulas in this sheet when the - * workbook is opened. + * workbook is opened. + * + * Note: This just returns if the sheet has the recalculate flag set and + * will still return false even if recalculation is enabled on workbook-level. + * + * @return true if the Sheet has the recalculate-flag set. */ boolean getForceFormulaRecalculation(); - + /** * Flag indicating whether the sheet displays Automatic Page Breaks. * @@ -538,7 +543,7 @@ public interface Sheet extends Iterable { * @see #setDisplayGridlines(boolean) to display gridlines on screen */ void setPrintGridlines(boolean show); - + /** * Gets the flag indicating whether this sheet prints the * row and column headings when printing. @@ -564,16 +569,16 @@ public interface Sheet extends Iterable { /** * Gets the user model for the default document header.

- * + * * Note that XSSF offers more kinds of document headers than HSSF does - * + * * @return the document header. Never null */ Header getHeader(); /** * Gets the user model for the default document footer.

- * + * * Note that XSSF offers more kinds of document footers than HSSF does. * * @return the document footer. Never null @@ -582,7 +587,7 @@ public interface Sheet extends Iterable { /** * Sets a flag indicating whether this sheet is selected.

- * + * * Note: multiple sheets can be selected, but only one sheet can be active at one time. * * @param value true if this sheet is selected @@ -612,20 +617,20 @@ public interface Sheet extends Iterable { * @return true => protection enabled; false => protection disabled */ boolean getProtect(); - + /** * Sets the protection enabled as well as the password * @param password to set for protection. Pass null to remove protection */ void protectSheet(String password); - + /** * Answer whether scenario protection is enabled or disabled * * @return true => protection enabled; false => protection disabled */ boolean getScenarioProtect(); - + /** * Window zoom magnification for current view representing percent values. * Valid values range from 10 to 400. Horizontal & Vertical scale together. @@ -949,7 +954,7 @@ public interface Sheet extends Iterable { * @param useMergedCells whether to use the contents of merged cells when calculating the width of the column */ void autoSizeColumn(int column, boolean useMergedCells); - + /** * Returns cell comment for the specified location * @@ -966,17 +971,17 @@ public interface Sheet extends Iterable { /** * Return the sheet's existing drawing, or null if there isn't yet one. - * + * * Use {@link #createDrawingPatriarch()} to get or create * * @return a SpreadsheetML drawing */ Drawing getDrawingPatriarch(); - + /** - * Creates the top-level drawing patriarch. + * Creates the top-level drawing patriarch. *

This may then be used to add graphics or charts.

- *

Note that this will normally have the effect of removing + *

Note that this will normally have the effect of removing * any existing drawings on this sheet.

* * @return The new drawing patriarch. @@ -1008,7 +1013,7 @@ public interface Sheet extends Iterable { /** * Sets array formula to specified region for result. *

- * Note if there are shared formulas this will invalidate any + * Note if there are shared formulas this will invalidate any * {@link FormulaEvaluator} instances based on this workbook *

* @param formula text representation of the formula @@ -1024,7 +1029,7 @@ public interface Sheet extends Iterable { * @return the {@link CellRange} of cells affected by this change */ CellRange removeArrayFormula(Cell cell); - + DataValidationHelper getDataValidationHelper(); /** @@ -1041,7 +1046,7 @@ public interface Sheet extends Iterable { /** * Enable filtering for a range of cells - * + * * @param range the range of cells to filter */ AutoFilter setAutoFilter(CellRangeAddress range); @@ -1055,102 +1060,102 @@ public interface Sheet extends Iterable { /** - * Gets the repeating rows used when printing the sheet, as found in + * Gets the repeating rows used when printing the sheet, as found in * File->PageSetup->Sheet.

- * + * * Repeating rows cover a range of contiguous rows, e.g.: * 

      * Sheet1!$1:$1
      * Sheet2!$5:$8
      *
- * The {@link CellRangeAddress} returned contains a column part which spans - * all columns, and a row part which specifies the contiguous range of + * The {@link CellRangeAddress} returned contains a column part which spans + * all columns, and a row part which specifies the contiguous range of * repeating rows.

- * + * * If the Sheet does not have any repeating rows defined, null is returned. - * - * @return an {@link CellRangeAddress} containing the repeating rows for the + * + * @return an {@link CellRangeAddress} containing the repeating rows for the * Sheet, or null. */ CellRangeAddress getRepeatingRows(); /** - * Gets the repeating columns used when printing the sheet, as found in + * Gets the repeating columns used when printing the sheet, as found in * File->PageSetup->Sheet.

- * + * * Repeating columns cover a range of contiguous columns, e.g.: * 

      * Sheet1!$A:$A
      * Sheet2!$C:$F
      *
- * The {@link CellRangeAddress} returned contains a row part which spans all - * rows, and a column part which specifies the contiguous range of + * The {@link CellRangeAddress} returned contains a row part which spans all + * rows, and a column part which specifies the contiguous range of * repeating columns.

- * - * If the Sheet does not have any repeating columns defined, null is + * + * If the Sheet does not have any repeating columns defined, null is * returned. - * - * @return an {@link CellRangeAddress} containing the repeating columns for + * + * @return an {@link CellRangeAddress} containing the repeating columns for * the Sheet, or null. */ CellRangeAddress getRepeatingColumns(); /** - * Sets the repeating rows used when printing the sheet, as found in + * Sets the repeating rows used when printing the sheet, as found in * File->PageSetup->Sheet.

- * + * * Repeating rows cover a range of contiguous rows, e.g.: * 

      * Sheet1!$1:$1
      * Sheet2!$5:$8
- * The parameter {@link CellRangeAddress} should specify a column part - * which spans all columns, and a row part which specifies the contiguous + * The parameter {@link CellRangeAddress} should specify a column part + * which spans all columns, and a row part which specifies the contiguous * range of repeating rows, e.g.: * 
      * sheet.setRepeatingRows(CellRangeAddress.valueOf("2:3"));
- * A null parameter value indicates that repeating rows should be removed + * A null parameter value indicates that repeating rows should be removed * from the Sheet: * 
      * sheet.setRepeatingRows(null);
- * - * @param rowRangeRef a {@link CellRangeAddress} containing the repeating + * + * @param rowRangeRef a {@link CellRangeAddress} containing the repeating * rows for the Sheet, or null. */ void setRepeatingRows(CellRangeAddress rowRangeRef); /** - * Sets the repeating columns used when printing the sheet, as found in + * Sets the repeating columns used when printing the sheet, as found in * File->PageSetup->Sheet.

- * + * * Repeating columns cover a range of contiguous columns, e.g.: * 

      * Sheet1!$A:$A
      * Sheet2!$C:$F
- * The parameter {@link CellRangeAddress} should specify a row part - * which spans all rows, and a column part which specifies the contiguous + * The parameter {@link CellRangeAddress} should specify a row part + * which spans all rows, and a column part which specifies the contiguous * range of repeating columns, e.g.: * 
      * sheet.setRepeatingColumns(CellRangeAddress.valueOf("B:C"));
- * A null parameter value indicates that repeating columns should be removed + * A null parameter value indicates that repeating columns should be removed * from the Sheet: * 
      * sheet.setRepeatingColumns(null);
- * - * @param columnRangeRef a {@link CellRangeAddress} containing the repeating + * + * @param columnRangeRef a {@link CellRangeAddress} containing the repeating * columns for the Sheet, or null. */ void setRepeatingColumns(CellRangeAddress columnRangeRef); - + /** * Returns the column outline level. Increased as you * put it into more groups (outlines), reduced as * you take it out of them. */ int getColumnOutlineLevel(int columnIndex); - + /** * Get a Hyperlink in this sheet anchored at row, column * @@ -1159,7 +1164,7 @@ public interface Sheet extends Iterable { * @return hyperlink if there is a hyperlink anchored at row, column; otherwise returns null */ Hyperlink getHyperlink(int row, int column); - + /** * Get a Hyperlink in this sheet located in a cell specified by {code addr} * @@ -1168,7 +1173,7 @@ public interface Sheet extends Iterable { * @since POI 3.15 beta 3 */ Hyperlink getHyperlink(CellAddress addr); - + /** * Get a list of Hyperlinks in this sheet * diff --git a/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFSheet.java b/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFSheet.java index 6ea20de383..d972d8f2c0 100644 --- a/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFSheet.java +++ b/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFSheet.java @@ -2098,8 +2098,13 @@ public class XSSFSheet extends POIXMLDocumentPart implements Sheet { } /** - * Whether Excel will be asked to recalculate all formulas when the - * workbook is opened. + * Whether Excel will be asked to recalculate all formulas of this sheet + * when the workbook is opened. + * + * Note: This just returns if the sheet has the recalculate flag set and + * will still return false even if recalculation is enabled on workbook-level. + * + * @return true if the Sheet has the recalculate-flag set. */ @Override public boolean getForceFormulaRecalculation() { diff --git a/src/ooxml/testcases/org/apache/poi/xssf/usermodel/TestXSSFSheet.java b/src/ooxml/testcases/org/apache/poi/xssf/usermodel/TestXSSFSheet.java index faad31f46f..618575c5d1 100644 --- a/src/ooxml/testcases/org/apache/poi/xssf/usermodel/TestXSSFSheet.java +++ b/src/ooxml/testcases/org/apache/poi/xssf/usermodel/TestXSSFSheet.java @@ -27,6 +27,7 @@ import static org.junit.Assert.assertNull; import static org.junit.Assert.assertSame; import static org.junit.Assert.assertTrue; +import java.io.FileInputStream; import java.io.IOException; import java.util.Arrays; import java.util.Calendar; @@ -36,6 +37,7 @@ import java.util.List; import java.util.Map; import java.util.Set; +import org.apache.poi.EncryptedDocumentException; import org.apache.poi.hssf.HSSFTestDataSamples; import org.apache.poi.ooxml.POIXMLException; import org.apache.poi.poifs.crypt.CryptoFunctions; @@ -55,6 +57,7 @@ import org.apache.poi.ss.usermodel.IndexedColors; 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.ss.usermodel.WorkbookFactory; import org.apache.poi.ss.util.*; import org.apache.poi.util.LocaleUtil; import org.apache.poi.xssf.XSSFITestDataProvider; @@ -2002,4 +2005,40 @@ public final class TestXSSFSheet extends BaseTestXSheet { assertNotNull(hfProp); } } + + @Test + public void testSheetForceFormulaRecalculationDefaultValues() throws IOException { + try (Workbook wb = _testDataProvider.openSampleWorkbook("sample.xlsx")){ + for (Sheet s : wb) { + assertEquals(wb.getForceFormulaRecalculation(),s.getForceFormulaRecalculation()); + } + } + } + + @Test + public void testWorkbookSetForceFormulaRecalculation() throws IOException { + try (Workbook wb = _testDataProvider.openSampleWorkbook("sample.xlsx")){ + wb.setForceFormulaRecalculation(true); + assertTrue(wb.getForceFormulaRecalculation()); + } + } + + @Test + public void testNotCascadeWorkbookSetForceFormulaRecalculation() throws IOException { + try (Workbook wb = _testDataProvider.openSampleWorkbook("sample.xlsx")) { + // set all sheets to force recalculation + for (Sheet s : wb) { + s.setForceFormulaRecalculation(true); + assertTrue(s.getForceFormulaRecalculation()); + } + + // disable on workbook-level + wb.setForceFormulaRecalculation(false); + + // on sheet-level, the flag is still set + for (Sheet s : wb) { + assertTrue("Sheet-level flag is still set to true", s.getForceFormulaRecalculation()); + } + } + } }