org.apache.poi.hssf.usermodel

## Class HSSFRichTextString

- java.lang.Object
- - org.apache.poi.hssf.usermodel.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 and Description
    --- | ---
    `static short` | `NO_FONT` Place holder for indicating that NO_FONT has been applied here

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `HSSFRichTextString()`
    `HSSFRichTextString(java.lang.String string)`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `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.
    `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

      `clone, finalize, 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.

Copyright 2020 The Apache Software Foundation or its licensors, as applicable.