* The structures of the highlevel API use references to this to perform most of their * operations. Its probably unwise to use these low level structures directly unless you * really know what you're doing. I recommend you read the Microsoft Excel 97 Developer's * Kit (Microsoft Press) and the documentation at http://sc.openoffice.org/excelfileformat.pdf * before even attempting to use this. *
* @author Andrew C. Oliver (acoliver at apache dot org)
* @author Glen Stampoultzis (glens at apache.org)
* @author Shawn Laubach (slaubach at apache dot org) Gridlines, Headers, Footers, PrintSetup, and Setting Default Column Styles
* @author Jason Height (jheight at chariot dot net dot au) Clone support. DBCell & Index Record writing support
* @author Brian Sanders (kestrel at burdell dot org) Active Cell support
* @author Jean-Pierre Paris (jean-pierre.paris at m4x dot org) (Just a little)
*
* @see org.apache.poi.hssf.model.Workbook
* @see org.apache.poi.hssf.usermodel.HSSFSheet
*/
public final class Sheet implements Model {
public static final short LeftMargin = 0;
public static final short RightMargin = 1;
public static final short TopMargin = 2;
public static final short BottomMargin = 3;
private static POILogger log = POILogFactory.getLogger(Sheet.class);
private List
* This method is "loc" sensitive. Meaning you need to set LOC to where you
* want it to start searching. If you don't know do this: setLoc(getDimsLoc).
* When adding several rows you can just start at the last one by leaving loc
* at what this sets it to.
*
* @param row the row to add the cell value to
* @param col the cell value record itself.
*/
public void addValueRecord(int row, CellValueRecordInterface col) {
if(log.check(POILogger.DEBUG)) {
log.log(POILogger.DEBUG, "add value record row" + row);
}
DimensionsRecord d = _dimensions;
if (col.getColumn() > d.getLastCol()) {
d.setLastCol(( short ) (col.getColumn() + 1));
}
if (col.getColumn() < d.getFirstCol()) {
d.setFirstCol(col.getColumn());
}
_rowsAggregate.insertCell(col);
}
/**
* remove a value record from the records array.
*
* This method is not loc sensitive, it resets loc to = dimsloc so no worries.
*
* @param row - the row of the value record you wish to remove
* @param col - a record supporting the CellValueRecordInterface.
* @see org.apache.poi.hssf.record.CellValueRecordInterface
*/
public void removeValueRecord(int row, CellValueRecordInterface col) {
log.logFormatted(POILogger.DEBUG, "remove value record row %",
new int[]{row } );
_rowsAggregate.removeCell(col);
}
/**
* replace a value record from the records array.
*
* This method is not loc sensitive, it resets loc to = dimsloc so no worries.
*
* @param newval - a record supporting the CellValueRecordInterface. this will replace
* the cell value with the same row and column. If there isn't one, one will
* be added.
*/
public void replaceValueRecord(CellValueRecordInterface newval) {
if (log.check( POILogger.DEBUG ))
log.log(POILogger.DEBUG, "replaceValueRecord ");
//The ValueRecordsAggregate use a tree map underneath.
//The tree Map uses the CellValueRecordInterface as both the
//key and the value, if we dont do a remove, then
//the previous instance of the key is retained, effectively using
//double the memory
_rowsAggregate.removeCell(newval);
_rowsAggregate.insertCell(newval);
}
/**
* Adds a row record to the sheet
*
*
* This method is "loc" sensitive. Meaning you need to set LOC to where you
* want it to start searching. If you don't know do this: setLoc(getDimsLoc).
* When adding several rows you can just start at the last one by leaving loc
* at what this sets it to.
*
* @param row the row record to be added
*/
public void addRow(RowRecord row) {
if (log.check( POILogger.DEBUG ))
log.log(POILogger.DEBUG, "addRow ");
DimensionsRecord d = _dimensions;
if (row.getRowNumber() >= d.getLastRow()) {
d.setLastRow(row.getRowNumber() + 1);
}
if (row.getRowNumber() < d.getFirstRow()) {
d.setFirstRow(row.getRowNumber());
}
//If the row exists remove it, so that any cells attached to the row are removed
RowRecord existingRow = _rowsAggregate.getRow(row.getRowNumber());
if (existingRow != null) {
_rowsAggregate.removeRow(existingRow);
}
_rowsAggregate.insertRow(row);
if (log.check( POILogger.DEBUG ))
log.log(POILogger.DEBUG, "exit addRow");
}
/**
* Removes a row record
*
* This method is not loc sensitive, it resets loc to = dimsloc so no worries.
*
* @param row the row record to remove
*/
public void removeRow(RowRecord row) {
_rowsAggregate.removeRow(row);
}
/**
* get the NEXT value record (from LOC). The first record that is a value record
* (starting at LOC) will be returned.
*
*
* This method is "loc" sensitive. Meaning you need to set LOC to where you
* want it to start searching. If you don't know do this: setLoc(getDimsLoc).
* When adding several rows you can just start at the last one by leaving loc
* at what this sets it to. For this method, set loc to dimsloc to start with,
* subsequent calls will return values in (physical) sequence or NULL when you get to the end.
*
* @return CellValueRecordInterface representing the next value record or NULL if there are no more
*/
public CellValueRecordInterface[] getValueRecords() {
return _rowsAggregate.getValueRecords();
}
/**
* get the NEXT RowRecord (from LOC). The first record that is a Row record
* (starting at LOC) will be returned.
*
* This method is "loc" sensitive. Meaning you need to set LOC to where you
* want it to start searching. If you don't know do this: setLoc(getDimsLoc).
* When adding several rows you can just start at the last one by leaving loc
* at what this sets it to. For this method, set loc to dimsloc to start with.
* subsequent calls will return rows in (physical) sequence or NULL when you get to the end.
*
* @return RowRecord representing the next row record or NULL if there are no more
*/
public RowRecord getNextRow() {
if (rowRecIterator == null)
{
rowRecIterator = _rowsAggregate.getIterator();
}
if (!rowRecIterator.hasNext())
{
return null;
}
return ( RowRecord ) rowRecIterator.next();
}
/**
* get the NEXT (from LOC) RowRecord where rownumber matches the given rownum.
* The first record that is a Row record (starting at LOC) that has the
* same rownum as the given rownum will be returned.
*
* This method is "loc" sensitive. Meaning you need to set LOC to where you
* want it to start searching. If you don't know do this: setLoc(getDimsLoc).
* When adding several rows you can just start at the last one by leaving loc
* at what this sets it to. For this method, set loc to dimsloc to start with.
* subsequent calls will return rows in (physical) sequence or NULL when you get to the end.
*
* @param rownum which row to return (careful with LOC)
* @return RowRecord representing the next row record or NULL if there are no more
*
*/
public RowRecord getRow(int rownum) {
return _rowsAggregate.getRow(rownum);
}
/**
* creates the BOF record
*/
/* package */ static BOFRecord createBOF() {
BOFRecord retval = new BOFRecord();
retval.setVersion(( short ) 0x600);
retval.setType(( short ) 0x010);
retval.setBuild(( short ) 0x0dbb);
retval.setBuildYear(( short ) 1996);
retval.setHistoryBitMask(0xc1);
retval.setRequiredVersion(0x6);
return retval;
}
/**
* creates the CalcMode record and sets it to 1 (automatic formula caculation)
*/
private static CalcModeRecord createCalcMode() {
CalcModeRecord retval = new CalcModeRecord();
retval.setCalcMode(( short ) 1);
return retval;
}
/**
* creates the CalcCount record and sets it to 100 (default number of iterations)
*/
private static CalcCountRecord createCalcCount() {
CalcCountRecord retval = new CalcCountRecord();
retval.setIterations(( short ) 100); // default 100 iterations
return retval;
}
/**
* creates the RefMode record and sets it to A1 Mode (default reference mode)
*/
private static RefModeRecord createRefMode() {
RefModeRecord retval = new RefModeRecord();
retval.setMode(RefModeRecord.USE_A1_MODE);
return retval;
}
/**
* creates the Iteration record and sets it to false (don't iteratively calculate formulas)
*/
private static IterationRecord createIteration() {
return new IterationRecord(false);
}
/**
* creates the Delta record and sets it to 0.0010 (default accuracy)
*/
private static DeltaRecord createDelta() {
return new DeltaRecord(DeltaRecord.DEFAULT_VALUE);
}
/**
* creates the SaveRecalc record and sets it to true (recalculate before saving)
*/
private static SaveRecalcRecord createSaveRecalc() {
SaveRecalcRecord retval = new SaveRecalcRecord();
retval.setRecalc(true);
return retval;
}
/**
* creates the PrintHeaders record and sets it to false (we don't create headers yet so why print them)
*/
private static PrintHeadersRecord createPrintHeaders() {
PrintHeadersRecord retval = new PrintHeadersRecord();
retval.setPrintHeaders(false);
return retval;
}
/**
* creates the PrintGridlines record and sets it to false (that makes for ugly sheets). As far as I can
* tell this does the same thing as the GridsetRecord
*/
private static PrintGridlinesRecord createPrintGridlines() {
PrintGridlinesRecord retval = new PrintGridlinesRecord();
retval.setPrintGridlines(false);
return retval;
}
/**
* creates the Gridset record and sets it to true (user has mucked with the gridlines)
*/
private static GridsetRecord createGridset() {
GridsetRecord retval = new GridsetRecord();
retval.setGridset(true);
return retval;
}
/**
* creates the Guts record and sets leftrow/topcol guttter and rowlevelmax/collevelmax to 0
*/
private static GutsRecord createGuts() {
GutsRecord retval = new GutsRecord();
retval.setLeftRowGutter(( short ) 0);
retval.setTopColGutter(( short ) 0);
retval.setRowLevelMax(( short ) 0);
retval.setColLevelMax(( short ) 0);
return retval;
}
private GutsRecord getGutsRecord() {
if (_gutsRecord == null) {
GutsRecord result = createGuts();
RecordOrderer.addNewSheetRecord(_records, result);
_gutsRecord = result;
}
return _gutsRecord;
}
/**
* creates the DefaultRowHeight Record and sets its options to 0 and rowheight to 0xff
*/
private static DefaultRowHeightRecord createDefaultRowHeight() {
DefaultRowHeightRecord retval = new DefaultRowHeightRecord();
retval.setOptionFlags(( short ) 0);
retval.setRowHeight(( short ) 0xff);
return retval;
}
/**
* creates the WSBoolRecord and sets its values to defaults
*/
private static WSBoolRecord createWSBool() {
WSBoolRecord retval = new WSBoolRecord();
retval.setWSBool1(( byte ) 0x4);
retval.setWSBool2(( byte ) 0xffffffc1);
return retval;
}
/**
* creates the DefaultColWidth Record and sets it to 8
*/
private static DefaultColWidthRecord createDefaultColWidth() {
DefaultColWidthRecord retval = new DefaultColWidthRecord();
retval.setColWidth(( short ) 8);
return retval;
}
/**
* get the default column width for the sheet (if the columns do not define their own width)
* @return default column width
*/
public int getDefaultColumnWidth() {
return defaultcolwidth.getColWidth();
}
/**
* @return
* options = 0x6b6
* toprow = 0
* leftcol = 0
* headercolor = 0x40
* pagebreakzoom = 0x0
* normalzoom = 0x0
*/
private static WindowTwoRecord createWindowTwo() {
WindowTwoRecord retval = new WindowTwoRecord();
retval.setOptions(( short ) 0x6b6);
retval.setTopRow(( short ) 0);
retval.setLeftCol(( short ) 0);
retval.setHeaderColor(0x40);
retval.setPageBreakZoom(( short ) 0);
retval.setNormalZoom(( short ) 0);
return retval;
}
/**
* Creates the Selection record and sets it to nothing selected
*/
private static SelectionRecord createSelection() {
return new SelectionRecord(0, 0);
}
public short getTopRow() {
return (windowTwo==null) ? (short) 0 : windowTwo.getTopRow();
}
public void setTopRow(short topRow) {
if (windowTwo!=null) {
windowTwo.setTopRow(topRow);
}
}
/**
* Sets the left column to show in desktop window pane.
* @param leftCol the left column to show in desktop window pane
*/
public void setLeftCol(short leftCol) {
if (windowTwo!=null) {
windowTwo.setLeftCol(leftCol);
}
}
public short getLeftCol() {
return (windowTwo==null) ? (short) 0 : windowTwo.getLeftCol();
}
/**
* Returns the active row
*
* @see org.apache.poi.hssf.record.SelectionRecord
* @return row the active row index
*/
public int getActiveCellRow() {
if (_selection == null) {
return 0;
}
return _selection.getActiveCellRow();
}
/**
* Sets the active row
*
* @param row the row index
* @see org.apache.poi.hssf.record.SelectionRecord
*/
public void setActiveCellRow(int row) {
//shouldn't have a sheet w/o a SelectionRecord, but best to guard anyway
if (_selection != null) {
_selection.setActiveCellRow(row);
}
}
/**
* @see org.apache.poi.hssf.record.SelectionRecord
* @return column of the active cell
*/
public short getActiveCellCol() {
if (_selection == null) {
return 0;
}
return (short)_selection.getActiveCellCol();
}
/**
* Sets the active column
*
* @param col the column index
* @see org.apache.poi.hssf.record.SelectionRecord
*/
public void setActiveCellCol(short col) {
//shouldn't have a sheet w/o a SelectionRecord, but best to guard anyway
if (_selection != null)
{
_selection.setActiveCellCol(col);
}
}
public List
* Aggregate object is always present, but possibly empty.
*/
private final WorksheetProtectionBlock _protectionBlock = new WorksheetProtectionBlock();
protected WindowTwoRecord windowTwo = null;
protected SelectionRecord _selection = null;
/** java object always present, but if empty no BIFF records are written */
private final MergedCellsTable _mergedCellsTable;
/** always present in this POI object, not always written to Excel file */
/*package*/ColumnInfoRecordsAggregate _columnInfos;
/** the DimensionsRecord is always present */
private DimensionsRecord _dimensions;
/** always present */
protected final RowRecordsAggregate _rowsAggregate;
private DataValidityTable _dataValidityTable= null;
private ConditionalFormattingTable condFormatting;
private Iterator rowRecIterator = null;
/** Add an UncalcedRecord if not true indicating formulas have not been calculated */
protected boolean _isUncalced = false;
public static final byte PANE_LOWER_RIGHT = (byte)0;
public static final byte PANE_UPPER_RIGHT = (byte)1;
public static final byte PANE_LOWER_LEFT = (byte)2;
public static final byte PANE_UPPER_LEFT = (byte)3;
/**
* read support (offset used as starting point for search) for low level
* API. Pass in an array of Record objects, the sheet number (0 based) and
* a record offset (should be the location of the sheets BOF record). A Sheet
* object is constructed and passed back with all of its initialization set
* to the passed in records and references to those records held. This function
* is normally called via Workbook.
*
* @param rs the stream to read records from
*
* @return Sheet object with all values set to those read from the file
*
* @see org.apache.poi.hssf.model.Workbook
* @see org.apache.poi.hssf.record.Record
*/
public static Sheet createSheet(RecordStream rs) {
return new Sheet(rs);
}
private Sheet(RecordStream rs) {
_mergedCellsTable = new MergedCellsTable();
RowRecordsAggregate rra = null;
Listtrue if gridlines are printed
*/
public boolean isGridsPrinted() {
if (gridset == null) {
gridset = createGridset();
//Insert the newlycreated Gridset record at the end of the record (just before the EOF)
int loc = findFirstRecordLocBySid(EOFRecord.sid);
_records.add(loc, gridset);
}
return !gridset.getGridset();
}
/**
* set whether gridlines printed or not.
* @param value True if gridlines printed.
*/
public void setGridsPrinted(boolean value) {
gridset.setGridset(!value);
}
/**
* set the default column width for the sheet (if the columns do not define their own width)
* @param dcw default column width
*/
public void setDefaultColumnWidth(int dcw) {
defaultcolwidth.setColWidth(dcw);
}
/**
* set the default row height for the sheet (if the rows do not define their own height)
*/
public void setDefaultRowHeight(short dch) {
defaultrowheight.setRowHeight(dch);
}
/**
* get the default row height for the sheet (if the rows do not define their own height)
* @return default row height
*/
public short getDefaultRowHeight() {
return defaultrowheight.getRowHeight();
}
/**
* get the width of a given column in units of 1/256th of a character width
* @param columnIndex index
* @see org.apache.poi.hssf.record.DefaultColWidthRecord
* @see org.apache.poi.hssf.record.ColumnInfoRecord
* @see #setColumnWidth(int, int)
* @return column width in units of 1/256th of a character width
*/
public int getColumnWidth(int columnIndex) {
ColumnInfoRecord ci = _columnInfos.findColumnInfo(columnIndex);
if (ci != null) {
return ci.getColumnWidth();
}
//default column width is measured in characters
//multiply
return (256*defaultcolwidth.getColWidth());
}
/**
* get the index to the ExtendedFormatRecord "associated" with
* the column at specified 0-based index. (In this case, an
* ExtendedFormatRecord index is actually associated with a
* ColumnInfoRecord which spans 1 or more columns)
*
* Returns the index to the default ExtendedFormatRecord (0xF)
* if no ColumnInfoRecord exists that includes the column
* index specified.
* @param columnIndex
* @return index of ExtendedFormatRecord associated with
* ColumnInfoRecord that includes the column index or the
* index of the default ExtendedFormatRecord (0xF)
*/
public short getXFIndexForColAt(short columnIndex) {
ColumnInfoRecord ci = _columnInfos.findColumnInfo(columnIndex);
if (ci != null) {
return (short)ci.getXFIndex();
}
return 0xF;
}
/**
* set the width for a given column in 1/256th of a character width units
*
* @param column -
* the column number
* @param width
* (in units of 1/256th of a character width)
*/
public void setColumnWidth(int column, int width) {
if(width > 255*256) throw new IllegalArgumentException("The maximum column width for an individual cell is 255 characters.");
setColumn(column, null, Integer.valueOf(width), null, null, null);
}
/**
* Get the hidden property for a given column.
* @param columnIndex column index
* @see org.apache.poi.hssf.record.DefaultColWidthRecord
* @see org.apache.poi.hssf.record.ColumnInfoRecord
* @see #setColumnHidden(int, boolean)
* @return whether the column is hidden or not.
*/
public boolean isColumnHidden(int columnIndex) {
ColumnInfoRecord cir = _columnInfos.findColumnInfo(columnIndex);
if (cir == null) {
return false;
}
return cir.getHidden();
}
/**
* Get the hidden property for a given column.
* @param column - the column number
* @param hidden - whether the column is hidden or not
*/
public void setColumnHidden(int column, boolean hidden) {
setColumn( column, null, null, null, Boolean.valueOf(hidden), null);
}
public void setDefaultColumnStyle(int column, int styleIndex) {
setColumn(column, Short.valueOf((short)styleIndex), null, null, null, null);
}
private void setColumn(int column, Short xfStyle, Integer width, Integer level, Boolean hidden, Boolean collapsed) {
_columnInfos.setColumn( column, xfStyle, width, level, hidden, collapsed );
}
/**
* Creates an outline group for the specified columns.
* @param fromColumn group from this column (inclusive)
* @param toColumn group to this column (inclusive)
* @param indent if true the group will be indented by one level,
* if false indenting will be removed by one level.
*/
public void groupColumnRange(int fromColumn, int toColumn, boolean indent) {
// Set the level for each column
_columnInfos.groupColumnRange( fromColumn, toColumn, indent);
// Determine the maximum overall level
int maxLevel = _columnInfos.getMaxOutlineLevel();
GutsRecord guts = getGutsRecord();
guts.setColLevelMax( (short) ( maxLevel+1 ) );
if (maxLevel == 0) {
guts.setTopColGutter( (short)0 );
} else {
guts.setTopColGutter( (short) ( 29 + (12 * (maxLevel-1)) ) );
}
}
/**
* creates the Dimensions Record and sets it to bogus values (you should set this yourself
* or let the high level API do it for you)
*/
private static DimensionsRecord createDimensions() {
DimensionsRecord retval = new DimensionsRecord();
retval.setFirstCol(( short ) 0);
retval.setLastRow(1); // one more than it is
retval.setFirstRow(0);
retval.setLastCol(( short ) 1); // one more than it is
return retval;
}
/**
* creates the WindowTwo Record and sets it to: null if no pane configured, or the pane information.
*/
public PaneInformation getPaneInformation() {
PaneRecord rec = (PaneRecord)findFirstRecordBySid(PaneRecord.sid);
if (rec == null)
return null;
return new PaneInformation(rec.getX(), rec.getY(), rec.getTopRow(),
rec.getLeftColumn(), (byte)rec.getActivePane(), windowTwo.getFreezePanes());
}
public SelectionRecord getSelection() {
return _selection;
}
public void setSelection( SelectionRecord selection) {
_selection = selection;
}
/**
* @return the {@link WorksheetProtectionBlock} for this sheet
*/
public WorksheetProtectionBlock getProtectionBlock() {
return _protectionBlock;
}
/**
* Sets whether the gridlines are shown in a viewer.
* @param show whether to show gridlines or not
*/
public void setDisplayGridlines(boolean show) {
windowTwo.setDisplayGridlines(show);
}
/**
* @return true if gridlines are displayed
*/
public boolean isDisplayGridlines() {
return windowTwo.getDisplayGridlines();
}
/**
* Sets whether the formulas are shown in a viewer.
* @param show whether to show formulas or not
*/
public void setDisplayFormulas(boolean show) {
windowTwo.setDisplayFormulas(show);
}
/**
* Returns if formulas are displayed.
* @return whether formulas are displayed
*/
public boolean isDisplayFormulas() {
return windowTwo.getDisplayFormulas();
}
/**
* Sets whether the RowColHeadings are shown in a viewer.
* @param show whether to show RowColHeadings or not
*/
public void setDisplayRowColHeadings(boolean show) {
windowTwo.setDisplayRowColHeadings(show);
}
/**
* Returns if RowColHeadings are displayed.
* @return whether RowColHeadings are displayed
*/
public boolean isDisplayRowColHeadings() {
return windowTwo.getDisplayRowColHeadings();
}
/**
* @return whether an uncalced record must be inserted or not at generation
*/
public boolean getUncalced() {
return _isUncalced;
}
/**
* @param uncalced whether an uncalced record must be inserted or not at generation
*/
public void setUncalced(boolean uncalced) {
this._isUncalced = uncalced;
}
/**
* Finds the DrawingRecord for our sheet, and
* attaches it to the DrawingManager (which knows about
* the overall DrawingGroup for our workbook).
* If requested, will create a new DrawRecord
* if none currently exist
* @param drawingManager The DrawingManager2 for our workbook
* @param createIfMissing Should one be created if missing?
*/
public int aggregateDrawingRecords(DrawingManager2 drawingManager, boolean createIfMissing) {
int loc = findFirstRecordLocBySid(DrawingRecord.sid);
boolean noDrawingRecordsFound = (loc == -1);
if (noDrawingRecordsFound) {
if(!createIfMissing) {
// None found, and not allowed to add in
return -1;
}
EscherAggregate aggregate = new EscherAggregate( drawingManager );
loc = findFirstRecordLocBySid(EscherAggregate.sid);
if (loc == -1) {
loc = findFirstRecordLocBySid( WindowTwoRecord.sid );
} else {
getRecords().remove(loc);
}
getRecords().add( loc, aggregate );
return loc;
}
Listnull, typically empty array
*/
public NoteRecord[] getNoteRecords() {
List