Package org.apache.poi.hssf.usermodel

Class HSSFRichTextString

  • All Implemented Interfaces:
    java.lang.Comparable<HSSFRichTextString>, RichTextString
    public final class HSSFRichTextString
extends java.lang.Object
implements java.lang.Comparable<HSSFRichTextString>, 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

      Fields 
      Modifier and Type Field Description
      static short NO_FONT
      Place holder for indicating that NO_FONT has been applied here

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      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.
      int compareTo​(HSSFRichTextString r)
      Compares one rich text string to another.
      boolean equals​(java.lang.Object o)  
      short getFontAtIndex​(int index)
      Returns the font in use at a particular index.
      short getFontOfFormattingRun​(int index)
      Gets the font used in a particular formatting run.
      int getIndexOfFormattingRun​(int index)
      The index within the string to which the specified formatting run applies.
      java.lang.String getString()
      Returns the plain string representation.
      int hashCode()  
      int length()  
      int numFormattingRuns()  
      java.lang.String toString()  

      • Methods inherited from class java.lang.Object

        getClass, notify, notifyAll, wait, wait, wait

    • Field Detail

      • NO_FONT

        public static final short NO_FONT
        Place holder for indicating that NO_FONT has been applied here
        See Also:
        Constant Field Values

    • Constructor Detail

      • HSSFRichTextString

        public HSSFRichTextString()

      • HSSFRichTextString

        public HSSFRichTextString​(java.lang.String string)

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

      • clearFormatting

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

      • getString

        public java.lang.String getString()
        Returns the plain string representation.
        Specified by:
        getString in interface RichTextString

      • length

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

      • getFontAtIndex

        public short getFontAtIndex​(int index)
        Returns the font in use at a particular index.
        Parameters:
        index - The index.
        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.

      • numFormattingRuns

        public int numFormattingRuns()
        Specified by:
        numFormattingRuns in interface RichTextString
        Returns:
        The number of formatting runs used. There will always be at least one of font NO_FONT.
        See Also:
        NO_FONT

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

      • getFontOfFormattingRun

        public short getFontOfFormattingRun​(int index)
        Gets the font used in a particular formatting run.
        Parameters:
        index - the index of the formatting run
        Returns:
        the font number used.

      • compareTo

        public int compareTo​(HSSFRichTextString r)
        Compares one rich text string to another.
        Specified by:
        compareTo in interface java.lang.Comparable<HSSFRichTextString>

      • equals

        public boolean equals​(java.lang.Object o)
        Overrides:
        equals in class java.lang.Object

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object
        Returns:
        the plain text representation of this string.

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