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 java.lang.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(java.lang.String str)	Create a rich text string
XSSFRichTextString(CTRst st)	Create a rich text string from the supplied XML bean

Method Summary

Modifier and Type	Method	Description
void	append(java.lang.String text)	Append new text to this text run
void	append(java.lang.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.
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.
java.lang.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()
void	setString(java.lang.String s)	Removes any formatting and sets new string value
java.lang.String	toString()	Returns the plain string representation.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

XSSFRichTextString

public XSSFRichTextString(java.lang.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(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(java.lang.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(java.lang.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 java.lang.String getString()

Returns the plain string representation.

Specified by:

getString in interface RichTextString

setString

public void setString(java.lang.String s)

Removes any formatting and sets new string value

Parameters:

s - new string value

toString

public java.lang.String toString()

Returns the plain string representation.

Overrides:

toString in class java.lang.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(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 CTRst getCTRst()

Return the underlying xml bean