Top Description Fields Constructors Methods
org.apache.poi.hssf.usermodel

public final Class HSSFRichTextString

extends Object
implements Comparable<HSSFRichTextString>, RichTextString
Class Inheritance
All Implemented Interfaces
org.apache.poi.ss.usermodel.RichTextString, java.lang.Comparable
Imports
java.util.Iterator, org.apache.poi.hssf.model.InternalWorkbook, org.apache.poi.hssf.record.LabelSSTRecord, org.apache.poi.hssf.record.common.FormatRun, .UnicodeString, org.apache.poi.ss.usermodel.Font, .RichTextString
Rich text unicode string. These strings can have fonts applied to arbitary parts of the string.

Note, that in certain cases creating too many HSSFRichTextString cells may cause Excel 2003 and lower to crash when changing the color of the cells and then saving the Excel file. Compare two snippets that produce equivalent output: 

HSSFCell hssfCell = row.createCell(idx);
 //rich text consists of two runs
 HSSFRichTextString richString = new HSSFRichTextString( "Hello, World!" );
 richString.applyFont( 0, 6, font1 );
 richString.applyFont( 6, 13, font2 );
 hssfCell.setCellValue( richString );
and 
//create a cell style and assign the first font to it
 HSSFCellStyle style = workbook.createCellStyle();
 style.setFont(font1);

 HSSFCell hssfCell = row.createCell(idx);
 hssfCell.setCellStyle(style);

 //rich text consists of one run overriding the cell style
 HSSFRichTextString richString = new HSSFRichTextString( "Hello, World!" );
 richString.applyFont( 6, 13, font2 );
 hssfCell.setCellValue( richString );

Excel always uses the latter approach: for a reach text containing N runs Excel saves the font of the first run in the cell's style and subsequent N-1 runs override this font.

For more information regarding this behavior please consult Bugzilla 47543: https://issues.apache.org/bugzilla/show_bug.cgi?id=47543

Field Summary

Modifier and TypeField and Description
private InternalWorkbook
_book

private LabelSSTRecord
_record

private UnicodeString
_string

public static final short
NO_FONT

Place holder for indicating that NO_FONT has been applied here

Constructor Summary

AccessConstructor and Description
public
HSSFRichTextString()

public
HSSFRichTextString(String string)

pack-priv
HSSFRichTextString(InternalWorkbook book, LabelSSTRecord record)

Method Summary

Modifier and TypeMethod and Description
private void
addToSSTIfRequired()

public void
applyFont(int
The start index to apply the font to (inclusive)
startIndex, int
The end index to apply the font to (exclusive)
endIndex, short
The font to use.
fontIndex)

Implements org.apache.poi.ss.usermodel.RichTextString.applyFont.

Applies a font to the specified characters of a string.

public void
applyFont(int
The start index to apply the font to (inclusive)
startIndex, int
The end index to apply to font to (exclusive)
endIndex, Font
The index of the font to use.
font)

Implements org.apache.poi.ss.usermodel.RichTextString.applyFont.

Applies a font to the specified characters of a string.

public void
applyFont(Font
The font to use.
font)

Implements org.apache.poi.ss.usermodel.RichTextString.applyFont.

Sets the font of the entire string.

public void
applyFont(short
the font to apply.
fontIndex)

Implements org.apache.poi.ss.usermodel.RichTextString.applyFont.

Applies the specified font to the entire string.

public void
clearFormatting()

Implements org.apache.poi.ss.usermodel.RichTextString.clearFormatting.

Removes any formatting that may have been applied to the string.

private UnicodeString
cloneStringIfRequired()

Called whenever the unicode string is modified.

public int
compareTo(HSSFRichTextString
the object to be compared.
r)

Implements java.lang.Comparable.compareTo.

Compares one rich text string to another.

public boolean
equals(Object
the reference object with which to compare.
o)

Overrides java.lang.Object.equals.

Indicates whether some other object is "equal to" this one.

public short

Returns:

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.
getFontAtIndex(int
The index.
index)

Returns the font in use at a particular index.

public short

Returns:

the font number used.
getFontOfFormattingRun(int
the index of the formatting run
index)

Gets the font used in a particular formatting run.

public int

Returns:

the index within the string.
getIndexOfFormattingRun(int
the index of the formatting run
index)

Implements org.apache.poi.ss.usermodel.RichTextString.getIndexOfFormattingRun.

The index within the string to which the specified formatting run applies.

pack-priv UnicodeString
getRawUnicodeString()

Returns the raw, probably shared Unicode String.

public String
getString()

Implements org.apache.poi.ss.usermodel.RichTextString.getString.

Returns the plain string representation.

pack-priv UnicodeString
getUnicodeString()

Used internally by the HSSFCell to get the internal string value.

public int
hashCode()

Overrides java.lang.Object.hashCode.

Returns a hash code value for this object.

public int

Returns:

the number of characters in the text.
length()

Implements org.apache.poi.ss.usermodel.RichTextString.length.

public int

Returns:

The number of formatting runs used. There will always be at least one of font NO_FONT.
numFormattingRuns()

Implements org.apache.poi.ss.usermodel.RichTextString.numFormattingRuns.

pack-priv void
setUnicodeString(UnicodeString str)

Used internally by the HSSFCell to set the internal string value

pack-priv void
setWorkbookReferences(InternalWorkbook book, LabelSSTRecord record)

This must be called to setup the internal work book references whenever a RichTextString is added to a cell

public String

Returns:

the plain text representation of this string.
toString()

Overrides java.lang.Object.toString.

Returns a string representation of the object.

Inherited from java.lang.Object:
clonefinalizegetClassnotifynotifyAllwaitwaitwait

Field Detail

_bookback to summary
private InternalWorkbook _book
_recordback to summary
private LabelSSTRecord _record
_stringback to summary
private UnicodeString _string
NO_FONTback to summary
public static final short NO_FONT

Place holder for indicating that NO_FONT has been applied here

Constructor Detail

HSSFRichTextStringback to summary
public HSSFRichTextString()
HSSFRichTextStringback to summary
public HSSFRichTextString(String string)
HSSFRichTextStringback to summary
pack-priv HSSFRichTextString(InternalWorkbook book, LabelSSTRecord record)

Method Detail

addToSSTIfRequiredback to summary
private void addToSSTIfRequired()
applyFontback to summary
public void applyFont(int startIndex, int endIndex, short fontIndex)

Implements org.apache.poi.ss.usermodel.RichTextString.applyFont.

Applies a font to the specified characters of a string.

Parameters
startIndex:int

The start index to apply the font to (inclusive)

endIndex:int

The end index to apply the font to (exclusive)

fontIndex:short

The font to use.

Annotations
@Override
applyFontback to summary
public void applyFont(int startIndex, int endIndex, Font font)

Implements org.apache.poi.ss.usermodel.RichTextString.applyFont.

Applies a font to the specified characters of a string.

Parameters
startIndex:int

The start index to apply the font to (inclusive)

endIndex:int

The end index to apply to font to (exclusive)

font:Font

The index of the font to use.

Annotations
@Override
applyFontback to summary
public void applyFont(Font font)

Implements org.apache.poi.ss.usermodel.RichTextString.applyFont.

Sets the font of the entire string.

Parameters
font:Font

The font to use.

Annotations
@Override
applyFontback to summary
public void applyFont(short fontIndex)

Implements org.apache.poi.ss.usermodel.RichTextString.applyFont.

Applies the specified font to the entire string.

Parameters
fontIndex:short

the font to apply.

Annotations
@Override
clearFormattingback to summary
public void clearFormatting()

Implements org.apache.poi.ss.usermodel.RichTextString.clearFormatting.

Removes any formatting that may have been applied to the string.

Annotations
@Override
cloneStringIfRequiredback to summary
private UnicodeString cloneStringIfRequired()

Called whenever the unicode string is modified. When it is modified we need to create a new SST index, so that other LabelSSTRecords will not be affected by changes that we make to this string.

compareToback to summary
public int compareTo(HSSFRichTextString r)

Implements java.lang.Comparable.compareTo.

Compares one rich text string to another.

Parameters
r:HSSFRichTextString

Doc from java.lang.Comparable.compareTo.

the object to be compared.

Returns:int

Doc from java.lang.Comparable.compareTo.

a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object.

Annotations
@Override
equalsback to summary
public boolean equals(Object o)

Overrides java.lang.Object.equals.

Doc from java.lang.Object.equals.

Indicates whether some other object is "equal to" this one.

The equals method implements an equivalence relation on non-null object references:

  • It is reflexive: for any non-null reference value x, x.equals(x) should return true.
  • It is symmetric: for any non-null reference values x and y, x.equals(y) should return true if and only if y.equals(x) returns true.
  • It is transitive: for any non-null reference values x, y, and z, if x.equals(y) returns true and y.equals(z) returns true, then x.equals(z) should return true.
  • It is consistent: for any non-null reference values x and y, multiple invocations of x.equals(y) consistently return true or consistently return false, provided no information used in equals comparisons on the objects is modified.
  • For any non-null reference value x, x.equals(null) should return false.

An equivalence relation partitions the elements it operates on into equivalence classes; all the members of an equivalence class are equal to each other. Members of an equivalence class are substitutable for each other, at least for some purposes.

Parameters
o:Object

the reference object with which to compare.

Returns:boolean

true if this object is the same as the obj argument; false otherwise.

Annotations
@Override
getFontAtIndexback to summary
public short getFontAtIndex(int index)

Returns the font in use at a particular index.

Parameters
index:int

The index.

Returns:short

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.

getFontOfFormattingRunback to summary
public short getFontOfFormattingRun(int index)

Gets the font used in a particular formatting run.

Parameters
index:int

the index of the formatting run

Returns:short

the font number used.

getIndexOfFormattingRunback to summary
public int getIndexOfFormattingRun(int index)

Implements org.apache.poi.ss.usermodel.RichTextString.getIndexOfFormattingRun.

The index within the string to which the specified formatting run applies.

Parameters
index:int

the index of the formatting run

Returns:int

the index within the string.

Annotations
@Override
getRawUnicodeStringback to summary
pack-priv UnicodeString getRawUnicodeString()

Returns the raw, probably shared Unicode String. Used when tweaking the styles, eg updating font positions. Changes to this string may well effect other RichTextStrings too!

getStringback to summary
public String getString()

Implements org.apache.poi.ss.usermodel.RichTextString.getString.

Returns the plain string representation.

Annotations
@Override
getUnicodeStringback to summary
pack-priv UnicodeString getUnicodeString()

Used internally by the HSSFCell to get the internal string value. Will ensure the string is not shared

hashCodeback to summary
public int hashCode()

Overrides java.lang.Object.hashCode.

Doc from java.lang.Object.hashCode.

Returns a hash code value for this object. This method is supported for the benefit of hash tables such as those provided by java.util.HashMap.

The general contract of hashCode is:

  • Whenever it is invoked on the same object more than once during an execution of a Java application, the hashCode method must consistently return the same integer, provided no information used in equals comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application.
  • If two objects are equal according to the equals method, then calling the hashCode method on each of the two objects must produce the same integer result.
  • It is not required that if two objects are unequal according to the equals method, then calling the hashCode method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hash tables.
Returns:int

a hash code value for this object

Annotations
@Override
lengthback to summary
public int length()

Implements org.apache.poi.ss.usermodel.RichTextString.length.

Returns:int

the number of characters in the text.

Annotations
@Override
numFormattingRunsback to summary
public int numFormattingRuns()

Implements org.apache.poi.ss.usermodel.RichTextString.numFormattingRuns.

Returns:int

The number of formatting runs used. There will always be at least one of font NO_FONT.

Annotations
@Override
See Also
NO_FONT
setUnicodeStringback to summary
pack-priv void setUnicodeString(UnicodeString str)

Used internally by the HSSFCell to set the internal string value

setWorkbookReferencesback to summary
pack-priv void setWorkbookReferences(InternalWorkbook book, LabelSSTRecord record)

This must be called to setup the internal work book references whenever a RichTextString is added to a cell

toStringback to summary
public String toString()

Overrides java.lang.Object.toString.

Doc from java.lang.Object.toString.

Returns a string representation of the object. Satisfying this method's contract implies a non-null result must be returned.

Returns:String

the plain text representation of this string.