nl.fountain.xelem.excel
Interface Cell

All Superinterfaces:

XLElement

All Known Implementing Classes:

SSCell

public interface Cell
extends XLElement

Represents the Cell element. The XLElement Cell is not aware of it's parent, nor of it's index-position in a row or worksheet. This makes it possible to use the same instances of Cells on different worksheets, or different places in the worksheet. Only at the time of assembly the cell-index and the attribute ss:Index are automatically set, if necessary. See also: Row.cellIterator(). (Also a Cell that is read by the nl.fountain.xelem.lex-API has it's index set.)

The setData-methods

The overloaded setData-methods will set the data displayed in the cell when the xml spreadsheet is opened. These methods will set the Excel datatype according to the java-type of the passed parameter.

Null values
If the passed parameter has a value of null the resulting xml will have a datatype set to "Error", the formula of the cell will be set to "=#N/A" and the cell will display "#N/A" when the spreadsheet is opened.

Infinite values
If the passed parameter is of type Double, Float or the primitive representation of these objects and the method isInfinite results to true the xml will have a datatype set to "String" and the cell will display "Infinite" when the spreadsheet is opened.

NaN values
If the passed parameter is of type Double, Float or the primitive representation of these objects and the method isNaN results to true the resulting xml will have a datatype set to "String" and the cell will display "NaN" when the spreadsheet is opened.

Field Summary

static String	DATATYPE_BOOLEAN The Excel datatype for boolean values: "Boolean".
static String	DATATYPE_DATE_TIME The Excel datatype for date and time values: "DateTime".
static String	DATATYPE_ERROR The Excel datatype for error values: "Error".
static String	DATATYPE_NUMBER The Excel datatype for number values: "Number".
static String	DATATYPE_STRING The Excel datatype for string values: "String".
static String	ERRORVALUE_DIV_BY_0 The Excel error value indicating division by zero: "#DIV/0".
static String	ERRORVALUE_NA The Excel error value indicating a value is not available: "#N/A".
static String	ERRORVALUE_NAME The Excel error value indicating text in a formula is not being recognized: "#NAME?".
static String	ERRORVALUE_NULL The Excel error value indicating intersection of two cell ranges is empty "#NULL!".
static String	ERRORVALUE_NUM The Excel error value indicating problems with a number in a formula or function: "#NUM!".
static String	ERRORVALUE_REF The Excel error value indicating that a cell reference is not valid: "#REF!".
static String	ERRORVALUE_VALUE The Excel error value indicating the wrong type of argument or operand is being used: "#VALUE!".

Fields inherited from interface nl.fountain.xelem.excel.XLElement

PREFIX_HTML, PREFIX_O, PREFIX_SS, PREFIX_X, XMLNS, XMLNS_HTML, XMLNS_O, XMLNS_SS, XMLNS_X

Method Summary

Comment	addComment() Adds a comment to this cell.
Comment	addComment(Comment comment) Adds the given comment to this cell.
Comment	addComment(String text) Adds a comment to this cell and sets the data-attribute of the comment to the given text.
boolean	booleanValue() Convenience method for reading the value of the data element of this cell as a boolean.
double	doubleValue() Convenience method for reading the value of the data element of this cell as a double.
Comment	getComment() Gets the comment of this cell.
Object	getData() Gets the value of the data element of this cell as an object.
String	getData$() Gets the NodeValue of the Data-tag as a String.
Element	getDataElement(Document doc) Gets the Data-element of this cell as an org.w3c.dom.Element.
String	getFormula() Gets the formula that was set on this cell.
String	getHRef() Gets the ss:HRef-attribute value that was set on this cell.
int	getIndex() Gets the value of the ss:Index-attribute of this Cell-element.
int	getMergeAcross() Gets the number of cells over which this cell has been merged horizontally.
int	getMergeDown() Gets the number of cells over which this cell has been merged vertically.
String	getStyleID() Gets the ss:StyleID which was set on this cell.
String	getXLDataType() Gets the value of the ss:Type-attribute of the Data-element.
boolean	hasComment() Specifies whether this cell has a comment.
boolean	hasData() Specifies whether this cell has data.
boolean	hasError() Specifies whether this cell has an error.
int	intValue() Convenience method for reading the value of the data element of this cell as an int.
void	setData(boolean data) Sets the given boolean as the data of this cell.
void	setData(Boolean data) Sets the given Boolean as the data of this cell.
void	setData(byte data) Sets the given byte as the data of this cell.
void	setData(char data) Sets the data of this cell to the value String.valueOf(char).
void	setData(Date data) Sets the given Date as the data of this cell.
void	setData(double data) Sets the given double as the data of this cell.
void	setData(Double data) Sets the given Double as the data of this cell.
void	setData(float data) Sets the given float as the data of this cell.
void	setData(Float data) Sets the given Float as the data of this cell.
void	setData(int data) Sets the given int as the data of this cell.
void	setData(Integer data) Sets the given Integer as the data of this cell.
void	setData(long data) Sets the given long as the data of this cell.
void	setData(Long data) Sets the given Long as the data of this cell.
void	setData(Number data) Sets the given Number as the data of this cell.
void	setData(Object data) Sets the given object as the data of this cell.
void	setData(short data) Sets the given short as the data of this cell.
void	setData(String data) Sets the given String as the data of this cell.
void	setError(String error_value) Sets the given error value as the data of this cell.
void	setFormula(String formula) Sets the ss:Formula-attribute on this cell.
void	setHRef(String href) Sets the ss:HRef-attribute on this cell.
void	setIndex(int index) Sets the value of the ss:Index-attribute of this Cell-element.
void	setMergeAcross(int m) Merges this cell with adjacent cells on the same row.
void	setMergeDown(int m) Merges this cell with adjacent cells on the same column.
void	setStyleID(String styleID) Sets the ss:StyleID on this cell.

Methods inherited from interface nl.fountain.xelem.excel.XLElement

addElementComment, assemble, getElementComments, getNameSpace, getPrefix, getTagName, setAttributes, setChildElement

Field Detail

DATATYPE_NUMBER

static final String DATATYPE_NUMBER

The Excel datatype for number values: "Number".

See Also:

Constant Field Values

DATATYPE_DATE_TIME

static final String DATATYPE_DATE_TIME

The Excel datatype for date and time values: "DateTime".

See Also:

Constant Field Values

DATATYPE_BOOLEAN

static final String DATATYPE_BOOLEAN

The Excel datatype for boolean values: "Boolean".

See Also:

Constant Field Values

DATATYPE_STRING

static final String DATATYPE_STRING

The Excel datatype for string values: "String".

See Also:

Constant Field Values

DATATYPE_ERROR

static final String DATATYPE_ERROR

The Excel datatype for error values: "Error".

See Also:

Constant Field Values

ERRORVALUE_DIV_BY_0

static final String ERRORVALUE_DIV_BY_0

The Excel error value indicating division by zero: "#DIV/0".

See Also:

Constant Field Values

ERRORVALUE_NAME

static final String ERRORVALUE_NAME

The Excel error value indicating text in a formula is not being recognized: "#NAME?".

See Also:

Constant Field Values

ERRORVALUE_NULL

static final String ERRORVALUE_NULL

The Excel error value indicating intersection of two cell ranges is empty "#NULL!".

See Also:

Constant Field Values

ERRORVALUE_NUM

static final String ERRORVALUE_NUM

The Excel error value indicating problems with a number in a formula or function: "#NUM!".

See Also:

Constant Field Values

ERRORVALUE_NA

static final String ERRORVALUE_NA

The Excel error value indicating a value is not available: "#N/A".

See Also:

Constant Field Values

ERRORVALUE_REF

static final String ERRORVALUE_REF

The Excel error value indicating that a cell reference is not valid: "#REF!".

See Also:

Constant Field Values

ERRORVALUE_VALUE

static final String ERRORVALUE_VALUE

The Excel error value indicating the wrong type of argument or operand is being used: "#VALUE!".

See Also:

Constant Field Values

Method Detail

setStyleID

void setStyleID(String styleID)

Sets the ss:StyleID on this cell. If no styleID is set on a cell, the ss:StyleID-attribute is not deployed in the resulting xml and Excel employes the Default-style on the cell.

Parameters:

styleID - the id of the style to employ on this cell.

getStyleID

String getStyleID()

Gets the ss:StyleID which was set on this cell.

Returns:

The id of the style to employ on this cell or null if no styleID was previously set.

setFormula

void setFormula(String formula)

Sets the ss:Formula-attribute on this cell. When opening a XML spreadsheet the formula-result goes before any data-value that was set on the cell.

         cell.setData(3);
         cell.setFormula("=1+1");
 

will display 2 in the opened spreadsheet.

Parameters:

formula - The formula for this cell.

getFormula

String getFormula()

Gets the formula that was set on this cell.

Returns:

The formula that was set on this cell or null if the cell has no formula.

setHRef

void setHRef(String href)

Sets the ss:HRef-attribute on this cell. Any special html-characters will be escaped in the reulting xml.

Parameters:

href - the ss:HRef-attribute on this cell.

getHRef

String getHRef()

Gets the ss:HRef-attribute value that was set on this cell.

Returns:

The HRef that was set on this cell or null if this cell has no HRef.

addComment

Comment addComment()

Adds a comment to this cell. Initially the comment has no text (no data and no author) and is not showing. If this cell allready had a comment, replaces this comment.

Returns:

the comment added to this cell

Since:

xelem.2.0

addComment

Comment addComment(Comment comment)

Adds the given comment to this cell. If this cell allready had a comment, replaces this comment.

Parameters:

comment - the comment to be added to this cell

Returns:

the newly added comment

Since:

xelem.2.0

addComment

Comment addComment(String text)

Adds a comment to this cell and sets the data-attribute of the comment to the given text. Initially the comment will have no author and is not showing. If this cell allready had a comment, replaces this comment.

Parameters:

text - the string to be displayed in the newly added comment

Returns:

the newly added comment

Since:

xelem.2.0

hasComment

boolean hasComment()

Specifies whether this cell has a comment.

Returns:

true if this cell has a comment, false otherwise.

Since:

xelem.2.0

getComment

Comment getComment()

Gets the comment of this cell.

Returns:

the comment of this cell. May be null.

Since:

xelem.2.0

setMergeAcross

void setMergeAcross(int m)

Merges this cell with adjacent cells on the same row.

The value of m must be greater than 0 in order to have effect on the resulting xml. No logic is included to prevent the merging of cells that goes beyond the width of the spreadsheet. If such is the case, the resulting xml spreadsheet will not open.

No other cells must be added within the scope of the merged cell:

         Cell c1 = sheet.addCellAt(1, 3);  // adds a cell at row 1, column 3
         c1.setMergeAcross(5);             // merges c1 across columns 3 - 8
         // illegal: first free index = 3 + 5 + 1 = 9
         // Cell c2 = sheet.addCellAt(1, 7);
 

Parameters:

m - The number of cells to include in the merge.

getMergeAcross

int getMergeAcross()

Gets the number of cells over which this cell has been merged horizontally. A return value of 0 indicates no horizontal merge was applied on this cell.

Returns:

the number of cells that partake in the horizontal merge of this cell

Since:

xelem.2.0

setMergeDown

void setMergeDown(int m)

Merges this cell with adjacent cells on the same column.

The value of m must be greater than 0 in order to have effect on the resulting xml.

No other rows or cells must be added within the scope of the merged cell:

         Cell c1 = sheet.addCellAt(1, 3);  // adds a cell at row 1, column 3
         c1.setMergeDown(5);             // merges c1 across rows 1 - 6
         // illegal: first free index = 1 + 5 + 1 = 7
         // Cell c2 = sheet.addCellAt(5, 3);
 

Parameters:

m - The number of cells to include in the merge.

getMergeDown

int getMergeDown()

Gets the number of cells over which this cell has been merged vertically. A return value of 0 indicates no vertical merge was applied on this cell.

Returns:

the number of cells that partake in the vertical merge of this cell

Since:

xelem.2.0

setData

void setData(Number data)

Sets the given Number as the data of this cell. The attribute ss:Type of the Data-element will be set to "Number".

Parameters:

data - The data to be displayed in this cell.

See Also:

Null values

setData

void setData(Integer data)

Sets the given Integer as the data of this cell. The attribute ss:Type of the Data-element will be set to "Number".

Parameters:

data - The data to be displayed in this cell.

See Also:

Null values

setData

void setData(Double data)

Sets the given Double as the data of this cell. The attribute ss:Type of the Data-element will be set to "Number".

Parameters:

data - The data to be displayed in this cell.

See Also:

Null values, Infinite values, NaN values

setData

void setData(Long data)

Sets the given Long as the data of this cell. The attribute ss:Type of the Data-element will be set to "Number".

Parameters:

data - The data to be displayed in this cell.

See Also:

Null values

setData

void setData(Float data)

Sets the given Float as the data of this cell. The attribute ss:Type of the Data-element will be set to "Number".

Parameters:

data - The data to be displayed in this cell.

See Also:

Null values, Infinite values, NaN values

setData

void setData(Date data)

Sets the given Date as the data of this cell. The attribute ss:Type of the Data-element will be set to "DateTime".

Parameters:

data - The data to be displayed in this cell.

See Also:

Null values

setData

void setData(Boolean data)

Sets the given Boolean as the data of this cell. The attribute ss:Type of the Data-element will be set to "Boolean".

Parameters:

data - The data to be displayed in this cell.

See Also:

Null values

setData

void setData(String data)

Sets the given String as the data of this cell. The attribute ss:Type of the Data-element will be set to "String".

Parameters:

data - The data to be displayed in this cell.

See Also:

Null values

setData

void setData(Object data)

Sets the given object as the data of this cell. This method reflects upon the class of the given object and will delegate to a corresponding setData-method if such a method is available. If no corresponding method is found this method sets the data of this cell to the toString-value of the given object and the datatype to "String".

Parameters:

data - The data to be displayed in this cell.

See Also:

Null values

setError

void setError(String error_value)

Sets the given error value as the data of this cell. The attribute ss:Type of the Data-element will be set to "Error". The formula of this cell will be set to the corresponding error value.

Parameters:

error_value - Must be one of Cell's ERRORVALUE_XXX values.

setData

void setData(byte data)

Sets the given byte as the data of this cell. The attribute ss:Type of the Data-element will be set to "Number".

Parameters:

data - The data to be displayed in this cell.

setData

void setData(short data)

Sets the given short as the data of this cell. The attribute ss:Type of the Data-element will be set to "Number".

Parameters:

data - The data to be displayed in this cell.

setData

void setData(int data)

Sets the given int as the data of this cell. The attribute ss:Type of the Data-element will be set to "Number".

Parameters:

data - The data to be displayed in this cell.

setData

void setData(long data)

Sets the given long as the data of this cell. The attribute ss:Type of the Data-element will be set to "Number".

Parameters:

data - The data to be displayed in this cell.

setData

void setData(float data)

Sets the given float as the data of this cell. The attribute ss:Type of the Data-element will be set to "Number".

Parameters:

data - The data to be displayed in this cell.

See Also:

Infinite values, NaN values

setData

void setData(double data)

Sets the given double as the data of this cell. The attribute ss:Type of the Data-element will be set to "Number".

Parameters:

data - The data to be displayed in this cell.

See Also:

Infinite values, NaN values

setData

void setData(char data)

Sets the data of this cell to the value String.valueOf(char). The attribute ss:Type of the Data-element will be set to "String".

Parameters:

data - The data to be displayed in this cell.

setData

void setData(boolean data)

Sets the given boolean as the data of this cell. The attribute ss:Type of the Data-element will be set to "Boolean".

Parameters:

data - The data to be displayed in this cell.

getData$

String getData$()

Gets the NodeValue of the Data-tag as a String.

Returns:

The NodeValue of the Data-tag as a String.

getXLDataType

String getXLDataType()

Gets the value of the ss:Type-attribute of the Data-element.

Returns:

The value of the ss:Type-attribute of the Data-element.

hasData

boolean hasData()

Specifies whether this cell has data.

Returns:

true if this cell has a data element, false otherwise

Since:

xelem.2.0

hasError

boolean hasError()

Specifies whether this cell has an error.

Returns:

true if the 'Type' attribute of this cells data element equals DATATYPE_ERROR, false otherwise

getData

Object getData()

Gets the value of the data element of this cell as an object. The type of the returned object is determined by the value of the 'Type' attribute of this cells data element.

xlDataType	returned type
Number	Double
DateTime	Date
Boolean	Boolean
String	String
Error	String
(not specified)	String

Returns:

the value of the data element of this cell as an object

Since:

xelem.2.0

intValue

int intValue()

Convenience method for reading the value of the data element of this cell as an int. Returns 0 if the value could not be converted.

Returns:

the value of the data element

Since:

xelem.2.0

doubleValue

double doubleValue()

Convenience method for reading the value of the data element of this cell as a double. Returns 0.0 if the value could not be converted.

Returns:

the value of the data element

Since:

xelem.2.0

booleanValue

boolean booleanValue()

Convenience method for reading the value of the data element of this cell as a boolean. Returns false if the value is not equal to "1".

Returns:

the value of the data element

Since:

xelem.2.0

getDataElement

Element getDataElement(Document doc)

Gets the Data-element of this cell as an org.w3c.dom.Element.

Parameters:

doc - the document to which the returned element may be appended

Returns:

the Data-element

setIndex

void setIndex(int index)

Sets the value of the ss:Index-attribute of this Cell-element. Any value set may be overruled by Row.cellIterator(), which sets the index of cells during assembly.

If you want to place a cell in any particular place, use the addCellAt-methods of Row, Table or Worksheet, or use Worksheets CellPointer.

Parameters:

index - the index of this cell

getIndex

int getIndex()

Gets the value of the ss:Index-attribute of this Cell-element. The returned value only makes sence if this cell was read with the reader-API in the nl.fountain.xelem.lex-package and before any manipulation of this cell or the workbook took place.

Returns:

the value of the ss:Index-attribute of this Cell-element

Since:

xelem.2.0