You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@poi.apache.org by ye...@apache.org on 2008/11/14 21:29:42 UTC
svn commit: r714128 - in /poi/trunk/src: documentation/content/xdocs/
documentation/content/xdocs/spreadsheet/
examples/src/org/apache/poi/xssf/usermodel/examples/
java/org/apache/poi/hssf/usermodel/
ooxml/interfaces-jdk15/org/apache/poi/ss/usermodel/ ...
Author: yegor
Date: Fri Nov 14 12:29:42 2008
New Revision: 714128
URL: http://svn.apache.org/viewvc?rev=714128&view=rev
Log:
more updates in javadocs and site documentation, also misc improvements in common hssf-xssf interfaces
Modified:
poi/trunk/src/documentation/content/xdocs/howtobuild.xml
poi/trunk/src/documentation/content/xdocs/spreadsheet/examples.xml
poi/trunk/src/documentation/content/xdocs/spreadsheet/formula.xml
poi/trunk/src/documentation/content/xdocs/spreadsheet/quick-guide.xml
poi/trunk/src/examples/src/org/apache/poi/xssf/usermodel/examples/NewLinesInCells.java
poi/trunk/src/java/org/apache/poi/hssf/usermodel/HSSFSheet.java
poi/trunk/src/ooxml/interfaces-jdk15/org/apache/poi/ss/usermodel/Cell.java
poi/trunk/src/ooxml/interfaces-jdk15/org/apache/poi/ss/usermodel/Name.java
poi/trunk/src/ooxml/interfaces-jdk15/org/apache/poi/ss/usermodel/Row.java
poi/trunk/src/ooxml/interfaces-jdk15/org/apache/poi/ss/usermodel/Sheet.java
poi/trunk/src/ooxml/interfaces-jdk15/org/apache/poi/ss/usermodel/Workbook.java
poi/trunk/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFCell.java
poi/trunk/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFSheet.java
Modified: poi/trunk/src/documentation/content/xdocs/howtobuild.xml
URL: http://svn.apache.org/viewvc/poi/trunk/src/documentation/content/xdocs/howtobuild.xml?rev=714128&r1=714127&r2=714128&view=diff
==============================================================================
--- poi/trunk/src/documentation/content/xdocs/howtobuild.xml (original)
+++ poi/trunk/src/documentation/content/xdocs/howtobuild.xml Fri Nov 14 12:29:42 2008
@@ -29,6 +29,13 @@
</header>
<body>
<section>
+ <title>JDK</title>
+ <p>
+ POI 3.5 and later requires the JDK version 1.5 or later.
+ Versions prior to 3.5 require JDK 1.4+
+ </p>
+ </section>
+ <section>
<title>Installing Ant</title>
<p>
The POI build system requires two components to perform a
@@ -114,6 +121,22 @@
<td>/junit/jars/junit-3.8.1.jar</td>
<td>lib</td>
</tr>
+ <tr>
+ <td>/dom4j/jars/dom4j-1.6.1.jar</td>
+ <td>ooxml-lib</td>
+ </tr>
+ <tr>
+ <td>/org.apache.xmlbeans/jars/xmlbeans-2.3.0.jar</td>
+ <td>ooxml-lib</td>
+ </tr>
+ <tr>
+ <td>/xmlbeans/jars/jsr173_1.0_api.jar</td>
+ <td>ooxml-lib</td>
+ </tr>
+ <tr>
+ <td>/org.apache.poi/jars/ooxml-schemas-1.0.jar</td>
+ <td>ooxml-lib</td>
+ </tr>
</table>
<p>
The main targets of interest to our users are:
Modified: poi/trunk/src/documentation/content/xdocs/spreadsheet/examples.xml
URL: http://svn.apache.org/viewvc/poi/trunk/src/documentation/content/xdocs/spreadsheet/examples.xml?rev=714128&r1=714127&r2=714128&view=diff
==============================================================================
--- poi/trunk/src/documentation/content/xdocs/spreadsheet/examples.xml (original)
+++ poi/trunk/src/documentation/content/xdocs/spreadsheet/examples.xml Fri Nov 14 12:29:42 2008
@@ -38,7 +38,7 @@
</source>
<p>All sample source is available in <link href="http://svn.apache.org/repos/asf/poi/trunk/src/examples/src/org/apache/poi/ss/examples/">SVN</link></p>
</section>
- <section><title>BusinessPlan</title>
+ <section><title>Business Plan</title>
<p> The <link href="http://svn.apache.org/repos/asf/poi/trunk/src/examples/src/org/apache/poi/ss/examples/BusinessPlan.java">BusinessPlan</link>
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 @@
</p>
</section>
<section><title>Calendar</title>
- <p> The <link href="http://svn.apache.org/repos/asf/poi/trunk/src/examples/src/org/apache/poi/ss/examples/Calendar.java">Calendar</link>
+ <p> The <link href="http://svn.apache.org/repos/asf/poi/trunk/src/examples/src/org/apache/poi/ss/examples/CalendarDemo.java">Calendar</link>
demo creates a multi sheet calendar. Each month is on a separate sheet.
</p>
<p>
<img src="../resources/images/calendar.jpg" alt="calendar demo"/>
</p>
</section>
- <section><title>LoanCalculator</title>
+ <section><title>Loan Calculator</title>
<p> The <link href="http://svn.apache.org/repos/asf/poi/trunk/src/examples/src/org/apache/poi/ss/examples/LoanCalculator.java">LoanCalculator</link>
demo creates a simple loan calculator. Demonstrates advance usage of cell formulas and named ranges.
</p>
@@ -63,8 +63,8 @@
<img src="../resources/images/loancalc.jpg" alt="loan calculator demo"/>
</p>
</section>
- <section><title>TimesheetDemo</title>
- <p> The <link href="http://svn.apache.org/repos/asf/poi/trunk/src/examples/src/org/apache/poi/ss/examples/TimesheetDemo.java">TimesheetDemo</link>
+ <section><title>Timesheet</title>
+ <p> The <link href="http://svn.apache.org/repos/asf/poi/trunk/src/examples/src/org/apache/poi/ss/examples/TimesheetDemo.java">Timesheet</link>
demo creates a weekly timesheet with automatic calculation of total hours. Demonstrates advance usage of cell formulas.
</p>
<p>
Modified: poi/trunk/src/documentation/content/xdocs/spreadsheet/formula.xml
URL: http://svn.apache.org/viewvc/poi/trunk/src/documentation/content/xdocs/spreadsheet/formula.xml?rev=714128&r1=714127&r2=714128&view=diff
==============================================================================
--- poi/trunk/src/documentation/content/xdocs/spreadsheet/formula.xml (original)
+++ poi/trunk/src/documentation/content/xdocs/spreadsheet/formula.xml Fri Nov 14 12:29:42 2008
@@ -30,7 +30,7 @@
<section><title>Introduction</title>
<p>
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.
</p>
@@ -43,43 +43,26 @@
<strong> getCellFormula() </strong> is used to retrieve the string representation of a formula.
</p>
<p>
- 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 <em> setCellFormula </em> call should be what you expect to type into excel. Also, note
that you should NOT add a "=" to the front of the string.
</p>
</section>
<section><title>Supported Features</title>
<ul>
- <li>Cell References</li>
- <li>String, integer and floating point literals</li>
- <li>Area references</li>
- <li>Relative or absolute references</li>
- <li>Arithmetic and logical operators</li>
- <li>Sheet or Macro Functions (inlcuding logical functions)</li>
- <li>Sheet References</li>
- <li>Formual return values (number or string)</li>
+ <li>References: single cell & area, 2D & 3D, relative & absolute</li>
+ <li>Literals: Number, text, boolean, error and array</li>
+ <li>Operators: arithmetic and logical, some region operators</li>
+ <li>Built-in functions: over 350 recognised, 280 evaluatable</li>
+ <li>Add-in functions: 3 from Analysis Toolpack</li>
</ul>
</section>
- <section><title>Partially supported</title>
- <ul>
- <li>Formula tokens in Excel are stored in one of three possible <em> classes </em>:
- 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.)
- </li>
-
- </ul>
- </section>
<section><title>Not yet supported</title>
<ul>
- <li>Array formulas</li>
- <li>Unary Operators</li>
- <li>3D References</li>
- <li>Error Values (cells containing #REF's or #VALUE's)</li>
- <li>Everything else :) </li>
+ <li>Manipulating array/table formulas (In Excel, formulas that look like "{=...}" as opposed to "=...")</li>
+ <li>Region operators: union, intersection</li>
+ <li>Parsing of previously uncalled add-in functions</li>
+ <li>Preservation of whitespace in formulas (when POI manipulates them)</li>
</ul>
</section>
@@ -96,9 +79,18 @@
</p>
<p>
The task of parsing a formula string into an array of RPN ordered tokens is done by the <strong>
- org.apache.poi.hssf.record.formula.FormulaParser</strong> class. This class implements a hand
+ org.apache.poi.ss.formula.FormulaParser</strong> class. This class implements a hand
written recursive descent parser.
</p>
+ <p>
+ Formula tokens in Excel are stored in one of three possible <em> operand classes </em>:
+ 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.)
+ </p>
<p>Check out the <link href="http://poi.apache.org/apidocs/">javadocs </link> for details.
</p>
</section>
Modified: poi/trunk/src/documentation/content/xdocs/spreadsheet/quick-guide.xml
URL: http://svn.apache.org/viewvc/poi/trunk/src/documentation/content/xdocs/spreadsheet/quick-guide.xml?rev=714128&r1=714127&r2=714128&view=diff
==============================================================================
--- poi/trunk/src/documentation/content/xdocs/spreadsheet/quick-guide.xml (original)
+++ poi/trunk/src/documentation/content/xdocs/spreadsheet/quick-guide.xml Fri Nov 14 12:29:42 2008
@@ -1317,10 +1317,10 @@
constructing AreaReference
</p>
<source>
- 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());
}
</source>
</section>
Modified: poi/trunk/src/examples/src/org/apache/poi/xssf/usermodel/examples/NewLinesInCells.java
URL: http://svn.apache.org/viewvc/poi/trunk/src/examples/src/org/apache/poi/xssf/usermodel/examples/NewLinesInCells.java?rev=714128&r1=714127&r2=714128&view=diff
==============================================================================
--- poi/trunk/src/examples/src/org/apache/poi/xssf/usermodel/examples/NewLinesInCells.java (original)
+++ poi/trunk/src/examples/src/org/apache/poi/xssf/usermodel/examples/NewLinesInCells.java Fri Nov 14 12:29:42 2008
@@ -47,7 +47,7 @@
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);
Modified: poi/trunk/src/java/org/apache/poi/hssf/usermodel/HSSFSheet.java
URL: http://svn.apache.org/viewvc/poi/trunk/src/java/org/apache/poi/hssf/usermodel/HSSFSheet.java?rev=714128&r1=714127&r2=714128&view=diff
==============================================================================
--- poi/trunk/src/java/org/apache/poi/hssf/usermodel/HSSFSheet.java (original)
+++ poi/trunk/src/java/org/apache/poi/hssf/usermodel/HSSFSheet.java Fri Nov 14 12:29:42 2008
@@ -1656,7 +1656,7 @@
* @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 @@
*
* @param column the column index
*/
- public void autoSizeColumn(short column) {
+ public void autoSizeColumn(int column) {
autoSizeColumn(column, false);
}
@@ -1686,7 +1686,7 @@
* @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;
/**
Modified: poi/trunk/src/ooxml/interfaces-jdk15/org/apache/poi/ss/usermodel/Cell.java
URL: http://svn.apache.org/viewvc/poi/trunk/src/ooxml/interfaces-jdk15/org/apache/poi/ss/usermodel/Cell.java?rev=714128&r1=714127&r2=714128&view=diff
==============================================================================
--- poi/trunk/src/ooxml/interfaces-jdk15/org/apache/poi/ss/usermodel/Cell.java (original)
+++ poi/trunk/src/ooxml/interfaces-jdk15/org/apache/poi/ss/usermodel/Cell.java Fri Nov 14 12:29:42 2008
@@ -20,6 +20,19 @@
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 @@
* @see #setCellType(int)
* @see #getCellType()
*/
-
public final static int CELL_TYPE_NUMERIC = 0;
/**
@@ -35,7 +47,6 @@
* @see #setCellType(int)
* @see #getCellType()
*/
-
public final static int CELL_TYPE_STRING = 1;
/**
@@ -43,7 +54,6 @@
* @see #setCellType(int)
* @see #getCellType()
*/
-
public final static int CELL_TYPE_FORMULA = 2;
/**
@@ -51,7 +61,6 @@
* @see #setCellType(int)
* @see #getCellType()
*/
-
public final static int CELL_TYPE_BLANK = 3;
/**
@@ -59,7 +68,6 @@
* @see #setCellType(int)
* @see #getCellType()
*/
-
public final static int CELL_TYPE_BOOLEAN = 4;
/**
@@ -67,32 +75,33 @@
* @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 @@
* @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 @@
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 @@
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 @@
/**
* 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();
Modified: poi/trunk/src/ooxml/interfaces-jdk15/org/apache/poi/ss/usermodel/Name.java
URL: http://svn.apache.org/viewvc/poi/trunk/src/ooxml/interfaces-jdk15/org/apache/poi/ss/usermodel/Name.java?rev=714128&r1=714127&r2=714128&view=diff
==============================================================================
--- poi/trunk/src/ooxml/interfaces-jdk15/org/apache/poi/ss/usermodel/Name.java (original)
+++ poi/trunk/src/ooxml/interfaces-jdk15/org/apache/poi/ss/usermodel/Name.java Fri Nov 14 12:29:42 2008
@@ -22,36 +22,43 @@
/** 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();
}
Modified: poi/trunk/src/ooxml/interfaces-jdk15/org/apache/poi/ss/usermodel/Row.java
URL: http://svn.apache.org/viewvc/poi/trunk/src/ooxml/interfaces-jdk15/org/apache/poi/ss/usermodel/Row.java?rev=714128&r1=714127&r2=714128&view=diff
==============================================================================
--- poi/trunk/src/ooxml/interfaces-jdk15/org/apache/poi/ss/usermodel/Row.java (original)
+++ poi/trunk/src/ooxml/interfaces-jdk15/org/apache/poi/ss/usermodel/Row.java Fri Nov 14 12:29:42 2008
@@ -20,132 +20,159 @@
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<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 @@
* 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() {
Modified: poi/trunk/src/ooxml/interfaces-jdk15/org/apache/poi/ss/usermodel/Sheet.java
URL: http://svn.apache.org/viewvc/poi/trunk/src/ooxml/interfaces-jdk15/org/apache/poi/ss/usermodel/Sheet.java?rev=714128&r1=714127&r2=714128&view=diff
==============================================================================
--- poi/trunk/src/ooxml/interfaces-jdk15/org/apache/poi/ss/usermodel/Sheet.java (original)
+++ poi/trunk/src/ooxml/interfaces-jdk15/org/apache/poi/ss/usermodel/Sheet.java Fri Nov 14 12:29:42 2008
@@ -22,6 +22,15 @@
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 @@
* 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 @@
*
* @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 @@
* @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 @@
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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 @@
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 @@
* @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 @@
* @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 @@
* @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
Modified: poi/trunk/src/ooxml/interfaces-jdk15/org/apache/poi/ss/usermodel/Workbook.java
URL: http://svn.apache.org/viewvc/poi/trunk/src/ooxml/interfaces-jdk15/org/apache/poi/ss/usermodel/Workbook.java?rev=714128&r1=714127&r2=714128&view=diff
==============================================================================
--- poi/trunk/src/ooxml/interfaces-jdk15/org/apache/poi/ss/usermodel/Workbook.java (original)
+++ poi/trunk/src/ooxml/interfaces-jdk15/org/apache/poi/ss/usermodel/Workbook.java Fri Nov 14 12:29:42 2008
@@ -23,6 +23,11 @@
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 @@
/** 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 @@
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 @@
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 @@
/**
* Delete the printarea for the sheet specified
+ *
* @param sheetIndex Zero-based sheet index (0 = First Sheet)
*/
void removePrintArea(int sheetIndex);
@@ -289,56 +358,43 @@
/**
* 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 @@
/**
* 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);
}
Modified: poi/trunk/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFCell.java
URL: http://svn.apache.org/viewvc/poi/trunk/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFCell.java?rev=714128&r1=714127&r2=714128&view=diff
==============================================================================
--- poi/trunk/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFCell.java (original)
+++ poi/trunk/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFCell.java Fri Nov 14 12:29:42 2008
@@ -344,13 +344,6 @@
}
/**
- * @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 @@
*
* @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());
Modified: poi/trunk/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFSheet.java
URL: http://svn.apache.org/viewvc/poi/trunk/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFSheet.java?rev=714128&r1=714127&r2=714128&view=diff
==============================================================================
--- poi/trunk/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFSheet.java (original)
+++ poi/trunk/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFSheet.java Fri Nov 14 12:29:42 2008
@@ -252,7 +252,7 @@
*
* @param column the column index
*/
- public void autoSizeColumn(short column) {
+ public void autoSizeColumn(int column) {
autoSizeColumn(column, false);
}
@@ -269,7 +269,7 @@
* @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 @@
/**
* 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 void setColumnGroupCollapsed(short columnNumber, boolean collapsed) {
+ public void setColumnGroupCollapsed(int columnNumber, boolean collapsed) {
// TODO Auto-generated method stub
}
@@ -1261,7 +1261,7 @@
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 @@
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);
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@poi.apache.org
For additional commands, e-mail: commits-help@poi.apache.org