aboutsummaryrefslogtreecommitdiffstats
path: root/src/ooxml
diff options
context:
space:
mode:
authorYegor Kozlov <yegor@apache.org>2008-11-14 20:29:42 +0000
committerYegor Kozlov <yegor@apache.org>2008-11-14 20:29:42 +0000
commit4a64ae88396cd31c4095bcd375f56cc388c66b22 (patch)
treea6438a9fd3519622c047515f63a86c7b80e09a1e /src/ooxml
parentc67c1d5ca0545d59ca3b8515bd78e7f02328c118 (diff)
downloadpoi-4a64ae88396cd31c4095bcd375f56cc388c66b22.tar.gz
poi-4a64ae88396cd31c4095bcd375f56cc388c66b22.zip
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
Diffstat (limited to 'src/ooxml')
-rw-r--r--src/ooxml/interfaces-jdk15/org/apache/poi/ss/usermodel/Cell.java190
-rw-r--r--src/ooxml/interfaces-jdk15/org/apache/poi/ss/usermodel/Name.java19
-rw-r--r--src/ooxml/interfaces-jdk15/org/apache/poi/ss/usermodel/Row.java107
-rw-r--r--src/ooxml/interfaces-jdk15/org/apache/poi/ss/usermodel/Sheet.java307
-rw-r--r--src/ooxml/interfaces-jdk15/org/apache/poi/ss/usermodel/Workbook.java257
-rw-r--r--src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFCell.java18
-rw-r--r--src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFSheet.java12
7 files changed, 565 insertions, 345 deletions
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 a315493781..930d0c9c66 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.
+ * <p>
+ * 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.
+ * </p>
+ * <p>
+ * Cells should have their number (0 based) before being added to a row.
+ * </p>
+ */
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
+ * Returns column index of this cell
+ *
+ * @return zero-based column index of a column in a sheet.
*/
+ int getColumnIndex();
- void setCellNum(short num);
-
- /**
- * @deprecated (Oct 2008) use {@link #getColumnIndex()}
- */
- short getCellNum();
-
/**
- * @return the cell's column index (zero based)
+ * 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 getColumnIndex();
-
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.
+ * <p>
+ * 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 <code>setCellValue(value.getTime())</code> which will
+ * automatically shift the times to the default timezone.
+ * </p>
*
* @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.
+ * <p>
+ * 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)}
+ * </p>
+ *
+ * @param formula the formula to set, e.g. <code>SUM(C4:E4)</code>.
+ * If the argument is <code>null</code> 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, <code>SUM(C4:E4)</code>
+ *
+ * @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.
+ * <p>
+ * For strings we throw an exception. For blank cells we return a 0.
+ * For formulas or error cells we return the precalculated value;
+ * </p>
+ * @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 <code>double</code>.
+ * @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.
+ * <p>
+ * For strings we throw an exception. For blank cells we return a null.
+ * </p>
+ * @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 <code>double</code>.
+ * @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
+ * <p>
+ * For numeric cells we throw an exception. For blank cells we return an empty string.
+ * For formula cells we return the pre-calculated value.
+ * </p>
+ * @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
* <p>
- * 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.
* </p>
+ * @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.
+ * <p>
+ * For strings, numbers, and errors, we throw an exception. For blank cells we return a false.
+ * </p>
+ * @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.
+ * <p>
+ * For strings, numbers, and booleans, we throw an exception.
* For blank cells we return a 0.
+ * </p>
+ *
+ * @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
+ * <code>workbook.getCellStyleAt(0)</code>
* @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 <code>null</code> 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 <code>null</code> 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 7ff4cbcf80..a0061b9515 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 f63ee010b2..2cb7b8b6d5 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<Cell> {
+
/**
* Use this to create new cells within the row and return it.
* <p>
- * 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 <code>setCellValue</code> or <code>setCellType</code>.
*
* @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.
* <p>
- * 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 <b>PLUS ONE</b>.
- * @return short representing the last logical cell in the row <b>PLUS ONE</b>, or -1 if the row does not contain any cells.
+ * Gets the index of the last cell contained in this row <b>PLUS ONE</b>. 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:
+ * <pre>
+ * short minColIx = row.getFirstCellNum();
+ * short maxColIx = row.getLastCellNum();
+ * for(short colIx=minColIx; colIx&lt;maxColIx; colIx++) {
+ * Cell cell = row.getCell(colIx);
+ * if(cell == null) {
+ * continue;
+ * }
+ * //... do something with cell
+ * }
+ * </pre>
+ *
+ * @return short representing the last logical cell in the row <b>PLUS ONE</b>,
+ * 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. <code>-1</code> 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<Cell> {
* 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 bd500d56ae..e280a35028 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.
+ *
+ * <p>
+ * 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.
+ * </p>
+ */
public interface Sheet extends Iterable<Row> {
/* Constants for margins */
@@ -49,8 +58,7 @@ public interface Sheet extends Iterable<Row> {
* 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<Row> {
*
* @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 - <code>false</code> 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<Row> {
* @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
+ * 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
*/
- public void setDefaultColumnWidth(int width);
+ 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
+ * 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<Row> {
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<Row> 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 <code>true</code> 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 <code>true</code> 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.
+ *
+ * <p>
+ * When true a summary row is inserted below the detailed data being summarized and a
+ * new outline level is established on that row.
+ * </p>
+ * <p>
+ * When false a summary row is inserted above the detailed data being summarized and a new outline level
+ * is established on that row.
+ * </p>
+ * @param value <code>true</code> 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.
+ *
+ * <p>
+ * 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.
+ * </p>
+ * <p>
+ * 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.
+ * </p>
+ * @param value <code>true</code> 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 <code>true</code> 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 <code>true</code> 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.
+ *
+ * <p>
+ * When true a summary row is inserted below the detailed data being summarized and a
+ * new outline level is established on that row.
+ * </p>
+ * <p>
+ * When false a summary row is inserted above the detailed data being summarized and a new outline level
+ * is established on that row.
+ * </p>
+ * @return <code>true</code> 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.
+ *
+ * <p>
+ * 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.
+ * </p>
+ * <p>
+ * 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.
+ * </p>
+ * @return <code>true</code> 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 <code>true</code> 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 <code>true</code> 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.
+ * <p>
+ * Note that XSSF offers more kinds of document headers than HSSF does
+ * </p>
+ * @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.
+ *<p>
+ * Note: multiple sheets can be selected, but only one sheet can be active at one time.
+ *</p>
+ * @param value <code>true</code> 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<Row> {
/**
* 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<Row> {
/**
* 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<Row> {
/**
* 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<Row> {
/**
* 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<Row> {
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<Row> {
* @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<Row> {
* @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<Row> {
* @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.
*
+ * <p>
+ * 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.
+ * </p>
+ * 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(int column);
+
+ /**
+ * Adjusts the column width to fit the contents.
+ * <p>
* 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.
+ * </p>
+ * 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(short 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 82ef894821..5023825b4b 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 <code>/\?*[]</code>
*/
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.
+ * Create 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 cloned 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 <code>/\?*[]</code>
*/
-
- Sheet cloneSheet(int sheetNum);
+ Sheet createSheet(String sheetname);
/**
- * create an Sheet for this Workbook, adds it to the sheets and returns
- * the high level representation. Use this to create new sheets.
+ * Create an Sheet from an existing sheet in the Workbook.
*
- * @param sheetname sheetname to set for the sheet.
- * @return Sheet representing the new sheet.
+ * @return Sheet representing the cloned sheet.
*/
+ Sheet cloneSheet(int sheetNum);
- Sheet createSheet(String sheetname);
/**
- * get the number of spreadsheets in the workbook (this will be three after serialization)
- * @return number of sheets
+ * 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 <code>null</code> 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 <code>null</code>
*/
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
+ * <i>Note:</i>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
* <p>
* 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.
+ * <p>
* The default is to return blank and null cells.
* {@link MissingCellPolicy}
+ * </p>
*/
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
- * <i>Note:</i>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 <code>PICTURE_TYPE_*</code>
+ * @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
+ * <p>
+ * Note that a sheet could instead be set to be very hidden, which is different
* ({@link #isSheetVeryHidden(int)})
+ * </p>
* @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
+ * <p>
+ * This is different from the normal hidden status
* ({@link #isSheetHidden(int)})
- * @param sheetIx Number
- * @return True if sheet is very hidden
+ * </p>
+ * @param sheetIx sheet index to check
+ * @return <code>true</code> 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.
+ * <pre>
* 0 = not hidden
* 1 = hidden
* 2 = very hidden.
- *
+ * </pre>
* @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 edbae83765..f3f9c17e1a 100644
--- a/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFCell.java
+++ b/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFCell.java
@@ -344,13 +344,6 @@ public final class XSSFCell implements Cell {
}
/**
- * @deprecated use {@link #getColumnIndex()}
- */
- public short getCellNum() {
- return (short)getColumnIndex();
- }
-
- /**
* Returns column index of this cell
*
* @return zero-based column index of a column in a sheet.
@@ -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 7613c87cf1..d2f781bb27 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);