XSSFRichTextString (Keikai Spreadsheet Build 5.0.0 API)

java.lang.Object
- org.zkoss.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);
 
```
Author:

Yegor Kozlov

Constructor Summary

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

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addRun(String text, XSSFFont font)`
`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(Font font)` Sets the font of the entire string.
`void`	`applyFont(int startIndex, int endIndex, Font font)` Applies a font to the specified characters of a string.
`void`	`applyFont(int startIndex, int endIndex, short fontIndex)` Applies a font to the specified characters of a string.
`void`	`applyFont(short fontIndex)` Applies the specified font to 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(XSSFWorkbook book, 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`	`getRawString()`
`String`	`getString()` Returns the plain string representation.
`String`	`getStringAt(int runIndex)` Returns the plain string representation of a run where _xHHHH_ is decoded to Java character already.
`int`	`length()` Returns the number of characters in this string.
`int`	`numFormattingRuns()`
`protected static void`	`preserveSpaces(org.openxmlformats.schemas.spreadsheetml.x2006.main.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`	`utfEncode(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.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Constructor Detail
  - 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
```
public XSSFRichTextString(org.openxmlformats.schemas.spreadsheetml.x2006.main.CTRst st)
```
    Create a rich text string from the supplied XML bean
- Method Detail
  - 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
  - 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
  - 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
  - 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(XSSFWorkbook book,
                                       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.spreadsheetml.x2006.main.STXstring xs)
```
    Add the xml:spaces="preserve" attribute if the string has leading or trailing spaces
    
    Parameters:
    
    xs - the string to check
  - getStringAt
```
public String getStringAt(int runIndex)
```
    Description copied from interface: RichTextString
    
    Returns the plain string representation of a run where _xHHHH_ is decoded to Java character already.
    
    Specified by:
    
    getStringAt in interface RichTextString
    
    Returns:
  - utfEncode
```
public static String utfEncode(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 encode
    
    Returns:
    
    the encoded string
    
    Since:
    
    3.9.10
  - getRawString
```
public String getRawString()
```
  - addRun
```
public void addRun(String text,
                   XSSFFont font)
```

Class XSSFRichTextString

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

XSSFRichTextString

XSSFRichTextString

XSSFRichTextString

Method Detail

applyFont

applyFont

applyFont

applyFont

append

append

clearFormatting

getIndexOfFormattingRun

getLengthOfFormattingRun

getString

setString

toString

length

numFormattingRuns

getFontOfFormattingRun

getFontAtIndex

getCTRst

setStylesTableReference

toCTFont

preserveSpaces

getStringAt

utfEncode

getRawString

addRun