Package org.apache.poi.xssf.usermodel

Class XSSFRichTextString

java.lang.Object
org.apache.poi.xssf.usermodel.XSSFRichTextString
All Implemented Interfaces:
RichTextString
public class XSSFRichTextString extends Object implements RichTextString
Rich text unicode string. These strings can have fonts applied to arbitary parts of the string.

Most strings in a workbook have formatting applied at the cell level, that is, the entire string in the cell has the same formatting applied. In these cases, the formatting for the cell is stored in the styles part, and the string for the cell can be shared across the workbook. The following code illustrates the example. 

     cell1.setCellValue(new XSSFRichTextString("Apache POI"));
     cell2.setCellValue(new XSSFRichTextString("Apache POI"));
     cell3.setCellValue(new XSSFRichTextString("Apache POI"));
In the above example all three cells will use the same string cached on workbook level.

Some strings in the workbook may have formatting applied at a level that is more granular than the cell level. For instance, specific characters within the string may be bolded, have coloring, italicizing, etc. In these cases, the formatting is stored along with the text in the string table, and is treated as a unique entry in the workbook. The following xml and code snippet illustrate this. 

     XSSFRichTextString s1 = new XSSFRichTextString("Apache POI");
     s1.applyFont(boldArial);
     cell1.setCellValue(s1);

     XSSFRichTextString s2 = new XSSFRichTextString("Apache POI");
     s2.applyFont(italicCourier);
     cell2.setCellValue(s2);

  • Constructor Summary

    Constructors
    Constructor
    Description
    XSSFRichTextString()
    Create empty rich text string and initialize it with empty string
    XSSFRichTextString(String str)
    Create a rich text string
    XSSFRichTextString(org.openxmlformats.schemas.spreadsheetml.x2006.main.CTRst st)
    Create a rich text string from the supplied XML bean

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    append(String text)
    Append new text to this text run
    void
    append(String text, XSSFFont font)
    Append new text to this text run and apply the specify font to it
    void
    applyFont(int startIndex, int endIndex, short fontIndex)
    Applies a font to the specified characters of a string.
    void
    applyFont(int startIndex, int endIndex, Font font)
    Applies a font to the specified characters of a string.
    void
    applyFont(short fontIndex)
    Applies the specified font to the entire string.
    void
    applyFont(Font font)
    Sets the font of the entire string.
    void
    clearFormatting()
    Removes any formatting that may have been applied to the string.
    org.openxmlformats.schemas.spreadsheetml.x2006.main.CTRst
    getCTRst()
    Return the underlying xml bean
    XSSFFont
    getFontAtIndex(int index)
    Return a copy of the font in use at a particular index.
    XSSFFont
    getFontOfFormattingRun(int index)
    Gets a copy of the font used in a particular formatting run.
    int
    getIndexOfFormattingRun(int index)
    The index within the string to which the specified formatting run applies.
    int
    getLengthOfFormattingRun(int index)
    Returns the number of characters this format run covers.
    String
    getString()
    Returns the plain string representation.
    boolean
    hasFormatting()
    Does this string have any explicit formatting applied, or is it just text in the default style?
    int
    length()
    Returns the number of characters in this string.
    int
    numFormattingRuns()
     
    protected static void
    preserveSpaces(org.openxmlformats.schemas.officeDocument.x2006.sharedTypes.STXstring xs)
    Add the xml:spaces="preserve" attribute if the string has leading or trailing spaces
    void
    setString(String s)
    Removes any formatting and sets new string value
    protected void
    setStylesTableReference(StylesTable tbl)
     
    protected static org.openxmlformats.schemas.spreadsheetml.x2006.main.CTFont
    toCTFont(org.openxmlformats.schemas.spreadsheetml.x2006.main.CTRPrElt pr)
    CTRPrElt --> CTFont adapter
    String
    toString()
    Returns the plain string representation.
    static String
    utfDecode(String value)
    For all characters which cannot be represented in XML as defined by the XML 1.0 specification, the characters are escaped using the Unicode numerical character representation escape character format _xHHHH_, where H represents a hexadecimal character in the character's value.
    static String
    utfEncode(String value)
    Encodes a string so that it survives a round trip through utfDecode(String), using the _xHHHH_ escapes defined for ST_Xstring in the OOXML spec.

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • XSSFRichTextString

      public XSSFRichTextString(String str)
      Create a rich text string

    • XSSFRichTextString

      public XSSFRichTextString()
      Create empty rich text string and initialize it with empty string

    • XSSFRichTextString

      @Internal public XSSFRichTextString(org.openxmlformats.schemas.spreadsheetml.x2006.main.CTRst st)
      Create a rich text string from the supplied XML bean

  • Method Details

    • applyFont

      public void applyFont(int startIndex, int endIndex, short fontIndex)
      Applies a font to the specified characters of a string.
      Specified by:
      applyFont in interface RichTextString
      Parameters:
      startIndex - The start index to apply the font to (inclusive)
      endIndex - The end index to apply the font to (exclusive)
      fontIndex - The font to use.

    • applyFont

      public void applyFont(int startIndex, int endIndex, Font font)
      Applies a font to the specified characters of a string.
      Specified by:
      applyFont in interface RichTextString
      Parameters:
      startIndex - The start index to apply the font to (inclusive)
      endIndex - The end index to apply to font to (exclusive)
      font - The index of the font to use.

    • applyFont

      public void applyFont(Font font)
      Sets the font of the entire string.
      Specified by:
      applyFont in interface RichTextString
      Parameters:
      font - The font to use.

    • applyFont

      public void applyFont(short fontIndex)
      Applies the specified font to the entire string.
      Specified by:
      applyFont in interface RichTextString
      Parameters:
      fontIndex - the font to apply.

    • append

      public void append(String text, XSSFFont font)
      Append new text to this text run and apply the specify font to it
      Parameters:
      text - the text to append
      font - the font to apply to the appended text or null if no formatting is required

    • append

      public void append(String text)
      Append new text to this text run
      Parameters:
      text - the text to append

    • hasFormatting

      public boolean hasFormatting()
      Does this string have any explicit formatting applied, or is it just text in the default style?

    • clearFormatting

      public void clearFormatting()
      Removes any formatting that may have been applied to the string.
      Specified by:
      clearFormatting in interface RichTextString

    • getIndexOfFormattingRun

      public int getIndexOfFormattingRun(int index)
      The index within the string to which the specified formatting run applies.
      Specified by:
      getIndexOfFormattingRun in interface RichTextString
      Parameters:
      index - the index of the formatting run
      Returns:
      the index within the string.

    • getLengthOfFormattingRun

      public int getLengthOfFormattingRun(int index)
      Returns the number of characters this format run covers.
      Parameters:
      index - the index of the formatting run
      Returns:
      the number of characters this format run covers

    • getString

      public String getString()
      Returns the plain string representation.
      Specified by:
      getString in interface RichTextString
      Returns:
      The string representation of this RichText string, null if there is no data at all

    • setString

      public void setString(String s)
      Removes any formatting and sets new string value
      Parameters:
      s - new string value

    • toString

      public String toString()
      Returns the plain string representation.
      Overrides:
      toString in class Object
      Returns:
      The string representation of this RichText string, never null

    • length

      public int length()
      Returns the number of characters in this string.
      Specified by:
      length in interface RichTextString
      Returns:
      the number of characters in the font.

    • numFormattingRuns

      public int numFormattingRuns()
      Specified by:
      numFormattingRuns in interface RichTextString
      Returns:
      The number of formatting runs used.

    • getFontOfFormattingRun

      public XSSFFont getFontOfFormattingRun(int index)
      Gets a copy of the font used in a particular formatting run.
      Parameters:
      index - the index of the formatting run
      Returns:
      A copy of the font used or null if no formatting is applied to the specified text run.

    • getFontAtIndex

      public XSSFFont getFontAtIndex(int index)
      Return a copy of the font in use at a particular index.
      Parameters:
      index - The index.
      Returns:
      A copy of the font that's currently being applied at that index or null if no font is being applied or the index is out of range.

    • getCTRst

      @Internal public org.openxmlformats.schemas.spreadsheetml.x2006.main.CTRst getCTRst()
      Return the underlying xml bean

    • setStylesTableReference

      protected void setStylesTableReference(StylesTable tbl)

    • toCTFont

      protected static org.openxmlformats.schemas.spreadsheetml.x2006.main.CTFont toCTFont(org.openxmlformats.schemas.spreadsheetml.x2006.main.CTRPrElt pr)
      CTRPrElt --> CTFont adapter

    • preserveSpaces

      protected static void preserveSpaces(org.openxmlformats.schemas.officeDocument.x2006.sharedTypes.STXstring xs)
      Add the xml:spaces="preserve" attribute if the string has leading or trailing spaces
      Parameters:
      xs - the string to check

    • utfDecode

      public static String utfDecode(String value)
      For all characters which cannot be represented in XML as defined by the XML 1.0 specification, the characters are escaped using the Unicode numerical character representation escape character format _xHHHH_, where H represents a hexadecimal character in the character's value.

      Example: The Unicode character 0D is invalid in an XML 1.0 document, so it shall be escaped as _x000D_.

      See section 3.18.9 in the OOXML spec.
      Parameters:
      value - the string to decode
      Returns:
      the decoded string or null if the input string is null
      Since:
      6.0.0
      See Also:

    • utfEncode

      public static String utfEncode(String value)
      Encodes a string so that it survives a round trip through utfDecode(String), using the _xHHHH_ escapes defined for ST_Xstring in the OOXML spec.
      • The leading underscore of literal text that would otherwise be read as a _xHHHH_ escape is written as _x005F_, as Excel does, e.g. _x0041_ becomes _x005F_x0041_.
      • Characters that cannot be represented in XML 1.0 (control characters other than tab, line feed and carriage return, and U+FFFE/U+FFFF) are escaped, e.g. U+0001 becomes _x0001_.
      Parameters:
      value - the string to encode
      Returns:
      the encoded string or null if the input string is null
      Since:
      6.0.0
      See Also: