Class CellFormat
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]#.##;[Black]#.##;[Red]#.##)
- 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 zero, display according to the second part (example: black text, with up to two decimal points); if it is a negative number, display according to the third part (example: red text, with up to two decimal points). If the value is text, display it as is.
- Four parts (example: [Green]#.##;[Black]#.##;[Red]#.##;[@])
- 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 zero, display according to the second part (example: black text, with up to two decimal points); if it is a negative number, display according to the third part (example: red 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).
A given format part may specify a given Locale, by including something
like [$$-409] or [$£-809] or [$-40C]. These
are (currently) largely ignored. You can use DateFormatConverter
to look these up into Java Locales if desired.
In addition to these, there is a general format that is used when no format
is specified.
TODO Merge this with DataFormatter
so we only have one set of
code for formatting numbers.
TODO Re-use parts of this logic with ConditionalFormatting
/
ConditionalFormattingRule
for reporting stylings which do/don't apply
TODO Support the full set of modifiers, including alternate calendars and
native character numbers, as documented at https://help.libreoffice.org/Common/Number_Format_Codes
-
Method Summary
Modifier and TypeMethodDescriptionReturns the result of applying the format to the given value.Uses the result of applying this format to the value, setting the text and color of a label before returning the result.Fetches the appropriate value from the cell, and uses the result, setting the text and color of a label before returning the result.Fetches the appropriate value from the cell, and returns the result of applying it to the appropriate format.boolean
Returns true if the other object is aCellFormat
object with the same format.static CellFormat
getInstance
(String format) Returns aCellFormat
that applies the given format.static CellFormat
getInstance
(Locale locale, String format) Returns aCellFormat
that applies the given format.int
hashCode()
Returns a hash code for the format.static CellType
ultimateType
(Cell cell) Returns the ultimate cell type, following the results of formulas.static CellType
ultimateTypeEnum
(Cell cell) Deprecated.
-
Method Details
-
getInstance
Returns aCellFormat
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.
-
getInstance
Returns aCellFormat
that applies the given format. Two calls with the same format may or may not return the same object.- Parameters:
locale
- The locale.format
- The format.- Returns:
- A
CellFormat
that applies the given format.
-
apply
Returns the result of applying the format to the given value. If the value is a number (a type ofNumber
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
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
.
-
apply
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
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
Returns the ultimate cell type, following the results of formulas. If the cell is aCellType.FORMULA
, this returns the result ofCell.getCachedFormulaResultType()
. Otherwise this returns the result ofCell.getCellType()
.- Parameters:
cell
- The cell.- Returns:
- The ultimate type of this cell.
-
ultimateTypeEnum
Deprecated.useultimateType
insteadReturns the ultimate cell type, following the results of formulas. If the cell is aCellType.FORMULA
, this returns the result ofCell.getCachedFormulaResultType()
. Otherwise this returns the result ofCell.getCellType()
.- Parameters:
cell
- The cell.- Returns:
- The ultimate type of this cell.
- Since:
- POI 3.15 beta 3
-
equals
Returns true if the other object is aCellFormat
object with the same format. -
hashCode
public int hashCode()Returns a hash code for the format.
-
ultimateType
instead