org.zkoss.poi.ss.format

Class CellFormat

java.lang.Object

org.zkoss.poi.ss.format.CellFormat

public class CellFormat
extends Object

Format a value according to the standard Excel behavior. This "standard" is not explicitly documented by Microsoft, so the behavior is determined by experimentation; see the tests.

An Excel format has up to four parts, separated by semicolons. Each part specifies what to do with particular kinds of values, depending on the number of parts given:

One part (example: [Green]#.##)

If the value is a number, display according to this one part (example: green text, with up to two decimal points). If the value is text, display it as is.

Two parts (example: [Green]#.##;[Red]#.##)

If the value is a positive number or zero, display according to the first part (example: green text, with up to two decimal points); if it is a negative number, display according to the second part (example: red text, with up to two decimal points). If the value is text, display it as is.

Three parts (example: [Green]#.##;[Red]#.##;[Black]#.##)

If the value is a positive number, display according to the first part (example: green text, with up to two decimal points); if it is a negative number, display according to the second part (example: red text, with up to two decimal points); if it is zero, display according to the third part (example: black text, with up to two decimal points). If the value is text, display it as is.

Four parts (example: [Green]#.##;[Red]#.##;[Black]#.##;[@])

If the value is a positive number, display according to the first part (example: green text, with up to two decimal points); if it is a negative number, display according to the second part (example: red text, with up to two decimal points); if it is zero, display according to the third part (example: black text, with up to two decimal points). If the value is text, display according to the fourth part (example: text in the cell's usual color, with the text value surround by brackets).

In addition to these, there is a general format that is used when no format is specified. This formatting is presented by the #GENERAL_FORMAT object. TODO Merge this with DataFormatter so we only have one set of code for formatting numbers.

Author:

Ken Arnold, Industrious Media LLC

Constructor Summary

Constructors

Constructor and Description
CellFormat(String format) Creates a new object.

Method Summary

Modifier and Type	Method and Description
CellFormatResult	apply(Cell c) Fetches the appropriate value from the cell, and returns the result of applying it to the appropriate format.
CellFormatResult	apply(JLabel label, Cell c) Fetches the appropriate value from the cell, and uses the result, setting the text and color of a label before returning the result.
CellFormatResult	apply(JLabel label, Object value, int cellWidth) Uses the result of applying this format to the value, setting the text and color of a label before returning the result.
CellFormatResult	apply(Object value, int cellWidth) Returns the result of applying the format to the given value.
boolean	equals(Object obj) Returns true if the other object is a CellFormat object with the same format.
static CellFormat	getGeneralFormat(Locale locale)
static CellFormat	getInstance(String format, Locale locale) Returns a CellFormat that applies the given format.
int	hashCode() Returns a hash code for the format.
boolean	isApplicableDateFormat(Double value)
static int	ultimateType(Cell cell) Returns the ultimate cell type, following the results of formulas.

Methods inherited from class java.lang.Object

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

Constructor Detail

CellFormat

public CellFormat(String format)

Creates a new object.

Parameters:

format - The format.

Method Detail

getGeneralFormat

public static final CellFormat getGeneralFormat(Locale locale)

getInstance

public static CellFormat getInstance(String format,
                                     Locale locale)

Returns a CellFormat that applies the given format. Two calls with the same format may or may not return the same object.

Parameters:

format - The format.

Returns:

A CellFormat that applies the given format.

apply

public CellFormatResult apply(Object value,
                              int cellWidth)

Returns the result of applying the format to the given value. If the value is a number (a type of Number object), the correct number format type is chosen; otherwise it is considered a text object.

Parameters:

value - The value

Returns:

The result, in a CellFormatResult.

apply

public CellFormatResult apply(Cell c)

Fetches the appropriate value from the cell, and returns the result of applying it to the appropriate format. For formula cells, the computed value is what is used.

Parameters:

c - The cell.

Returns:

The result, in a CellFormatResult.

isApplicableDateFormat

public boolean isApplicableDateFormat(Double value)

apply

public CellFormatResult apply(JLabel label,
                              Object value,
                              int cellWidth)

Uses the result of applying this format to the value, setting the text and color of a label before returning the result.

Parameters:

label - The label to apply to.

value - The value to process.

Returns:

The result, in a CellFormatResult.

apply

public CellFormatResult apply(JLabel label,
                              Cell c)

Fetches the appropriate value from the cell, and uses the result, setting the text and color of a label before returning the result.

Parameters:

label - The label to apply to.

c - The cell.

Returns:

The result, in a CellFormatResult.

ultimateType

public static int ultimateType(Cell cell)

Returns the ultimate cell type, following the results of formulas. If the cell is a Cell.CELL_TYPE_FORMULA, this returns the result of Cell.getCachedFormulaResultType(). Otherwise this returns the result of Cell.getCellType().

Parameters:

cell - The cell.

Returns:

The ultimate type of this cell.

equals

public boolean equals(Object obj)

Returns true if the other object is a CellFormat object with the same format.

Overrides:

equals in class Object

Parameters:

obj - The other object.

Returns:

true if the two objects are equal.

hashCode

public int hashCode()

Returns a hash code for the format.

Overrides:

hashCode in class Object

Returns:

A hash code for the format.