org.apache.poi.hssf.model
Class InternalSheet

java.lang.Object
  org.apache.poi.hssf.model.InternalSheet

@Internal
public final class InternalSheet
extends java.lang.Object

Low level model implementation of a Sheet (one workbook contains many sheets) This file contains the low level binary records starting at the sheets BOF and ending with the sheets EOF. Use HSSFSheet for a high level representation.

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), Glen Stampoultzis (glens at apache.org), Shawn Laubach (slaubach at apache dot org) Gridlines, Headers, Footers, PrintSetup, and Setting Default Column Styles, Jason Height (jheight at chariot dot net dot au) Clone support. DBCell & Index Record writing support, Brian Sanders (kestrel at burdell dot org) Active Cell support, Jean-Pierre Paris (jean-pierre.paris at m4x dot org) (Just a little)

See Also:

InternalWorkbook, HSSFSheet

Field Summary

protected boolean	_isUncalced Add an UncalcedRecord if not true indicating formulas have not been calculated
protected RowRecordsAggregate	_rowsAggregate always present
protected SelectionRecord	_selection
static short	BottomMargin
protected DefaultColWidthRecord	defaultcolwidth
protected DefaultRowHeightRecord	defaultrowheight
protected GridsetRecord	gridset
static short	LeftMargin
static byte	PANE_LOWER_LEFT
static byte	PANE_LOWER_RIGHT
static byte	PANE_UPPER_LEFT
static byte	PANE_UPPER_RIGHT
protected PrintGridlinesRecord	printGridlines
static short	RightMargin
static short	TopMargin
protected WindowTwoRecord	windowTwo

Method Summary

int	addMergedRegion(int rowFrom, int colFrom, int rowTo, int colTo)
void	addRow(RowRecord row) Adds a row record to the sheet
void	addValueRecord(int row, CellValueRecordInterface col) Adds a value record to the sheet's contained binary records (i.e.
int	aggregateDrawingRecords(DrawingManager2 drawingManager, boolean createIfMissing) Finds the DrawingRecord for our sheet, and attaches it to the DrawingManager (which knows about the overall DrawingGroup for our workbook).
InternalSheet	cloneSheet() Clones the low level records of this sheet and returns the new sheet instance.
void	createFreezePane(int colSplit, int rowSplit, int topRow, int leftmostColumn) Creates a split (freezepane).
static InternalSheet	createSheet() Creates a sheet with all the usual records minus values and the "index" record (not required).
static InternalSheet	createSheet(RecordStream rs) read support (offset used as starting point for search) for low level API.
void	createSplitPane(int xSplitPos, int ySplitPos, int topRow, int leftmostColumn, int activePane) Creates a split pane.
Record	findFirstRecordBySid(short sid) Returns the first occurrence of a record matching a particular sid.
int	findFirstRecordLocBySid(short sid) Finds the first occurrence of a record matching a particular sid and returns it's position.
short	getActiveCellCol()
int	getActiveCellRow() Returns the active row
java.util.Iterator<CellValueRecordInterface>	getCellValueIterator() Get all the value records (from LOC).
int	getColumnWidth(int columnIndex) get the width of a given column in units of 1/256th of a character width
ConditionalFormattingTable	getConditionalFormattingTable()
int	getDefaultColumnWidth() get the default column width for the sheet (if the columns do not define their own width)
short	getDefaultRowHeight() get the default row height for the sheet (if the rows do not define their own height)
GridsetRecord	getGridsetRecord() Gets the gridset record for this sheet.
short	getLeftCol()
CellRangeAddress	getMergedRegionAt(int index)
RowRecord	getNextRow() get the NEXT RowRecord (from LOC).
NoteRecord[]	getNoteRecords() Get the NoteRecords (related to cell comments) for this sheet
int	getNumMergedRegions()
DataValidityTable	getOrCreateDataValidityTable()
PageSettingsBlock	getPageSettings()
PaneInformation	getPaneInformation() Returns the information regarding the currently configured pane (split or freeze).
PrintGridlinesRecord	getPrintGridlines() Returns the PrintGridlinesRecord.
WorksheetProtectionBlock	getProtectionBlock()
java.util.List<RecordBase>	getRecords()
RowRecord	getRow(int rownum) get the NEXT (from LOC) RowRecord where rownumber matches the given rownum.
RowRecordsAggregate	getRowsAggregate()
SelectionRecord	getSelection()
short	getTopRow()
boolean	getUncalced()
CellValueRecordInterface[]	getValueRecords() Deprecated. use getCellValueIterator() instead
WindowTwoRecord	getWindowTwo()
short	getXFIndexForColAt(short columnIndex) get the index to the ExtendedFormatRecord "associated" with the column at specified 0-based index.
void	groupColumnRange(int fromColumn, int toColumn, boolean indent) Creates an outline group for the specified columns.
void	groupRowRange(int fromRow, int toRow, boolean indent)
boolean	isColumnHidden(int columnIndex) Get the hidden property for a given column.
boolean	isDisplayFormulas() Returns if formulas are displayed.
boolean	isDisplayGridlines()
boolean	isDisplayRowColHeadings() Returns if RowColHeadings are displayed.
boolean	isGridsPrinted()
void	preSerialize() Perform any work necessary before the sheet is about to be serialized.
void	removeMergedRegion(int index)
void	removeRow(RowRecord row) Removes a row record This method is not loc sensitive, it resets loc to = dimsloc so no worries.
void	removeValueRecord(int row, CellValueRecordInterface col) remove a value record from the records array.
void	replaceValueRecord(CellValueRecordInterface newval) replace a value record from the records array.
void	setActiveCellCol(short col) Sets the active column
void	setActiveCellRow(int row) Sets the active row
void	setColumnGroupCollapsed(int columnNumber, boolean collapsed)
void	setColumnHidden(int column, boolean hidden) Get the hidden property for a given column.
void	setColumnWidth(int column, int width) set the width for a given column in 1/256th of a character width units
void	setDefaultColumnStyle(int column, int styleIndex)
void	setDefaultColumnWidth(int dcw) set the default column width for the sheet (if the columns do not define their own width)
void	setDefaultRowHeight(short dch) set the default row height for the sheet (if the rows do not define their own height)
void	setDimensions(int firstrow, short firstcol, int lastrow, short lastcol) Per an earlier reported bug in working with Andy Khan's excel read library.
void	setDisplayFormulas(boolean show) Sets whether the formulas are shown in a viewer.
void	setDisplayGridlines(boolean show) Sets whether the gridlines are shown in a viewer.
void	setDisplayRowColHeadings(boolean show) Sets whether the RowColHeadings are shown in a viewer.
void	setGridsPrinted(boolean value) set whether gridlines printed or not.
void	setLeftCol(short leftCol) Sets the left column to show in desktop window pane.
void	setPrintGridlines(PrintGridlinesRecord newPrintGridlines) Sets the PrintGridlinesRecord.
void	setSCLRecord(SCLRecord sclRecord) Sets the SCL record or creates it in the correct place if it does not already exist.
void	setSelected(boolean sel) Sets whether the sheet is selected
void	setSelection(SelectionRecord selection)
void	setTopRow(short topRow)
void	setUncalced(boolean uncalced)
void	updateFormulasAfterCellShift(FormulaShifter shifter, int externSheetIndex) Updates formulas in cells and conditional formats due to moving of cells
void	visitContainedRecords(RecordAggregate.RecordVisitor rv, int offset)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

LeftMargin

public static final short LeftMargin

See Also:

Constant Field Values

RightMargin

public static final short RightMargin

See Also:

Constant Field Values

TopMargin

public static final short TopMargin

See Also:

Constant Field Values

BottomMargin

public static final short BottomMargin

See Also:

Constant Field Values

printGridlines

protected PrintGridlinesRecord printGridlines

gridset

protected GridsetRecord gridset

defaultcolwidth

protected DefaultColWidthRecord defaultcolwidth

defaultrowheight

protected DefaultRowHeightRecord defaultrowheight

windowTwo

protected WindowTwoRecord windowTwo

_selection

protected SelectionRecord _selection

_rowsAggregate

protected final RowRecordsAggregate _rowsAggregate

always present

_isUncalced

protected boolean _isUncalced

Add an UncalcedRecord if not true indicating formulas have not been calculated

PANE_LOWER_RIGHT

public static final byte PANE_LOWER_RIGHT

See Also:

Constant Field Values

PANE_UPPER_RIGHT

public static final byte PANE_UPPER_RIGHT

See Also:

Constant Field Values

PANE_LOWER_LEFT

public static final byte PANE_LOWER_LEFT

See Also:

Constant Field Values

PANE_UPPER_LEFT

public static final byte PANE_UPPER_LEFT

See Also:

Constant Field Values

Method Detail

createSheet

public static InternalSheet createSheet(RecordStream rs)

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.

Parameters:

rs - the stream to read records from

Returns:

Sheet object with all values set to those read from the file

See Also:

InternalWorkbook, Record

cloneSheet

public InternalSheet cloneSheet()

Clones the low level records of this sheet and returns the new sheet instance. This method is implemented by adding methods for deep cloning to all records that can be added to a sheet. The Record object does not implement cloneable. When adding a new record, implement a public clone method if and only if the record belongs to a sheet.

createSheet

public static InternalSheet createSheet()

Creates a sheet with all the usual records minus values and the "index" record (not required). Sets the location pointer to where the first value records should go. Use this to create a sheet from "scratch".

Returns:

Sheet object with all values set to defaults

getRowsAggregate

public RowRecordsAggregate getRowsAggregate()

updateFormulasAfterCellShift

public void updateFormulasAfterCellShift(FormulaShifter shifter,
                                         int externSheetIndex)

Updates formulas in cells and conditional formats due to moving of cells

Parameters:

externSheetIndex - the externSheet index of this sheet

addMergedRegion

public int addMergedRegion(int rowFrom,
                           int colFrom,
                           int rowTo,
                           int colTo)

removeMergedRegion

public void removeMergedRegion(int index)

getMergedRegionAt

public CellRangeAddress getMergedRegionAt(int index)

getNumMergedRegions

public int getNumMergedRegions()

getConditionalFormattingTable

public ConditionalFormattingTable getConditionalFormattingTable()

setDimensions

public void setDimensions(int firstrow,
                          short firstcol,
                          int lastrow,
                          short lastcol)

Per an earlier reported bug in working with Andy Khan's excel read library. This sets the values in the sheet's DimensionsRecord object to be correct. Excel doesn't really care, but we want to play nice with other libraries.

See Also:

DimensionsRecord

visitContainedRecords

public void visitContainedRecords(RecordAggregate.RecordVisitor rv,
                                  int offset)

addValueRecord

public void addValueRecord(int row,
                           CellValueRecordInterface col)

Adds a value record to the sheet's contained binary records (i.e. LabelSSTRecord or NumberRecord).

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.

Parameters:

row - the row to add the cell value to

col - the cell value record itself.

removeValueRecord

public void removeValueRecord(int row,
                              CellValueRecordInterface col)

remove a value record from the records array. This method is not loc sensitive, it resets loc to = dimsloc so no worries.

Parameters:

row - - the row of the value record you wish to remove

col - - a record supporting the CellValueRecordInterface.

See Also:

CellValueRecordInterface

replaceValueRecord

public void replaceValueRecord(CellValueRecordInterface newval)

replace a value record from the records array. This method is not loc sensitive, it resets loc to = dimsloc so no worries.

Parameters:

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.

addRow

public void addRow(RowRecord row)

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.

Parameters:

row - the row record to be added

removeRow

public void removeRow(RowRecord row)

Removes a row record This method is not loc sensitive, it resets loc to = dimsloc so no worries.

Parameters:

row - the row record to remove

getCellValueIterator

public java.util.Iterator<CellValueRecordInterface> getCellValueIterator()

Get all the value records (from LOC). Records will be returned from the first record (starting at LOC) which is a value record.

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.

Returns:

Iterator of CellValueRecordInterface representing the value records

getValueRecords

@Deprecated
public CellValueRecordInterface[] getValueRecords()

Deprecated. use getCellValueIterator() instead

Get all the value records (from LOC). Records will be returned from the first record (starting at LOC) which is a value record.

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.

Returns:

Array of CellValueRecordInterface representing the remaining value records

getNextRow

public RowRecord getNextRow()

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.

Returns:

RowRecord representing the next row record or NULL if there are no more

getRow

public RowRecord getRow(int rownum)

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.

Parameters:

rownum - which row to return (careful with LOC)

Returns:

RowRecord representing the next row record or NULL if there are no more

getDefaultColumnWidth

public int getDefaultColumnWidth()

get the default column width for the sheet (if the columns do not define their own width)

Returns:

default column width

isGridsPrinted

public boolean isGridsPrinted()

Returns:

true if gridlines are printed

setGridsPrinted

public void setGridsPrinted(boolean value)

set whether gridlines printed or not.

Parameters:

value - True if gridlines printed.

setDefaultColumnWidth

public void setDefaultColumnWidth(int dcw)

set the default column width for the sheet (if the columns do not define their own width)

Parameters:

dcw - default column width

setDefaultRowHeight

public void setDefaultRowHeight(short dch)

set the default row height for the sheet (if the rows do not define their own height)

getDefaultRowHeight

public short getDefaultRowHeight()

get the default row height for the sheet (if the rows do not define their own height)

Returns:

default row height

getColumnWidth

public int getColumnWidth(int columnIndex)

get the width of a given column in units of 1/256th of a character width

Parameters:

columnIndex - index

Returns:

column width in units of 1/256th of a character width

See Also:

DefaultColWidthRecord, ColumnInfoRecord, setColumnWidth(int, int)

getXFIndexForColAt

public short getXFIndexForColAt(short columnIndex)

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.

Parameters:

columnIndex -

Returns:

index of ExtendedFormatRecord associated with ColumnInfoRecord that includes the column index or the index of the default ExtendedFormatRecord (0xF)

setColumnWidth

public void setColumnWidth(int column,
                           int width)

set the width for a given column in 1/256th of a character width units

Parameters:

column - - the column number

width - (in units of 1/256th of a character width)

isColumnHidden

public boolean isColumnHidden(int columnIndex)

Get the hidden property for a given column.

Parameters:

columnIndex - column index

Returns:

whether the column is hidden or not.

See Also:

DefaultColWidthRecord, ColumnInfoRecord, setColumnHidden(int, boolean)

setColumnHidden

public void setColumnHidden(int column,
                            boolean hidden)

Get the hidden property for a given column.

Parameters:

column - - the column number

hidden - - whether the column is hidden or not

setDefaultColumnStyle

public void setDefaultColumnStyle(int column,
                                  int styleIndex)

groupColumnRange

public void groupColumnRange(int fromColumn,
                             int toColumn,
                             boolean indent)

Creates an outline group for the specified columns.

Parameters:

fromColumn - group from this column (inclusive)

toColumn - group to this column (inclusive)

indent - if true the group will be indented by one level, if false indenting will be removed by one level.

getTopRow

public short getTopRow()

setTopRow

public void setTopRow(short topRow)

setLeftCol

public void setLeftCol(short leftCol)

Sets the left column to show in desktop window pane.

Parameters:

leftCol - the left column to show in desktop window pane

getLeftCol

public short getLeftCol()

getActiveCellRow

public int getActiveCellRow()

Returns the active row

Returns:

row the active row index

See Also:

SelectionRecord

setActiveCellRow

public void setActiveCellRow(int row)

Sets the active row

Parameters:

row - the row index

See Also:

SelectionRecord

getActiveCellCol

public short getActiveCellCol()

Returns:

column of the active cell

See Also:

SelectionRecord

setActiveCellCol

public void setActiveCellCol(short col)

Sets the active column

Parameters:

col - the column index

See Also:

SelectionRecord

getRecords

public java.util.List<RecordBase> getRecords()

getGridsetRecord

public GridsetRecord getGridsetRecord()

Gets the gridset record for this sheet.

findFirstRecordBySid

public Record findFirstRecordBySid(short sid)

Returns the first occurrence of a record matching a particular sid.

setSCLRecord

public void setSCLRecord(SCLRecord sclRecord)

Sets the SCL record or creates it in the correct place if it does not already exist.

Parameters:

sclRecord - The record to set.

findFirstRecordLocBySid

public int findFirstRecordLocBySid(short sid)

Finds the first occurrence of a record matching a particular sid and returns it's position.

Parameters:

sid - the sid to search for

Returns:

the record position of the matching record or -1 if no match is made.

getWindowTwo

public WindowTwoRecord getWindowTwo()

getPrintGridlines

public PrintGridlinesRecord getPrintGridlines()

Returns the PrintGridlinesRecord.

Returns:

PrintGridlinesRecord for the sheet.

setPrintGridlines

public void setPrintGridlines(PrintGridlinesRecord newPrintGridlines)

Sets the PrintGridlinesRecord.

Parameters:

newPrintGridlines - The new PrintGridlinesRecord for the sheet.

setSelected

public void setSelected(boolean sel)

Sets whether the sheet is selected

Parameters:

sel - True to select the sheet, false otherwise.

createFreezePane

public void createFreezePane(int colSplit,
                             int rowSplit,
                             int topRow,
                             int leftmostColumn)

Creates a split (freezepane). Any existing freezepane or split pane is overwritten.

If both colSplit and rowSplit are zero then the existing freeze pane is removed

Parameters:

colSplit - Horizonatal position of split.

rowSplit - Vertical position of split.

topRow - Top row visible in bottom pane

leftmostColumn - Left column visible in right pane.

createSplitPane

public void createSplitPane(int xSplitPos,
                            int ySplitPos,
                            int topRow,
                            int leftmostColumn,
                            int activePane)

Creates a split pane. Any existing freezepane or split pane is overwritten.

Parameters:

xSplitPos - Horizonatal position of split (in 1/20th of a point).

ySplitPos - Vertical position of split (in 1/20th of a point).

topRow - Top row visible in bottom pane

leftmostColumn - Left column visible in right pane.

activePane - Active pane. One of: PANE_LOWER_RIGHT, PANE_UPPER_RIGHT, PANE_LOWER_LEFT, PANE_UPPER_LEFT

See Also:

PANE_LOWER_LEFT, PANE_LOWER_RIGHT, PANE_UPPER_LEFT, PANE_UPPER_RIGHT

getPaneInformation

public PaneInformation getPaneInformation()

Returns the information regarding the currently configured pane (split or freeze).

Returns:

null if no pane configured, or the pane information.

getSelection

public SelectionRecord getSelection()

setSelection

public void setSelection(SelectionRecord selection)

getProtectionBlock

public WorksheetProtectionBlock getProtectionBlock()

Returns:

the WorksheetProtectionBlock for this sheet

setDisplayGridlines

public void setDisplayGridlines(boolean show)

Sets whether the gridlines are shown in a viewer.

Parameters:

show - whether to show gridlines or not

isDisplayGridlines

public boolean isDisplayGridlines()

Returns:

true if gridlines are displayed

setDisplayFormulas

public void setDisplayFormulas(boolean show)

Sets whether the formulas are shown in a viewer.

Parameters:

show - whether to show formulas or not

isDisplayFormulas

public boolean isDisplayFormulas()

Returns if formulas are displayed.

Returns:

whether formulas are displayed

setDisplayRowColHeadings

public void setDisplayRowColHeadings(boolean show)

Sets whether the RowColHeadings are shown in a viewer.

Parameters:

show - whether to show RowColHeadings or not

isDisplayRowColHeadings

public boolean isDisplayRowColHeadings()

Returns if RowColHeadings are displayed.

Returns:

whether RowColHeadings are displayed

getUncalced

public boolean getUncalced()

Returns:

whether an uncalced record must be inserted or not at generation

setUncalced

public void setUncalced(boolean uncalced)

Parameters:

uncalced - whether an uncalced record must be inserted or not at generation

aggregateDrawingRecords

public int aggregateDrawingRecords(DrawingManager2 drawingManager,
                                   boolean createIfMissing)

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

Parameters:

drawingManager - The DrawingManager2 for our workbook

createIfMissing - Should one be created if missing?

preSerialize

public void preSerialize()

Perform any work necessary before the sheet is about to be serialized. For instance the escher aggregates size needs to be calculated before serialization so that the dgg record (which occurs first) can be written.

getPageSettings

public PageSettingsBlock getPageSettings()

setColumnGroupCollapsed

public void setColumnGroupCollapsed(int columnNumber,
                                    boolean collapsed)

groupRowRange

public void groupRowRange(int fromRow,
                          int toRow,
                          boolean indent)

getOrCreateDataValidityTable

public DataValidityTable getOrCreateDataValidityTable()

getNoteRecords

public NoteRecord[] getNoteRecords()

Get the NoteRecords (related to cell comments) for this sheet

Returns:

never null, typically empty array