288 lines
10 KiB
Java
288 lines
10 KiB
Java
/* ====================================================================
|
|
Licensed to the Apache Software Foundation (ASF) under one or more
|
|
contributor license agreements. See the NOTICE file distributed with
|
|
this work for additional information regarding copyright ownership.
|
|
The ASF licenses this file to You under the Apache License, Version 2.0
|
|
(the "License"); you may not use this file except in compliance with
|
|
the License. You may obtain a copy of the License at
|
|
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
Unless required by applicable law or agreed to in writing, software
|
|
distributed under the License is distributed on an "AS IS" BASIS,
|
|
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
See the License for the specific language governing permissions and
|
|
limitations under the License.
|
|
==================================================================== */
|
|
|
|
package org.apache.poi.ss.usermodel;
|
|
|
|
import java.util.Iterator;
|
|
|
|
import org.apache.poi.util.Removal;
|
|
|
|
/**
|
|
* 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 {@link CellType#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 or greater than the maximum number of supported columns
|
|
* (255 for *.xls, 1048576 for *.xlsx)
|
|
*/
|
|
Cell createCell(int column);
|
|
|
|
/**
|
|
* Use this to create new cells within the row and return it.
|
|
* <p>
|
|
* The cell that is returned will be of the requested type.
|
|
* The type can be changed either through calling setCellValue
|
|
* or setCellType, but there is a small overhead to doing this,
|
|
* so it is best to create of the required type up front.
|
|
*
|
|
* @param column - the column number this cell represents
|
|
* @param type - the cell's data type
|
|
* @return Cell a high level representation of the created cell.
|
|
* @throws IllegalArgumentException if columnIndex < 0 or greater than a maximum number of supported columns
|
|
* (255 for *.xls, 1048576 for *.xlsx)
|
|
* @see CellType#BLANK
|
|
* @see CellType#BOOLEAN
|
|
* @see CellType#ERROR
|
|
* @see CellType#FORMULA
|
|
* @see CellType#NUMERIC
|
|
* @see CellType#STRING
|
|
* @deprecated POI 3.15 beta 3. Use {@link #createCell(int, CellType)} instead.
|
|
*/
|
|
Cell createCell(int column, int type);
|
|
/**
|
|
* Use this to create new cells within the row and return it.
|
|
* <p>
|
|
* The cell that is returned will be of the requested type.
|
|
* The type can be changed either through calling setCellValue
|
|
* or setCellType, but there is a small overhead to doing this,
|
|
* so it is best to create of the required type up front.
|
|
*
|
|
* @param column - the column number this cell represents
|
|
* @param type - the cell's data type
|
|
* @return Cell a high level representation of the created cell.
|
|
* @throws IllegalArgumentException if columnIndex < 0 or greater than a maximum number of supported columns
|
|
* (255 for *.xls, 1048576 for *.xlsx)
|
|
*/
|
|
Cell createCell(int column, CellType type);
|
|
|
|
/**
|
|
* Remove the Cell from this row.
|
|
*
|
|
* @param cell the cell to remove
|
|
*/
|
|
void removeCell(Cell cell);
|
|
|
|
/**
|
|
* Set the row number of this row.
|
|
*
|
|
* @param rowNum the row number (0-based)
|
|
* @throws IllegalArgumentException if rowNum < 0
|
|
*/
|
|
void setRowNum(int rowNum);
|
|
|
|
/**
|
|
* 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
|
|
* 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);
|
|
|
|
/**
|
|
* Returns the cell at the given (0 based) index, with the specified {@link org.apache.poi.ss.usermodel.Row.MissingCellPolicy}
|
|
*
|
|
* @return the cell at the given (0 based) index
|
|
* @throws IllegalArgumentException if cellnum < 0 or the specified MissingCellPolicy is invalid
|
|
*/
|
|
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.
|
|
*/
|
|
short getFirstCellNum();
|
|
|
|
/**
|
|
* 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!).
|
|
* 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
|
|
* 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
|
|
*
|
|
* @param zHeight height is zero or not.
|
|
*/
|
|
void setZeroHeight(boolean zHeight);
|
|
|
|
/**
|
|
* 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 the height in points. <code>-1</code> resets to the default height
|
|
*/
|
|
void setHeightInPoints(float height);
|
|
|
|
/**
|
|
* 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();
|
|
|
|
/**
|
|
* 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();
|
|
|
|
/**
|
|
* Is this row formatted? Most aren't, but some rows
|
|
* do have whole-row styles. For those that do, you
|
|
* can get the formatting from {@link #getRowStyle()}
|
|
*/
|
|
boolean isFormatted();
|
|
|
|
/**
|
|
* Returns the whole-row cell styles. Most rows won't
|
|
* have one of these, so will return null. Call
|
|
* {@link #isFormatted()} to check first.
|
|
*/
|
|
CellStyle getRowStyle();
|
|
|
|
/**
|
|
* Applies a whole-row cell styling to the row.
|
|
*/
|
|
void setRowStyle(CellStyle style);
|
|
|
|
/**
|
|
* @return Cell iterator of the physically defined cells. Note element 4 may
|
|
* actually be row cell depending on how many are defined!
|
|
*/
|
|
Iterator<Cell> cellIterator();
|
|
|
|
/**
|
|
* Returns the Sheet this row belongs to
|
|
*
|
|
* @return the Sheet that owns this row
|
|
*/
|
|
Sheet getSheet();
|
|
|
|
/**
|
|
* Used to specify the different possible policies
|
|
* if for the case of null and blank cells
|
|
*/
|
|
public enum MissingCellPolicy {
|
|
RETURN_NULL_AND_BLANK(1),
|
|
RETURN_BLANK_AS_NULL(2),
|
|
CREATE_NULL_AS_BLANK(3);
|
|
|
|
/**
|
|
* @deprecated as of POI 3.15-beta2, scheduled for removal in 3.17 - the id has no function and will be removed.
|
|
* The {@code id} is only kept only for backwards compatibility with applications that hard-coded the number
|
|
*/
|
|
@Removal(version="3.17")
|
|
@Deprecated
|
|
public final int id;
|
|
private MissingCellPolicy(int id) {
|
|
this.id = id;
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Missing cells are returned as null, Blank cells are returned as normal
|
|
*
|
|
* @deprecated as of POI 3.15-beta2, scheduled for removal in 3.17 - use the MissingCellPolicy enum
|
|
**/
|
|
@Removal(version="3.17")
|
|
@Deprecated
|
|
public static final MissingCellPolicy RETURN_NULL_AND_BLANK = MissingCellPolicy.RETURN_NULL_AND_BLANK;
|
|
/**
|
|
* Missing cells and blank cells are returned as null
|
|
*
|
|
* @deprecated as of POI 3.15-beta2, scheduled for removal in 3.17 - use the MissingCellPolicy enum
|
|
**/
|
|
@Removal(version="3.17")
|
|
@Deprecated
|
|
public static final MissingCellPolicy RETURN_BLANK_AS_NULL = MissingCellPolicy.RETURN_BLANK_AS_NULL;
|
|
/**
|
|
* A new, blank cell is created for missing cells. Blank cells are returned as normal
|
|
*
|
|
* @deprecated as of POI 3.15-beta2, scheduled for removal in 3.17 - use the MissingCellPolicy enum
|
|
**/
|
|
@Removal(version="3.17")
|
|
@Deprecated
|
|
public static final MissingCellPolicy CREATE_NULL_AS_BLANK = MissingCellPolicy.CREATE_NULL_AS_BLANK;
|
|
|
|
/**
|
|
* Returns the rows outline level. Increased as you
|
|
* put it into more groups (outlines), reduced as
|
|
* you take it out of them.
|
|
*/
|
|
public int getOutlineLevel();
|
|
}
|