From 6a8bb2c748b0cef876af602efb968e9f44a0d605 Mon Sep 17 00:00:00 2001 From: Yegor Kozlov Date: Fri, 14 Nov 2008 20:29:42 +0000 Subject: [PATCH] more updates in javadocs and site documentation, also misc improvements in common hssf-xssf interfaces git-svn-id: https://svn.apache.org/repos/asf/poi/trunk@714128 13f79535-47bb-0310-9956-ffa450edef68 --- .../content/xdocs/howtobuild.xml | 23 ++ .../content/xdocs/spreadsheet/examples.xml | 10 +- .../content/xdocs/spreadsheet/formula.xml | 50 ++- .../content/xdocs/spreadsheet/quick-guide.xml | 4 +- .../usermodel/examples/NewLinesInCells.java | 2 +- .../apache/poi/hssf/usermodel/HSSFSheet.java | 6 +- .../org/apache/poi/ss/usermodel/Cell.java | 192 +++++++---- .../org/apache/poi/ss/usermodel/Name.java | 19 +- .../org/apache/poi/ss/usermodel/Row.java | 107 +++--- .../org/apache/poi/ss/usermodel/Sheet.java | 309 ++++++++++++------ .../org/apache/poi/ss/usermodel/Workbook.java | 259 +++++++++------ .../apache/poi/xssf/usermodel/XSSFCell.java | 18 +- .../apache/poi/xssf/usermodel/XSSFSheet.java | 12 +- 13 files changed, 623 insertions(+), 388 deletions(-) diff --git a/src/documentation/content/xdocs/howtobuild.xml b/src/documentation/content/xdocs/howtobuild.xml index af45effa8..e13258bd4 100644 --- a/src/documentation/content/xdocs/howtobuild.xml +++ b/src/documentation/content/xdocs/howtobuild.xml @@ -28,6 +28,13 @@ +
+ JDK +

+ POI 3.5 and later requires the JDK version 1.5 or later. + Versions prior to 3.5 require JDK 1.4+ +

+
Installing Ant

@@ -114,6 +121,22 @@ /junit/jars/junit-3.8.1.jar lib + + /dom4j/jars/dom4j-1.6.1.jar + ooxml-lib + + + /org.apache.xmlbeans/jars/xmlbeans-2.3.0.jar + ooxml-lib + + + /xmlbeans/jars/jsr173_1.0_api.jar + ooxml-lib + + + /org.apache.poi/jars/ooxml-schemas-1.0.jar + ooxml-lib +

The main targets of interest to our users are: diff --git a/src/documentation/content/xdocs/spreadsheet/examples.xml b/src/documentation/content/xdocs/spreadsheet/examples.xml index f683738a3..966a1626b 100755 --- a/src/documentation/content/xdocs/spreadsheet/examples.xml +++ b/src/documentation/content/xdocs/spreadsheet/examples.xml @@ -38,7 +38,7 @@

All sample source is available in SVN

-
BusinessPlan +
Business Plan

The BusinessPlan application creates a sample business plan with three phases, weekly iterations and time highlighting. Demonstrates advanced cell formatting (number and date formats, alignmnets, fills, borders) and various settings for organizing data in a sheet (freezed panes, groupped rows). @@ -48,14 +48,14 @@

Calendar -

The Calendar +

The Calendar demo creates a multi sheet calendar. Each month is on a separate sheet.

calendar demo

-
LoanCalculator +
Loan Calculator

The LoanCalculator demo creates a simple loan calculator. Demonstrates advance usage of cell formulas and named ranges.

@@ -63,8 +63,8 @@ loan calculator demo

-
TimesheetDemo -

The TimesheetDemo +

Timesheet +

The Timesheet demo creates a weekly timesheet with automatic calculation of total hours. Demonstrates advance usage of cell formulas.

diff --git a/src/documentation/content/xdocs/spreadsheet/formula.xml b/src/documentation/content/xdocs/spreadsheet/formula.xml index 3dda9f181..3f319fce4 100644 --- a/src/documentation/content/xdocs/spreadsheet/formula.xml +++ b/src/documentation/content/xdocs/spreadsheet/formula.xml @@ -30,7 +30,7 @@

Introduction

This document describes the current state of formula support in POI. - The information in this document currently applies to the 2.0 version of POI. + The information in this document currently applies to the 3.5 version of POI. Since this area is a work in progress, this document will be updated with new features as and when they are added.

@@ -43,43 +43,26 @@ getCellFormula() is used to retrieve the string representation of a formula.

- We aim to support the complete excel grammer for formulas. Thus, the string that you pass in + We aim to support the complete excel grammar for formulas. Thus, the string that you pass in to the setCellFormula call should be what you expect to type into excel. Also, note that you should NOT add a "=" to the front of the string.

Supported Features
    -
  • Cell References
    • -
  • String, integer and floating point literals
    • -
  • Area references
    • -
  • Relative or absolute references
    • -
  • Arithmetic and logical operators
    • -
  • Sheet or Macro Functions (inlcuding logical functions)
    • -
  • Sheet References
    • -
  • Formual return values (number or string)
    • +
  • References: single cell & area, 2D & 3D, relative & absolute
    • +
  • Literals: Number, text, boolean, error and array
    • +
  • Operators: arithmetic and logical, some region operators
    • +
  • Built-in functions: over 350 recognised, 280 evaluatable
    • +
  • Add-in functions: 3 from Analysis Toolpack
-
Partially supported -
    -
  • Formula tokens in Excel are stored in one of three possible classes : - Reference, Value and Array. Based on the location of a token, its class can change - in complicated and undocumented ways. While we have support for most cases, we - are not sure if we have covered all bases (since there is no documentation for this area.) - We would therefore like you to report any - occurence of #VALUE! in a cell upon opening a POI generated workbook in excel. (Check that - typing the formula into Excel directly gives a valid result.) -
    • - -
-
Not yet supported
    -
  • Array formulas
    • -
  • Unary Operators
    • -
  • 3D References
    • -
  • Error Values (cells containing #REF's or #VALUE's)
    • -
  • Everything else :)
    • +
  • Manipulating array/table formulas (In Excel, formulas that look like "{=...}" as opposed to "=...")
    • +
  • Region operators: union, intersection
    • +
  • Parsing of previously uncalled add-in functions
    • +
  • Preservation of whitespace in formulas (when POI manipulates them)
@@ -96,9 +79,18 @@

The task of parsing a formula string into an array of RPN ordered tokens is done by the - org.apache.poi.hssf.record.formula.FormulaParser class. This class implements a hand + org.apache.poi.ss.formula.FormulaParser class. This class implements a hand written recursive descent parser.

+

+ Formula tokens in Excel are stored in one of three possible operand classes : + Reference, Value and Array. Based on the location of a token, its class can change + in complicated and undocumented ways. While we have support for most cases, we + are not sure if we have covered all bases (since there is no documentation for this area.) + We would therefore like you to report any + occurrence of #VALUE! in a cell upon opening a POI generated workbook in excel. (Check that + typing the formula into Excel directly gives a valid result.) +

Check out the javadocs for details.

diff --git a/src/documentation/content/xdocs/spreadsheet/quick-guide.xml b/src/documentation/content/xdocs/spreadsheet/quick-guide.xml index 9b347c759..2688bc9f2 100644 --- a/src/documentation/content/xdocs/spreadsheet/quick-guide.xml +++ b/src/documentation/content/xdocs/spreadsheet/quick-guide.xml @@ -1317,10 +1317,10 @@ Examples: constructing AreaReference

- if(hssfName.isDeleted()){ + if(name.isDeleted()){ //named range points to a deleted cell. } else { - AreaReference ref = new AreaReference(hssfName.getReference()); + AreaReference ref = new AreaReference(name.getReference()); }
diff --git a/src/examples/src/org/apache/poi/xssf/usermodel/examples/NewLinesInCells.java b/src/examples/src/org/apache/poi/xssf/usermodel/examples/NewLinesInCells.java index 5626e7a7c..eb179357d 100755 --- a/src/examples/src/org/apache/poi/xssf/usermodel/examples/NewLinesInCells.java +++ b/src/examples/src/org/apache/poi/xssf/usermodel/examples/NewLinesInCells.java @@ -47,7 +47,7 @@ public class NewLinesInCells { row.setHeightInPoints((2*sheet.getDefaultRowHeightInPoints())); //adjust column width to fit the content - sheet.autoSizeColumn((short)2); + sheet.autoSizeColumn(2); FileOutputStream fileOut = new FileOutputStream("ooxml-newlines.xlsx"); wb.write(fileOut); diff --git a/src/java/org/apache/poi/hssf/usermodel/HSSFSheet.java b/src/java/org/apache/poi/hssf/usermodel/HSSFSheet.java index e6e9ac9b4..8651ff48c 100644 --- a/src/java/org/apache/poi/hssf/usermodel/HSSFSheet.java +++ b/src/java/org/apache/poi/hssf/usermodel/HSSFSheet.java @@ -1656,7 +1656,7 @@ public class HSSFSheet implements org.apache.poi.ss.usermodel.Sheet * @param column the column index * @param style the style to set */ - public void setDefaultColumnStyle(short column, CellStyle style) { + public void setDefaultColumnStyle(int column, CellStyle style) { sheet.setDefaultColumnStyle(column, ((HSSFCellStyle)style).getIndex()); } @@ -1669,7 +1669,7 @@ public class HSSFSheet implements org.apache.poi.ss.usermodel.Sheet * * @param column the column index */ - public void autoSizeColumn(short column) { + public void autoSizeColumn(int column) { autoSizeColumn(column, false); } @@ -1686,7 +1686,7 @@ public class HSSFSheet implements org.apache.poi.ss.usermodel.Sheet * @param column the column index * @param useMergedCells whether to use the contents of merged cells when calculating the width of the column */ - public void autoSizeColumn(short column, boolean useMergedCells) { + public void autoSizeColumn(int column, boolean useMergedCells) { AttributedString str; TextLayout layout; /** diff --git a/src/ooxml/interfaces-jdk15/org/apache/poi/ss/usermodel/Cell.java b/src/ooxml/interfaces-jdk15/org/apache/poi/ss/usermodel/Cell.java index a31549378..930d0c9c6 100644 --- a/src/ooxml/interfaces-jdk15/org/apache/poi/ss/usermodel/Cell.java +++ b/src/ooxml/interfaces-jdk15/org/apache/poi/ss/usermodel/Cell.java @@ -20,6 +20,19 @@ package org.apache.poi.ss.usermodel; import java.util.Calendar; import java.util.Date; +/** + * High level representation of a cell in a row of a spreadsheet. + *

+ * Cells can be numeric, formula-based or string-based (text). The cell type + * specifies this. String cells cannot conatin numbers and numeric cells cannot + * contain strings (at least according to our model). Client apps should do the + * conversions themselves. Formula cells have the formula string, as well as + * the formula result, which can be numeric or string. + *

+ *

+ * Cells should have their number (0 based) before being added to a row. + *

+ */ public interface Cell { /** @@ -27,7 +40,6 @@ public interface Cell { * @see #setCellType(int) * @see #getCellType() */ - public final static int CELL_TYPE_NUMERIC = 0; /** @@ -35,7 +47,6 @@ public interface Cell { * @see #setCellType(int) * @see #getCellType() */ - public final static int CELL_TYPE_STRING = 1; /** @@ -43,7 +54,6 @@ public interface Cell { * @see #setCellType(int) * @see #getCellType() */ - public final static int CELL_TYPE_FORMULA = 2; /** @@ -51,7 +61,6 @@ public interface Cell { * @see #setCellType(int) * @see #getCellType() */ - public final static int CELL_TYPE_BLANK = 3; /** @@ -59,7 +68,6 @@ public interface Cell { * @see #setCellType(int) * @see #getCellType() */ - public final static int CELL_TYPE_BOOLEAN = 4; /** @@ -67,32 +75,33 @@ public interface Cell { * @see #setCellType(int) * @see #getCellType() */ - public final static int CELL_TYPE_ERROR = 5; /** - * set the cell's number within the row (0 based) - * @param num short the cell number - */ - - void setCellNum(short num); - - /** - * @deprecated (Oct 2008) use {@link #getColumnIndex()} - */ - short getCellNum(); - - /** - * @return the cell's column index (zero based) + * Returns column index of this cell + * + * @return zero-based column index of a column in a sheet. */ int getColumnIndex(); + /** + * Returns row index of a row in the sheet that contains this cell + * + * @return zero-based row index of a row in the sheet that contains this cell + */ int getRowIndex(); + /** + * Returns the sheet this cell belongs to + * + * @return the sheet this cell belongs to + */ Sheet getSheet(); /** - * set the cells type (numeric, formula or string) + * Set the cells type (numeric, formula or string) + * + * @throws IllegalArgumentException if the specified cell type is invalid * @see #CELL_TYPE_NUMERIC * @see #CELL_TYPE_STRING * @see #CELL_TYPE_FORMULA @@ -100,23 +109,23 @@ public interface Cell { * @see #CELL_TYPE_BOOLEAN * @see #CELL_TYPE_ERROR */ - void setCellType(int cellType); /** - * @return the cell's type (e.g. numeric, formula or string) - * @see #CELL_TYPE_STRING - * @see #CELL_TYPE_NUMERIC - * @see #CELL_TYPE_FORMULA - * @see #CELL_TYPE_BOOLEAN - * @see #CELL_TYPE_BLANK - * @see #CELL_TYPE_ERROR + * Return the cell type. + * + * @return the cell type + * @see Cell#CELL_TYPE_BLANK + * @see Cell#CELL_TYPE_NUMERIC + * @see Cell#CELL_TYPE_STRING + * @see Cell#CELL_TYPE_FORMULA + * @see Cell#CELL_TYPE_BOOLEAN + * @see Cell#CELL_TYPE_ERROR */ - int getCellType(); /** - * set a numeric value for the cell + * Set a numeric value for the cell * * @param value the numeric value to set this cell to. For formulas we'll set the * precalculated value, for numerics we'll set its value. For other types we @@ -125,18 +134,25 @@ public interface Cell { void setCellValue(double value); /** - * set a date value for the cell. Excel treats dates as numeric so you will need to format the cell as - * a date. + * Set a boolean value for the cell * - * @param value the date value to set this cell to. For formulas we'll set the - * precalculated value, for numerics we'll set its value. For other types we - * will change the cell to a numeric cell and set its value. + * @param value the boolean value to set this cell to. For formulas we'll set the + * precalculated value, for booleans we'll set its value. For other types we + * will change the cell to a boolean cell and set its value. */ void setCellValue(Date value); /** - * set a date value for the cell. Excel treats dates as numeric so you will need to format the cell as + * Set a date value for the cell. Excel treats dates as numeric so you will need to format the cell as * a date. + *

+ * This will set the cell value based on the Calendar's timezone. As Excel + * does not support timezones this means that both 20:00+03:00 and + * 20:00-03:00 will be reported as the same value (20:00) even that there + * are 6 hours difference between the two times. This difference can be + * preserved by using setCellValue(value.getTime()) which will + * automatically shift the times to the default timezone. + *

* * @param value the date value to set this cell to. For formulas we'll set the * precalculated value, for numerics we'll set its value. For othertypes we @@ -165,97 +181,131 @@ public interface Cell { void setCellValue(String value); /** - * Set a formula value for the cell. + * Sets formula for this cell. + *

+ * Note, this method only sets the formula string and does not calculate the formula value. + * To set the precalculated value use {@link #setCellValue(double)} or {@link #setCellValue(String)} + *

+ * + * @param formula the formula to set, e.g. SUM(C4:E4). + * If the argument is null then the current formula is removed. */ void setCellFormula(String formula); /** - * Get the formula value of the cell. + * Return a formula for the cell, for example, SUM(C4:E4) + * + * @return a formula for the cell + * @throws IllegalStateException if the cell type returned by {@link #getCellType()} is not CELL_TYPE_FORMULA */ String getCellFormula(); /** - * get the value of the cell as a number. For strings we throw an exception. - * For blank cells we return a 0. + * Get the value of the cell as a number. + *

+ * For strings we throw an exception. For blank cells we return a 0. + * For formulas or error cells we return the precalculated value; + *

+ * @return the value of the cell as a number + * @throws IllegalStateException if the cell type returned by {@link #getCellType()} is CELL_TYPE_STRING + * @exception NumberFormatException if the cell value isn't a parsable double. + * @see DataFormatter for turning this number into a string similar to that which Excel would render this number as. */ - double getNumericCellValue(); /** - * get the value of the cell as a date. For strings we throw an exception. - * For blank cells we return a null. + * Get the value of the cell as a date. + *

+ * For strings we throw an exception. For blank cells we return a null. + *

+ * @return the value of the cell as a date + * @throws IllegalStateException if the cell type returned by {@link #getCellType()} is CELL_TYPE_STRING + * @exception NumberFormatException if the cell value isn't a parsable double. + * @see DataFormatter for formatting this date into a string similar to how excel does. */ Date getDateCellValue(); /** - * get the value of the cell as a string - for numeric cells we throw an exception. - * For blank cells we return an empty string. - * For formulaCells that are not string Formulas, we return empty String + * Get the value of the cell as a XSSFRichTextString + *

+ * For numeric cells we throw an exception. For blank cells we return an empty string. + * For formula cells we return the pre-calculated value. + *

+ * @return the value of the cell as a XSSFRichTextString */ - RichTextString getRichStringCellValue(); /** - * Get the value of the cell as a string - for numeric cells we throw an exception + * Get the value of the cell as a string *

- * For blank cells we return an empty string. - * For formulaCells that are not string Formulas, we return empty String + * For numeric cells we throw an exception. For blank cells we return an empty string. + * For formulaCells that are not string Formulas, we return empty String. *

+ * @return the value of the cell as a string */ String getStringCellValue(); /** - * set a boolean value for the cell + * Set a boolean value for the cell * * @param value the boolean value to set this cell to. For formulas we'll set the * precalculated value, for booleans we'll set its value. For other types we * will change the cell to a boolean cell and set its value. */ - - void setCellValue(boolean value); + void setCellValue(boolean value); /** - * set a error value for the cell + * Set a error value for the cell * * @param value the error value to set this cell to. For formulas we'll set the - * precalculated value ??? IS THIS RIGHT??? , for errors we'll set + * precalculated value , for errors we'll set * its value. For other types we will change the cell to an error * cell and set its value. + * @see FormulaError */ - void setCellErrorValue(byte value); /** - * get the value of the cell as a boolean. For strings, numbers, and errors, we throw an exception. - * For blank cells we return a false. + * Get the value of the cell as a boolean. + *

+ * For strings, numbers, and errors, we throw an exception. For blank cells we return a false. + *

+ * @return the value of the cell as a boolean + * @throws IllegalStateException if the cell type returned by {@link #getCellType()} + * is not CELL_TYPE_BOOLEAN, CELL_TYPE_BLANK or CELL_TYPE_FORMULA */ - boolean getBooleanCellValue(); /** - * get the value of the cell as an error code. For strings, numbers, and booleans, we throw an exception. + * Get the value of the cell as an error code. + *

+ * For strings, numbers, and booleans, we throw an exception. * For blank cells we return a 0. + *

+ * + * @return the value of the cell as an error code + * @throws IllegalStateException if the cell type returned by {@link #getCellType()} isn't CELL_TYPE_ERROR + * @see FormulaError for error codes */ - byte getErrorCellValue(); /** - * set the style for the cell. The style should be an CellStyle created/retreived from + * Set the style for the cell. The style should be an CellStyle created/retreived from * the Workbook. * - * @param style reference contained in the workbook - * @see Workbook#createCellStyle() - * @see Workbook#getCellStyleAt(short) + * @param style reference contained in the workbook. + * If the value is null then the style information is removed causing the cell to used the default workbook style. + * @see org.apache.poi.ss.usermodel.Workbook#createCellStyle() */ - void setCellStyle(CellStyle style); /** - * get the style for the cell. This is a reference to a cell style contained in the workbook - * object. + * Return the cell's style. + * + * @return the cell's style. Always not-null. Default cell style has zero index and can be obtained as + * workbook.getCellStyleAt(0) * @see Workbook#getCellStyleAt(short) */ - CellStyle getCellStyle(); /** @@ -273,14 +323,14 @@ public interface Cell { /** * Returns comment associated with this cell * - * @return comment associated with this cell + * @return comment associated with this cell or null if not found */ Comment getCellComment(); /** * Returns hyperlink associated with this cell * - * @return hyperlink associated with this cell or null if not found + * @return hyperlink associated with this cell or null if not found */ Hyperlink getHyperlink(); diff --git a/src/ooxml/interfaces-jdk15/org/apache/poi/ss/usermodel/Name.java b/src/ooxml/interfaces-jdk15/org/apache/poi/ss/usermodel/Name.java index 7ff4cbcf8..a0061b951 100644 --- a/src/ooxml/interfaces-jdk15/org/apache/poi/ss/usermodel/Name.java +++ b/src/ooxml/interfaces-jdk15/org/apache/poi/ss/usermodel/Name.java @@ -22,36 +22,43 @@ public interface Name { /** Get the sheets name which this named range is referenced to * @return sheet name, which this named range refered to */ - String getSheetName(); /** * gets the name of the named range * @return named range name */ - String getNameName(); /** * sets the name of the named range * @param nameName named range name to set */ - void setNameName(String nameName); /** * gets the reference of the named range * @return reference of the named range */ - String getReference(); /** * sets the reference of this named range * @param ref the reference to set */ + void setReference(String ref); - void setReference(String ref); - + /** + * Checks if this name is a function name + * + * @return true if this name is a function name + */ boolean isFunctionName(); + + /** + * Checks if this name points to a cell that no longer exists + * + * @return true if the name refers to a deleted cell, false otherwise + */ + boolean isDeleted(); } diff --git a/src/ooxml/interfaces-jdk15/org/apache/poi/ss/usermodel/Row.java b/src/ooxml/interfaces-jdk15/org/apache/poi/ss/usermodel/Row.java index f63ee010b..2cb7b8b6d 100644 --- a/src/ooxml/interfaces-jdk15/org/apache/poi/ss/usermodel/Row.java +++ b/src/ooxml/interfaces-jdk15/org/apache/poi/ss/usermodel/Row.java @@ -20,132 +20,159 @@ package org.apache.poi.ss.usermodel; import java.lang.Iterable; import java.util.Iterator; +/** + * High level representation of a row of a spreadsheet. + */ public interface Row extends Iterable { + /** * Use this to create new cells within the row and return it. *

- * The cell that is returned is a CELL_TYPE_BLANK. The type can be changed + * The cell that is returned is a {@link Cell#CELL_TYPE_BLANK}. The type can be changed * either through calling setCellValue or setCellType. * * @param column - the column number this cell represents - * * @return Cell a high level representation of the created cell. + * @throws IllegalArgumentException if columnIndex < 0 */ Cell createCell(int column); /** * Use this to create new cells within the row and return it. *

- * The cell that is returned is a CELL_TYPE_BLANK. The type can be changed + * The cell that is returned is a {@link Cell#CELL_TYPE_BLANK}. The type can be changed * either through calling setCellValue or setCellType. * * @param column - the column number this cell represents - * * @return Cell a high level representation of the created cell. + * @throws IllegalArgumentException if columnIndex < 0 */ Cell createCell(int column, int type); /** - * remove the Cell from this row. - * @param cell to remove + * Remove the Cell from this row. + * + * @param cell the cell to remove */ void removeCell(Cell cell); /** - * set the row number of this row. + * Set the row number of this row. + * * @param rowNum the row number (0-based) - * @throws IndexOutOfBoundsException if the row number is not within the range 0-65535. + * @throws IllegalArgumentException if rowNum < 0 */ - void setRowNum(int rowNum); /** - * get row number this row represents + * Get row number this row represents + * * @return the row number (0 based) */ - int getRowNum(); /** - * get the cell representing a given column (logical cell) 0-based. If you + * Get the cell representing a given column (logical cell) 0-based. If you * ask for a cell that is not defined....you get a null. * * @param cellnum 0 based column number * @return Cell representing that column or null if undefined. + * @see #getCell(int, org.apache.poi.ss.usermodel.Row.MissingCellPolicy) */ Cell getCell(int cellnum); /** - * Get the cell representing a given column (logical cell) - * 0-based. If you ask for a cell that is not defined, then - * your supplied policy says what to do + * Returns the cell at the given (0 based) index, with the specified {@link org.apache.poi.ss.usermodel.Row.MissingCellPolicy} * - * @param cellnum 0 based column number - * @param policy Policy on blank / missing cells - * @return representing that column or null if undefined + policy allows. + * @return the cell at the given (0 based) index + * @throws IllegalArgumentException if cellnum < 0 or the specified MissingCellPolicy is invalid + * @see Row#RETURN_NULL_AND_BLANK + * @see Row#RETURN_BLANK_AS_NULL + * @see Row#CREATE_NULL_AS_BLANK */ - public Cell getCell(int cellnum, MissingCellPolicy policy); + Cell getCell(int cellnum, MissingCellPolicy policy); /** - * get the number of the first cell contained in this row. - * @return short representing the first logical cell in the row, or -1 if the row does not contain any cells. + * Get the number of the first cell contained in this row. + * + * @return short representing the first logical cell in the row, + * or -1 if the row does not contain any cells. */ short getFirstCellNum(); /** - * gets the number of the last cell contained in this row PLUS ONE. - * @return short representing the last logical cell in the row PLUS ONE, or -1 if the row does not contain any cells. + * Gets the index of the last cell contained in this row PLUS ONE. The result also + * happens to be the 1-based column number of the last cell. This value can be used as a + * standard upper bound when iterating over cells: + * 

+     * short minColIx = row.getFirstCellNum();
+     * short maxColIx = row.getLastCellNum();
+     * for(short colIx=minColIx; colIx<maxColIx; colIx++) {
+     *   Cell cell = row.getCell(colIx);
+     *   if(cell == null) {
+     *     continue;
+     *   }
+     *   //... do something with cell
+     * }
+     *
+ * + * @return short representing the last logical cell in the row PLUS ONE, + * or -1 if the row does not contain any cells. */ - short getLastCellNum(); /** - * gets the number of defined cells (NOT number of cells in the actual row!). + * Gets the number of defined cells (NOT number of cells in the actual row!). * That is to say if only columns 0,4,5 have values then there would be 3. + * * @return int representing the number of defined cells in the row. */ - int getPhysicalNumberOfCells(); /** - * set the row's height or set to ff (-1) for undefined/default-height. Set the height in "twips" or + * Set the row's height or set to ff (-1) for undefined/default-height. Set the height in "twips" or * 1/20th of a point. + * * @param height rowheight or 0xff for undefined (use sheet default) */ - void setHeight(short height); /** - * set whether or not to display this row with 0 height + * Set whether or not to display this row with 0 height + * * @param zHeight height is zero or not. */ void setZeroHeight(boolean zHeight); /** - * get whether or not to display this row with 0 height + * Get whether or not to display this row with 0 height + * * @return - zHeight height is zero or not. */ boolean getZeroHeight(); /** - * set the row's height in points. - * @param height row height in points + * Set the row's height in points. + * + * @param height the height in points. -1 resets to the default height */ - void setHeightInPoints(float height); /** - * get the row's height or ff (-1) for undefined/default-height in twips (1/20th of a point) - * @return rowheight or 0xff for undefined (use sheet default) + * Get the row's height measured in twips (1/20th of a point). If the height is not set, the default worksheet value is returned, + * See {@link Sheet#getDefaultRowHeightInPoints()} + * + * @return row height measured in twips (1/20th of a point) */ - short getHeight(); /** - * get the row's height or ff (-1) for undefined/default-height in points (20*getHeight()) - * @return rowheight or 0xff for undefined (use sheet default) + * Returns row height measured in point size. If the height is not set, the default worksheet value is returned, + * See {@link Sheet#getDefaultRowHeightInPoints()} + * + * @return row height measured in point size + * @see Sheet#getDefaultRowHeightInPoints() */ - float getHeightInPoints(); /** @@ -158,7 +185,7 @@ public interface Row extends Iterable { * Used to specify the different possible policies * if for the case of null and blank cells */ - public static class MissingCellPolicy { + public static final class MissingCellPolicy { private static int NEXT_ID = 1; public final int id; private MissingCellPolicy() { diff --git a/src/ooxml/interfaces-jdk15/org/apache/poi/ss/usermodel/Sheet.java b/src/ooxml/interfaces-jdk15/org/apache/poi/ss/usermodel/Sheet.java index bd500d56a..e280a3502 100644 --- a/src/ooxml/interfaces-jdk15/org/apache/poi/ss/usermodel/Sheet.java +++ b/src/ooxml/interfaces-jdk15/org/apache/poi/ss/usermodel/Sheet.java @@ -22,6 +22,15 @@ import java.util.Iterator; import org.apache.poi.hssf.util.PaneInformation; import org.apache.poi.ss.util.CellRangeAddress; +/** + * High level representation of a Excel worksheet. + * + *

+ * Sheets are the central structures within a workbook, and are where a user does most of his spreadsheet work. + * The most common type of sheet is the worksheet, which is represented as a grid of cells. Worksheet cells can + * contain text, numbers, dates, and formulas. Cells can also be formatted. + *

+ */ public interface Sheet extends Iterable { /* Constants for margins */ @@ -49,8 +58,7 @@ public interface Sheet extends Iterable { * Create a new row within the sheet and return the high level representation * * @param rownum row number - * @return High level Row object representing a row in the sheet - * @see Row + * @return high level Row object representing a row in the sheet * @see #removeRow(Row) */ Row createRow(int rownum); @@ -60,54 +68,57 @@ public interface Sheet extends Iterable { * * @param row representing a row to remove. */ - void removeRow(Row row); /** * Returns the logical row (not physical) 0-based. If you ask for a row that is not * defined you get a null. This is to say row 4 represents the fifth row on a sheet. - * @param rownum row to get + * + * @param rownum row to get (0-based) * @return Row representing the rownumber or null if its not defined on the sheet */ - Row getRow(int rownum); /** - * Returns the number of phsyically defined rows (NOT the number of rows in the sheet) + * Returns the number of physically defined rows (NOT the number of rows in the sheet) + * + * @return the number of physically defined rows in this sheet */ - int getPhysicalNumberOfRows(); /** - * gets the first row on the sheet - * @return the number of the first logical row on the sheet + * Gets the first row on the sheet + * + * @return the number of the first logical row on the sheet (0-based) */ - int getFirstRowNum(); /** - * gets the last row on the sheet - * @return last row contained n this sheet. + * Gets the last row on the sheet + * + * @return last row contained n this sheet (0-based) */ - int getLastRowNum(); /** - * Get the visibility state for a given column. + * Get the visibility state for a given column + * * @param columnIndex - the column to get (0-based) * @param hidden - the visiblity state of the column */ void setColumnHidden(int columnIndex, boolean hidden); /** - * Get the hidden state for a given column. + * Get the hidden state for a given column + * * @param columnIndex - the column to set (0-based) * @return hidden - false if the column is visible */ boolean isColumnHidden(int columnIndex); /** - * set the width (in units of 1/256th of a character width) + * Set the width (in units of 1/256th of a character width) + * * @param columnIndex - the column to set (0-based) * @param width - the width in units of 1/256th of a character width */ @@ -119,72 +130,74 @@ public interface Sheet extends Iterable { * @return width - the width in units of 1/256th of a character width */ int getColumnWidth(int columnIndex); - /** - * set the default column width for the sheet (if the columns do not define their own width) in - * characters - * @param width default column width - */ - public void setDefaultColumnWidth(int width); /** - * get the default column width for the sheet (if the columns do not define their own width) in - * characters - * @return default column width + * Set the default column width for the sheet (if the columns do not define their own width) + * in characters + * + * @param width default column width measured in characters */ + void setDefaultColumnWidth(int width); + /** + * Get the default column width for the sheet (if the columns do not define their own width) + * in characters + * + * @return default column width measured in characters + */ int getDefaultColumnWidth(); /** - * get the default row height for the sheet (if the rows do not define their own height) in + * Get the default row height for the sheet (if the rows do not define their own height) in * twips (1/20 of a point) - * @return default row height + * + * @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 + * Get the default row height for the sheet (if the rows do not define their own height) in * points. + * * @return default row height in points */ - float getDefaultRowHeightInPoints(); /** - * set the default row height for the sheet (if the rows do not define their own height) in + * Set the default row height for the sheet (if the rows do not define their own height) in * twips (1/20 of a point) - * @param height default row height + * + * @param height default row height measured in twips (1/20 of a point) */ - void setDefaultRowHeight(short height); /** - * set the default row height for the sheet (if the rows do not define their own height) in + * Set the default row height for the sheet (if the rows do not define their own height) in * points * @param height default row height */ - void setDefaultRowHeightInPoints(float height); /** - * adds a merged region of cells (hence those cells form one) + * Adds a merged region of cells (hence those cells form one) + * * @param region (rowfrom/colfrom-rowto/colto) to merge * @return index of this region */ int addMergedRegion(CellRangeAddress region); /** - * determines whether the output is vertically centered on the page. + * Determines whether the output is vertically centered on the page. + * * @param value true to vertically center, false otherwise. */ - void setVerticallyCenter(boolean value); /** - * determines whether the output is horizontally centered on the page. + * Determines whether the output is horizontally centered on the page. + * * @param value true to horizontally center, false otherwise. */ - void setHorizontallyCenter(boolean value); /** @@ -194,140 +207,187 @@ public interface Sheet extends Iterable { boolean getHorizontallyCenter(); /** - * removes a merged region of cells (hence letting them free) + * Removes a merged region of cells (hence letting them free) + * * @param index of the region to unmerge */ - void removeMergedRegion(int index); /** - * returns the number of merged regions + * Returns the number of merged regions + * * @return number of merged regions */ - int getNumMergedRegions(); /** + * Returns an iterator of the physical rows + * * @return an iterator of the PHYSICAL rows. Meaning the 3rd element may not * be the third row if say for instance the second row is undefined. */ Iterator rowIterator(); /** - * show automatic page breaks or not - * @param b whether to show auto page breaks + * Flag indicating whether the sheet displays Automatic Page Breaks. + * + * @param value true if the sheet displays Automatic Page Breaks. */ - void setAutobreaks(boolean b); /** - * set whether to display the guts or not + * Set whether to display the guts or not * - * @param b guts or no guts (or glory) + * @param value - guts or no guts */ - - void setDisplayGuts(boolean b); + void setDisplayGuts(boolean value); /** - * fit to page option is on - * @param b fit or not + * Flag indicating whether the Fit to Page print option is enabled. + * + * @param value true if the Fit to Page print option is enabled. */ - - void setFitToPage(boolean b); + void setFitToPage(boolean value); /** - * set if row summaries appear below detail in the outline - * @param b below or not + * Flag indicating whether summary rows appear below detail in an outline, when applying an outline. + * + *

+ * When true a summary row is inserted below the detailed data being summarized and a + * new outline level is established on that row. + *

+ *

+ * When false a summary row is inserted above the detailed data being summarized and a new outline level + * is established on that row. + *

+ * @param value true if row summaries appear below detail in the outline */ - - void setRowSumsBelow(boolean b); + void setRowSumsBelow(boolean value); /** - * set if col summaries appear right of the detail in the outline - * @param b right or not + * Flag indicating whether summary columns appear to the right of detail in an outline, when applying an outline. + * + *

+ * When true a summary column is inserted to the right of the detailed data being summarized + * and a new outline level is established on that column. + *

+ *

+ * When false a summary column is inserted to the left of the detailed data being + * summarized and a new outline level is established on that column. + *

+ * @param value true if col summaries appear right of the detail in the outline */ - - void setRowSumsRight(boolean b); + void setRowSumsRight(boolean value); /** - * show automatic page breaks or not - * @return whether to show auto page breaks + * Flag indicating whether the sheet displays Automatic Page Breaks. + * + * @return true if the sheet displays Automatic Page Breaks. */ - boolean getAutobreaks(); /** - * get whether to display the guts or not + * Get whether to display the guts or not, + * default value is true * - * @return guts or no guts (or glory) + * @return boolean - guts or no guts */ - boolean getDisplayGuts(); /** - * fit to page option is on - * @return fit or not + * Flag indicating whether the Fit to Page print option is enabled. + * + * @return true if the Fit to Page print option is enabled. */ - boolean getFitToPage(); /** - * get if row summaries appear below detail in the outline - * @return below or not + * Flag indicating whether summary rows appear below detail in an outline, when applying an outline. + * + *

+ * When true a summary row is inserted below the detailed data being summarized and a + * new outline level is established on that row. + *

+ *

+ * When false a summary row is inserted above the detailed data being summarized and a new outline level + * is established on that row. + *

+ * @return true if row summaries appear below detail in the outline */ - boolean getRowSumsBelow(); /** - * get if col summaries appear right of the detail in the outline - * @return right or not + * Flag indicating whether summary columns appear to the right of detail in an outline, when applying an outline. + * + *

+ * When true a summary column is inserted to the right of the detailed data being summarized + * and a new outline level is established on that column. + *

+ *

+ * When false a summary column is inserted to the left of the detailed data being + * summarized and a new outline level is established on that column. + *

+ * @return true if col summaries appear right of the detail in the outline */ - boolean getRowSumsRight(); /** - * Returns whether gridlines are printed. - * @return Gridlines are printed + * Gets the flag indicating whether this sheet displays the lines + * between rows and columns to make editing and reading easier. + * + * @return true if this sheet displays gridlines. + * @see #isPrintGridlines() to check if printing of gridlines is turned on or off */ boolean isPrintGridlines(); /** - * Turns on or off the printing of gridlines. - * @param newPrintGridlines boolean to turn on or off the printing of - * gridlines + * Sets the flag indicating whether this sheet should display the lines + * between rows and columns to make editing and reading easier. + * To turn printing of gridlines use {@link #setPrintGridlines(boolean)} + * + * + * @param show true if this sheet should display gridlines. + * @see #setPrintGridlines(boolean) */ - void setPrintGridlines(boolean newPrintGridlines); + void setPrintGridlines(boolean show); /** * Gets the print setup object. + * * @return The user model for the print setup object. */ PrintSetup getPrintSetup(); /** * 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. + *

+ * Note that XSSF offers more kinds of document headers than HSSF does + *

+ * @return the document header. */ 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. + * Note that XSSF offers more kinds of document footers than HSSF does. + * + * @return the document footer. */ Footer getFooter(); /** - * Sets whether sheet is selected. - * @param sel Whether to select the sheet or deselect the sheet. + * 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 + * @see Workbook#setActiveSheet(int) */ - void setSelected(boolean sel); + void setSelected(boolean value); /** * Gets the size of the margin in inches. + * * @param margin which margin to get * @return the size of the margin */ @@ -335,6 +395,7 @@ public interface Sheet extends Iterable { /** * Sets the size of the margin in inches. + * * @param margin which margin to get * @param size the size of the margin */ @@ -342,12 +403,14 @@ public interface Sheet extends Iterable { /** * Answer whether protection is enabled or disabled + * * @return true => protection enabled; false => protection disabled */ boolean getProtect(); /** * Answer whether scenario protection is enabled or disabled + * * @return true => protection enabled; false => protection disabled */ boolean getScenarioProtect(); @@ -364,14 +427,16 @@ public interface Sheet extends Iterable { /** * The top row in the visible view when the sheet is - * first viewed after opening it in a viewer + * first viewed after opening it in a viewer + * * @return short indicating the rownum (0 based) of the top row */ short getTopRow(); /** * The left col in the visible view when the sheet is - * first viewed after opening it in a viewer + * first viewed after opening it in a viewer + * * @return short indicating the rownum (0 based) of the top row */ short getLeftCol(); @@ -379,6 +444,7 @@ public interface Sheet extends Iterable { /** * Sets desktop window pane display area, when the * file is first opened in a viewer. + * * @param toprow the top row to show in desktop window pane * @param leftcol the left column to show in desktop window pane */ @@ -449,37 +515,43 @@ public interface Sheet extends Iterable { void createSplitPane(int xSplitPos, int ySplitPos, int leftmostColumn, int topRow, int activePane); /** - * Returns the information regarding the currently configured pane (split or freeze). + * Returns the information regarding the currently configured pane (split or freeze) + * * @return null if no pane configured, or the pane information. */ PaneInformation getPaneInformation(); /** - * Sets whether the gridlines are shown in a viewer. + * Sets whether the gridlines are shown in a viewer + * * @param show whether to show gridlines or not */ void setDisplayGridlines(boolean show); /** - * Returns if gridlines are displayed. + * Returns if gridlines are displayed + * * @return whether gridlines are displayed */ boolean isDisplayGridlines(); /** - * Sets whether the formulas are shown in a viewer. + * Sets whether the formulas are shown in a viewer + * * @param show whether to show formulas or not */ void setDisplayFormulas(boolean show); /** - * Returns if formulas are displayed. + * Returns if formulas are displayed + * * @return whether formulas are displayed */ boolean isDisplayFormulas(); /** - * Sets whether the RowColHeadings are shown in a viewer. + * Sets whether the RowColHeadings are shown in a viewer + * * @param show whether to show RowColHeadings or not */ void setDisplayRowColHeadings(boolean show); @@ -546,7 +618,7 @@ public interface Sheet extends Iterable { * @param columnNumber One of the columns in the group. * @param collapsed true = collapse group, false = expand group. */ - void setColumnGroupCollapsed(short columnNumber, boolean collapsed); + void setColumnGroupCollapsed(int columnNumber, boolean collapsed); /** * Create an outline for the provided column range. @@ -554,9 +626,15 @@ public interface Sheet extends Iterable { * @param fromColumn beginning of the column range. * @param toColumn end of the column range. */ - void groupColumn(short fromColumn, short toColumn); + void groupColumn(int fromColumn, int toColumn); - void ungroupColumn(short fromColumn, short toColumn); + /** + * Ungroup a range of columns that were previously groupped + * + * @param fromColumn start column (0-based) + * @param toColumn end column (0-based) + */ + void ungroupColumn(int fromColumn, int toColumn); /** * Tie a range of rows together so that they can be collapsed or expanded @@ -588,18 +666,37 @@ public interface Sheet extends Iterable { * @param column the column index * @param style the style to set */ - void setDefaultColumnStyle(short column, CellStyle style); + void setDefaultColumnStyle(int column, CellStyle style); /** * Adjusts the column width to fit the contents. * + *

* This process can be relatively slow on large sheets, so this should * normally only be called once per column, at the end of your * processing. + *

+ * You can specify whether the content of merged cells should be considered or ignored. + * Default is to ignore merged cells. * * @param column the column index */ - void autoSizeColumn(short column); + void autoSizeColumn(int column); + + /** + * Adjusts the column width to fit the contents. + *

+ * This process can be relatively slow on large sheets, so this should + * normally only be called once per column, at the end of your + * processing. + *

+ * You can specify whether the content of merged cells should be considered or ignored. + * Default is to ignore merged cells. + * + * @param column the column index + * @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 row and column diff --git a/src/ooxml/interfaces-jdk15/org/apache/poi/ss/usermodel/Workbook.java b/src/ooxml/interfaces-jdk15/org/apache/poi/ss/usermodel/Workbook.java index 82ef89482..5023825b4 100644 --- a/src/ooxml/interfaces-jdk15/org/apache/poi/ss/usermodel/Workbook.java +++ b/src/ooxml/interfaces-jdk15/org/apache/poi/ss/usermodel/Workbook.java @@ -23,6 +23,11 @@ import java.util.List; import org.apache.poi.ss.usermodel.Row.MissingCellPolicy; +/** + * High level representation of a Excel workbook. This is the first object most users + * will construct whether they are reading or writing a workbook. It is also the + * top level object for creating new sheets/etc. + */ public interface Workbook { /** Extended windows meta file */ @@ -43,114 +48,143 @@ public interface Workbook { /** Device independent bitmap */ public static final int PICTURE_TYPE_DIB = 7; + /** + * Convenience method to get the active sheet. The active sheet is is the sheet + * which is currently displayed when the workbook is viewed in Excel. + * 'Selected' sheet(s) is a distinct concept. + * + * @return the index of the active sheet (0-based) + */ int getActiveSheetIndex(); + + /** + * Convenience method to set the active sheet. The active sheet is is the sheet + * which is currently displayed when the workbook is viewed in Excel. + * 'Selected' sheet(s) is a distinct concept. + * + * @param sheetIndex index of the active sheet (0-based) + */ void setActiveSheet(int sheetIndex); + /** + * Gets the first tab that is displayed in the list of tabs in excel. + * + * @return the first tab that to display in the list of tabs (0-based). + */ int getFirstVisibleTab(); + + /** + * Sets the first tab that is displayed in the list of tabs in excel. + * + * @param sheetIndex the first tab that to display in the list of tabs (0-based) + */ void setFirstVisibleTab(int sheetIndex); /** - * sets the order of appearance for a given sheet. + * Sets the order of appearance for a given sheet. * * @param sheetname the name of the sheet to reorder * @param pos the position that we want to insert the sheet into (0 based) */ - void setSheetOrder(String sheetname, int pos); /** - * sets the tab whose data is actually seen when the sheet is opened. + * Sets the tab whose data is actually seen when the sheet is opened. * This may be different from the "selected sheet" since excel seems to * allow you to show the data of one sheet when another is seen "selected" * in the tabs (at the bottom). + * * @see Sheet#setSelected(boolean) - * @param index + * @param index the index of the sheet to select (0 based) */ void setSelectedTab(short index); /** - * set the sheet name. - * Will throw IllegalArgumentException if the name is greater than 31 chars - * or contains /\?*[] + * Set the sheet name. + * * @param sheet number (0 based) + * @throws IllegalArgumentException if the name is greater than 31 chars or contains /\?*[] */ void setSheetName(int sheet, String name); /** - * get the sheet name - * @param sheet Number + * Set the sheet name + * + * @param sheet sheet number (0 based) * @return Sheet name */ - String getSheetName(int sheet); - /** Returns the index of the sheet by his name + /** + * Returns the index of the sheet by his name + * * @param name the sheet name * @return index of the sheet (0 based) */ int getSheetIndex(String name); - /** Returns the index of the given sheet + /** + * Returns the index of the given sheet + * * @param sheet the sheet to look up * @return index of the sheet (0 based) */ int getSheetIndex(Sheet sheet); /** - * create an Sheet for this Workbook, adds it to the sheets and returns + * Sreate an Sheet for this Workbook, adds it to the sheets and returns * the high level representation. Use this to create new sheets. * * @return Sheet representing the new sheet. */ - Sheet createSheet(); /** - * create an Sheet from an existing sheet in the Workbook. - * - * @return Sheet representing the cloned sheet. - */ - - Sheet cloneSheet(int sheetNum); - - /** - * create an Sheet for this Workbook, adds it to the sheets and returns + * Create an Sheet for this Workbook, adds it to the sheets and returns * the high level representation. Use this to create new sheets. * - * @param sheetname sheetname to set for the sheet. + * @param sheetname sheetname to set for the sheet. * @return Sheet representing the new sheet. + * @throws IllegalArgumentException if the name is greater than 31 chars or contains /\?*[] */ - Sheet createSheet(String sheetname); /** - * get the number of spreadsheets in the workbook (this will be three after serialization) - * @return number of sheets + * Create an Sheet from an existing sheet in the Workbook. + * + * @return Sheet representing the cloned sheet. */ + Sheet cloneSheet(int sheetNum); + + /** + * Get the number of spreadsheets in the workbook + * + * @return the number of sheets + */ int getNumberOfSheets(); /** * Get the Sheet object at the given index. + * * @param index of the sheet number (0-based physical & logical) * @return Sheet at the provided index */ - Sheet getSheetAt(int index); /** * Get sheet with the given name + * * @param name of the sheet - * @return Sheet with the name provided or null if it does not exist + * @return Sheet with the name provided or null if it does not exist */ - Sheet getSheet(String name); /** - * removes sheet at the given index - * @param index of the sheet (0-based) + * Removes sheet at the given index + * + * @param index of the sheet to remove (0-based) */ - void removeSheetAt(int index); /** @@ -181,79 +215,111 @@ public interface Workbook { void setRepeatingRowsAndColumns(int sheetIndex, int startColumn, int endColumn, int startRow, int endRow); /** - * create a new Font and add it to the workbook's font table + * Create a new Font and add it to the workbook's font table + * * @return new font object */ - Font createFont(); /** * Finds a font that matches the one with the supplied attributes + * + * @return the font with the matched attributes or null */ Font findFont(short boldWeight, short color, short fontHeight, String name, boolean italic, boolean strikeout, short typeOffset, byte underline); /** - * get the number of fonts in the font table + * Get the number of fonts in the font table + * * @return number of fonts */ - short getNumberOfFonts(); /** - * get the font at the given index number - * @param idx index number - * @return XSSFFont at the index + * Get the font at the given index number + * + * @param idx index number (0-based) + * @return font at the index */ - Font getFontAt(short idx); /** - * create a new Cell style and add it to the workbook's style table + * Create a new Cell style and add it to the workbook's style table + * * @return the new Cell Style object */ - CellStyle createCellStyle(); /** - * get the number of styles the workbook contains + * Get the number of styles the workbook contains + * * @return count of cell styles */ - short getNumCellStyles(); /** - * get the cell style object at the given index - * @param idx index within the set of styles + * Get the cell style object at the given index + * + * @param idx index within the set of styles (0-based) * @return CellStyle object at the index */ - CellStyle getCellStyleAt(short idx); /** - * Method write - write out this workbook to an Outputstream. Constructs - * a new POI POIFSFileSystem, passes in the workbook binary representation and - * writes it out. - * - * @param stream - the java OutputStream you wish to write the XLS to + * Write out this workbook to an Outputstream. * + * @param stream - the java OutputStream you wish to write to * @exception IOException if anything can't be written. - * @see org.apache.poi.poifs.filesystem.POIFSFileSystem */ - void write(OutputStream stream) throws IOException; - /** gets the total number of named ranges in the workboko + /** + * Gets the total number of named ranges in the workbook + * * @return number of named ranges */ int getNumberOfNames(); - /** gets the Named range - * @param index position of the named range + /** + * Gets the Named range + * + * @param index position of the named range (0-based) * @return named range high level */ Name getNameAt(int index); /** + * Creates a new named range in this workbook + * + * @return new named range object + */ + Name createName(); + + /** + * Gets the named range index by his name + * Note:Excel named ranges are case-insensitive and + * this method performs a case-insensitive search. + * + * @param name named range name + * @return named range index + */ + int getNameIndex(String name); + + /** + * Remove the named range by his index + * + * @param index named range index (0 based) + */ + void removeName(int index); + + /** + * Remove the named range by his name + * + * @param name named range name + */ + void removeName(String name); + + /** * Sets the printarea for the sheet provided *

* i.e. Reference = $A$1:$B$2 @@ -274,7 +340,9 @@ public interface Workbook { void setPrintArea(int sheetIndex, int startColumn, int endColumn, int startRow, int endRow); /** - * Retrieves the reference for the printarea of the specified sheet, the sheet name is appended to the reference even if it was not specified. + * Retrieves the reference for the printarea of the specified sheet, + * the sheet name is appended to the reference even if it was not specified. + * * @param sheetIndex Zero-based sheet index (0 Represents the first sheet to keep consistent with java) * @return String Null if no print area has been defined */ @@ -282,6 +350,7 @@ public interface Workbook { /** * Delete the printarea for the sheet specified + * * @param sheetIndex Zero-based sheet index (0 = First Sheet) */ void removePrintArea(int sheetIndex); @@ -289,56 +358,43 @@ public interface Workbook { /** * Retrieves the current policy on what to do when * getting missing or blank cells from a row. + *

* The default is to return blank and null cells. * {@link MissingCellPolicy} + *

*/ MissingCellPolicy getMissingCellPolicy(); - /** + + /** * Sets the policy on what to do when * getting missing or blank cells from a row. + * * This will then apply to all calls to * {@link Row#getCell(int)} }. See * {@link MissingCellPolicy} */ void setMissingCellPolicy(MissingCellPolicy missingCellPolicy); - /** creates a new named range and add it to the model - * @return named range high level - */ - Name createName(); - - /** gets the named range index by his name - * Note:Excel named ranges are case-insensitive and - * this method performs a case-insensitive search. - * - * @param name named range name - * @return named range index - */ - int getNameIndex(String name); - - /** remove the named range by his index - * @param index named range index (0 based) - */ - void removeName(int index); - /** * Returns the instance of DataFormat for this workbook. + * * @return the DataFormat object */ DataFormat createDataFormat(); - /** remove the named range by his name - * @param name named range name - */ - void removeName(String name); - /** * Adds a picture to the workbook. * * @param pictureData The bytes of the picture - * @param format The format of the picture. One of PICTURE_TYPE_* + * @param format The format of the picture. * * @return the index to this picture (1 based). + * @see #PICTURE_TYPE_EMF + * @see #PICTURE_TYPE_WMF + * @see #PICTURE_TYPE_PICT + * @see #PICTURE_TYPE_JPEG + * @see #PICTURE_TYPE_PNG + * @see #PICTURE_TYPE_DIB */ int addPicture(byte[] pictureData, int format); @@ -351,51 +407,50 @@ public interface Workbook { /** * Returns an object that handles instantiating concrete - * classes of the various instances one needs for - * HSSF and XSSF. - * Works around a major shortcoming in Java, where we - * can't have static methods on interfaces or abstract - * classes. + * classes of the various instances one needs for HSSF and XSSF. */ CreationHelper getCreationHelper(); /** * Check whether a sheet is hidden. - * Note that a sheet could instead be - * set to be very hidden, which is different + *

+ * Note that a sheet could instead be set to be very hidden, which is different * ({@link #isSheetVeryHidden(int)}) + *

* @param sheetIx Number * @return True if sheet is hidden */ - public boolean isSheetHidden(int sheetIx) ; + boolean isSheetHidden(int sheetIx) ; /** * Check whether a sheet is very hidden. - * This is different from the normal - * hidden status + *

+ * This is different from the normal hidden status * ({@link #isSheetHidden(int)}) - * @param sheetIx Number - * @return True if sheet is very hidden + *

+ * @param sheetIx sheet index to check + * @return true if sheet is very hidden */ - public boolean isSheetVeryHidden(int sheetIx); + boolean isSheetVeryHidden(int sheetIx); /** * Hide or unhide a sheet * - * @param sheetIx The sheet index + * @param sheetIx the sheet index (0-based) * @param hidden True to mark the sheet as hidden, false otherwise */ - public void setSheetHidden(int sheetIx, boolean hidden); + void setSheetHidden(int sheetIx, boolean hidden); /** * Hide or unhide a sheet. + * 
      *  0 = not hidden
      *  1 = hidden
      *  2 = very hidden.
-     *
+     *
* @param sheetIx The sheet number * @param hidden 0 for not hidden, 1 for hidden, 2 for very hidden */ - public void setSheetHidden(int sheetIx, int hidden); + void setSheetHidden(int sheetIx, int hidden); } diff --git a/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFCell.java b/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFCell.java index edbae8376..f3f9c17e1 100644 --- a/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFCell.java +++ b/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFCell.java @@ -343,13 +343,6 @@ public final class XSSFCell implements Cell { if(cell.isSetV()) cell.unsetV(); } - /** - * @deprecated use {@link #getColumnIndex()} - */ - public short getCellNum() { - return (short)getColumnIndex(); - } - /** * Returns column index of this cell * @@ -584,16 +577,7 @@ public final class XSSFCell implements Cell { * * @param num column index of this cell */ - public void setCellNum(int num) { - setCellNum((short)num); - } - - /** - * Sets column index of this cell - * - * @param num column index of this cell - */ - public void setCellNum(short num) { + protected void setCellNum(int num) { checkBounds(num); cellNum = num; cell.setR(formatPosition()); 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 7613c87cf..d2f781bb2 100644 --- a/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFSheet.java +++ b/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFSheet.java @@ -252,7 +252,7 @@ public class XSSFSheet extends POIXMLDocumentPart implements Sheet { * * @param column the column index */ - public void autoSizeColumn(short column) { + public void autoSizeColumn(int column) { autoSizeColumn(column, false); } @@ -269,7 +269,7 @@ public class XSSFSheet extends POIXMLDocumentPart implements Sheet { * @param column the column index * @param useMergedCells whether to use the contents of merged cells when calculating the width of the column */ - public void autoSizeColumn(short column, boolean useMergedCells) { + public void autoSizeColumn(int column, boolean useMergedCells) { double width = ColumnHelper.getColumnWidth(this, column, useMergedCells); if(width != -1){ columnHelper.setColBestFit(column, true); @@ -932,7 +932,7 @@ public class XSSFSheet extends POIXMLDocumentPart implements Sheet { /** * Group between (0 based) columns */ - public void groupColumn(short fromColumn, short toColumn) { + public void groupColumn(int fromColumn, int toColumn) { groupColumn1Based(fromColumn+1, toColumn+1); } private void groupColumn1Based(int fromColumn, int toColumn) { @@ -1231,7 +1231,7 @@ public class XSSFSheet extends POIXMLDocumentPart implements Sheet { } } - public void setColumnGroupCollapsed(short columnNumber, boolean collapsed) { + public void setColumnGroupCollapsed(int columnNumber, boolean collapsed) { // TODO Auto-generated method stub } @@ -1261,7 +1261,7 @@ public class XSSFSheet extends POIXMLDocumentPart implements Sheet { columnHelper.setColWidth(columnIndex, (double)width/256); } - public void setDefaultColumnStyle(short column, CellStyle style) { + public void setDefaultColumnStyle(int column, CellStyle style) { columnHelper.setColDefaultStyle(column, style); } @@ -1465,7 +1465,7 @@ public class XSSFSheet extends POIXMLDocumentPart implements Sheet { getSheetTypeSheetView().setTopLeftCell(cellRef); } - public void ungroupColumn(short fromColumn, short toColumn) { + public void ungroupColumn(int fromColumn, int toColumn) { CTCols cols = worksheet.getColsArray(0); for (int index = fromColumn; index <= toColumn; index++) { CTCol col = columnHelper.getColumn(index, false);