Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.apache.poi.ss.format
Class CellFormat

    java.lang.Object
      org.apache.poi.ss.format.CellFormat

    public class CellFormat

extends java.lang.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]#.##;[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. 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. 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

Field Summary
`static CellFormat` | `GENERAL_FORMAT` Deprecated. use `getInstance(Locale, String)` instead

Method Summary
`CellFormatResult` | `apply(Cell c)` Fetches the appropriate value from the cell, and returns the result of applying it to the appropriate format.
`CellFormatResult` | `apply(javax.swing.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(javax.swing.JLabel label, java.lang.Object value)` Uses the result of applying this format to the value, setting the text and color of a label before returning the result.
`CellFormatResult` | `apply(java.lang.Object value)` Returns the result of applying the format to the given value.
`boolean` | `equals(java.lang.Object obj)` Returns `true` if the other object is a `CellFormat` object with the same format.
`static CellFormat` | `getInstance(java.util.Locale locale, java.lang.String format)` Returns a `CellFormat` that applies the given format.
`static CellFormat` | `getInstance(java.lang.String format)` Returns a `CellFormat` that applies the given format.
`int` | `hashCode()` Returns a hash code for the format.
`static int` | `ultimateType(Cell cell)` Deprecated. POI 3.15. This will return a CellType enum in the future
`static CellType` | `ultimateTypeEnum(Cell cell)` Deprecated. POI 3.15 beta 3 Will be deleted when we make the CellType enum transition. See bug 59791.

Methods inherited from class java.lang.Object
`clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### GENERAL_FORMAT

    @Deprecated
    @Removal(version="3.18")
    public static final CellFormat GENERAL_FORMAT

  Deprecated. use `getInstance(Locale, String)` instead
  Format a value as it would be were no format specified. This is also used when the format specified is `General`.

Method Detail

### getInstance

    public static CellFormat getInstance(java.lang.String format)

  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.

### getInstance

    public static CellFormat getInstance(java.util.Locale locale,
                                         java.lang.String format)

  Returns a `CellFormat` 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

    public CellFormatResult apply(java.lang.Object value)

  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`.

### apply

    public CellFormatResult apply(javax.swing.JLabel label,
                                  java.lang.Object value)

  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(javax.swing.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)

  Deprecated. POI 3.15. This will return a CellType enum in the future

  Returns the ultimate cell type, following the results of formulas. If the cell is a `CellType.FORMULA`, this returns the result of `Cell.getCachedFormulaResultTypeEnum()`. Otherwise this returns the result of `Cell.getCellTypeEnum()`. Will return `CellType` in a future version of POI. For forwards compatibility, do not hard-code cell type literals in your code.

  Parameters:
    `cell` - The cell.
  Returns:
    The ultimate type of this cell.

### ultimateTypeEnum

    public static CellType ultimateTypeEnum(Cell cell)

  Deprecated. POI 3.15 beta 3 Will be deleted when we make the CellType enum transition. See bug 59791.

  Returns the ultimate cell type, following the results of formulas. If the cell is a `CellType.FORMULA`, this returns the result of `Cell.getCachedFormulaResultTypeEnum()`. Otherwise this returns the result of `Cell.getCellTypeEnum()`.

  Parameters:
    `cell` - The cell.
  Returns:
    The ultimate type of this cell.
  Since:
    POI 3.15 beta 3

### equals

    public boolean equals(java.lang.Object obj)

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

  Overrides:
    `equals` in class `java.lang.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 `java.lang.Object`
  Returns:
    A hash code for the format.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright 2017 The Apache Software Foundation or its licensors, as applicable.