Package ghidra.util

# Class HTMLUtilities

java.lang.Object
ghidra.util.HTMLUtilities

public class HTMLUtilities extends Object
A helper class providing static methods for formatting text with common HTML tags.

Many clients use this class to render content as HTML. Below are a few use cases along with the method that should be used for each.

Use Case | Function | Description
--- | --- | ---
A client wishes to display a simple text message (that itself contains no HTML markup) as HTML. The message may contain newline characters. | `toHTML(String)` | The given text has all newline characters (\n) replaced with <BR> tags so that the HTML display of the text will visually display multiple lines. Also, the final text is prepended with <HTML> so that the Java HTML rendering engine will render the result as HTML.
A client wishes to display a simple text message (that itself may or may not contain HTML markup) as HTML. Further, the client wishes to not only split lines at newline characters, but also wishes to ensure that no line is longer than a specified limit. | `toWrappedHTML(String)` or `toWrappedHTML(String, int)` | This text works the same as `toHTML(String)` with the addition of line-wrapping text that passes the given cutoff.
A client wishes to display a text message with dynamic content, unknown at the time of programming. | `toLiteralHTML(String, int)` | This method works the same as `toWrappedHTML(String)`, with the addition of 'friendly encoding', or escaping, any embedded HTML content. The effect of this is that any existing HTML markup is not rendered as HTML, but is displayed as plain text.
A client wishes to display, as a tooltip, a text message with dynamic content, unknown at the time of programming. Tooltips are unique from general HTML in that we want them to share a common line wrapping length. | `toLiteralHTMLForTooltip(String)` | This method works the same as `toLiteralHTML(String, int)`, with the addition of capping the max text length, as well as setting the line-wrap length to `DEFAULT_MAX_LINE_LENGTH`.
A client wishes to convert newlines in text into HTML line breaks, without adding HTML tags around the text, which allows them to embed this text into a larger HTML document. | `lineWrapWithHTMLLineBreaks(String)` or `lineWrapWithHTMLLineBreaks(String, int)` | This first method will simply convert all newline characters to <BR> tags. The second method adds the ability to trigger line-wrapping at the given length as well.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `BR`
  `static final String`
  `HTML`
  `static final String`
  `HTML_CLOSE`
  `static String`
  `HTML_NEW_LINE`
  `static String`
  `HTML_SPACE`
  `static final String`
  `LINK_PLACEHOLDER_CLOSE`
  `static final String`
  `LINK_PLACEHOLDER_OPEN`
  `static final String`
  `PRE`
  `static final String`
  `PRE_CLOSE`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `HTMLUtilities()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static String`
  `bold(String text)`
  Surrounds the specified text with the HTML begin and end tags for bold.
  `static boolean`
  `charNeedsHTMLEscaping(int codePoint)`
  Tests a unicode code point (i.e., 32 bit character) to see if it needs to be escaped before being added to a HTML document because it is non-printable or a non-standard control character
  `static String`
  `colorString(Color color, String text)`
  Surrounds the indicated text with HTML font coloring tags so that the text will display in color within HTML.
  `static String`
  `colorString(String rgbColor, int value)`
  Surrounds the indicated numeric value with HTML font coloring tags so that the numeric value will display in color within HTML.
  `static String`
  `colorString(String rgbColor, String text)`
  Surrounds the indicated text with HTML font coloring tags so that the text will display in color within HTML.
  `static String`
  `convertLinkPlaceholdersToHyperlinks(String text)`
  Takes HTML text wrapped by `wrapWithLinkPlaceholder(String, String)` and replaces the custom link comment tags with HTML anchor (`A`) tags, where the `HREF` value is the value that was in the `CONTENT` attribute.
  `static String`
  `escapeHTML(String text)`
  Escapes any HTML special characters in the specified text.
  `static String`
  `friendlyEncodeHTML(String text)`
  Converts any special or reserved characters in the specified string into HTML-escaped entities.
  `static String`
  `friendlyEncodeHTML(String text, boolean skipLeadingWhitespace)`
  See `friendlyEncodeHTML(String)`
  `static String`
  `fromHTML(String text)`
  Checks the given string to see it is HTML, according to `BasicHTML` and then will return the text without any markup tags if it is.
  `static boolean`
  `isHTML(String text)`
  Returns true if the given text is HTML.
  `static boolean`
  `isUnbreakableHTML(String text)`
  Returns true if the text cannot be broken into lines due to the usage of particular HTML constructs.
  `static String`
  `italic(String text)`
  Surrounds the specified text with the HTML begin and end tags for italic.
  `static String`
  `lineWrapWithHTMLLineBreaks(String text)`
  This is just a convenience call to `lineWrapWithHTMLLineBreaks(String, int)` with a max line length of 0, which signals to not to wrap on line length, but only on newline characters.
  `static String`
  `lineWrapWithHTMLLineBreaks(String text, int maxLineLength)`
  Replaces all newline characters with HTML <BR> tags.
  `static String`
  `setFont(String text, Color color, int ptSize)`
  Sets the font size and color of the given text by wrapping it in <font> tags.
  `static String`
  `setFontSize(String text, int ptSize)`
  Sets the font size of the given text by wrapping it in <font> tags.
  `static String`
  `spaces(int num)`
  Creates a string with the indicated number of HTML space characters (`&nbsp;`).
  `static String`
  `toHexString(Color color)`
  Returns a color string of the format #RRGGBB.
  `static String`
  `toHTML(String text)`
  Convert the given string to HTML by adding the HTML tag and replacing new line chars with HTML <BR> tags.
  `static String`
  `toLiteralHTML(String text, int maxLineLength)`
  A convenience method to split the given HTML into lines, based on the given length, and then to `friendlyEncodeHTML(String)` the text.
  `static String`
  `toLiteralHTMLForTooltip(String text)`
  A very specific method that will: Make sure the HTML length is clipped to a reasonable size Escape any embedded HTML (so that it is not interpreted as HTML) Put the entire result in HTML
  `static String`
  `toRGBString(Color color)`
  Returns a color string of the format rrrgggbbb.
  `static String`
  `toWrappedHTML(String text)`
  This is just a convenience method to call `toWrappedHTML(String, int)` with a max line length of 75.
  `static String`
  `toWrappedHTML(String text, int maxLineLength)`
  Similar to `toHTML(String)` in that it will wrap the given text in HTML tags and split the content into multiple lines.
  `static String`
  `underline(String text)`
  Surrounds the specified text with the HTML begin and end tags for underlined text.
  `static String`
  `wrapAsHTML(String text)`
  Marks the given text as HTML in order to be rendered thusly by Java widgets.
  `static String`
  `wrapWithLinkPlaceholder(String htmlText, String content)`
  Returns the given text wrapped in `LINK_PLACEHOLDER_OPEN` and close tags.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Field Details

  - ### HTML

    public static final String HTML
    See Also:
      - Constant Field Values

  - ### HTML_CLOSE

    public static final String HTML_CLOSE
    See Also:
      - Constant Field Values

  - ### BR

    public static final String BR
    See Also:
      - Constant Field Values

  - ### PRE

    public static final String PRE
    See Also:
      - Constant Field Values

  - ### PRE_CLOSE

    public static final String PRE_CLOSE
    See Also:
      - Constant Field Values

  - ### LINK_PLACEHOLDER_OPEN

    public static final String LINK_PLACEHOLDER_OPEN
    See Also:
      - Constant Field Values

  - ### LINK_PLACEHOLDER_CLOSE

    public static final String LINK_PLACEHOLDER_CLOSE
    See Also:
      - Constant Field Values

  - ### HTML_SPACE

    public static String HTML_SPACE

  - ### HTML_NEW_LINE

    public static String HTML_NEW_LINE

- ## Constructor Details

  - ### HTMLUtilities

    public HTMLUtilities()

- ## Method Details

  - ### wrapAsHTML

    public static String wrapAsHTML(String text)
    Marks the given text as HTML in order to be rendered thusly by Java widgets.
    Parameters:
      `text` - the original text
    Returns:
      the text marked as HTML

  - ### colorString

    public static String colorString(Color color, String text)
    Surrounds the indicated text with HTML font coloring tags so that the text will display in color within HTML. The given color will be converted to its hex value.
    Parameters:
      `color` - The Java color object to use
      `text` - the original text
    Returns:
      the string for HTML colored text

  - ### colorString

    public static String colorString(String rgbColor, String text)
    Surrounds the indicated text with HTML font coloring tags so that the text will display in color within HTML.
    Parameters:
      `rgbColor` - (eg. "#8c0000") a string indicating the RGB hexadecimal color
      `text` - the original text
    Returns:
      the string for HTML colored text

  - ### colorString

    public static String colorString(String rgbColor, int value)
    Surrounds the indicated numeric value with HTML font coloring tags so that the numeric value will display in color within HTML.
    Parameters:
      `rgbColor` - (eg. "#8c0000") a string indicating the RGB hexadecimal color
      `value` - the numeric value to be converted to text and wrapped with color tags.
    Returns:
      the string for the HTML colored number

  - ### spaces

    public static String spaces(int num)
    Creates a string with the indicated number of HTML space characters (`&nbsp;`).
    Parameters:
      `num` - the number of HTML spaces
    Returns:
      the string o HTML spaces

  - ### bold

    public static String bold(String text)
    Surrounds the specified text with the HTML begin and end tags for bold.
    Parameters:
      `text` - the original text
    Returns:
      the text with the bold HTML tags

  - ### underline

    public static String underline(String text)
    Surrounds the specified text with the HTML begin and end tags for underlined text.
    Parameters:
      `text` - the original text
    Returns:
      the text with the underline HTML tags

  - ### italic

    public static String italic(String text)
    Surrounds the specified text with the HTML begin and end tags for italic.
    Parameters:
      `text` - the original text
    Returns:
      the text with the italic HTML tags

  - ### isHTML

    public static boolean isHTML(String text)
    Returns true if the given text is HTML. For this to be true, the text must begin with the <HTML> tag.
    Parameters:
      `text` - the text to check
    Returns:
      true if the given text is HTML

  - ### isUnbreakableHTML

    public static boolean isUnbreakableHTML(String text)
    Returns true if the text cannot be broken into lines due to the usage of particular HTML constructs.
    Parameters:
      `text` - the text to check
    Returns:
      true if the text cannot be correctly broken into lines

  - ### setFontSize

    public static String setFontSize(String text, int ptSize)
    Sets the font size of the given text by wrapping it in <font> tags.
    Parameters:
      `text` - the text to size
      `ptSize` - the point size of the text
    Returns:
      the updated String

  - ### setFont

    public static String setFont(String text, Color color, int ptSize)
    Sets the font size and color of the given text by wrapping it in <font> tags.
    Parameters:
      `text` - the text to size
      `color` - the color of the text
      `ptSize` - the point size of the text
    Returns:
      the updated String

  - ### wrapWithLinkPlaceholder

    public static String wrapWithLinkPlaceholder(String htmlText, String content)
    Returns the given text wrapped in `LINK_PLACEHOLDER_OPEN` and close tags. If `foo` is passed for the HTML text, with a content value of `123456`, then the output will look like:

                <!-- LINK CONTENT="123456" -->foo<!-- /LINK -->

    Parameters:
      `htmlText` - the HTML text to wrap
      `content` - the value that will be put into the `CONTENT` section of the generated HTML. This can later be retrieved by clients transforming this text.
    Returns:
      the wrapped text

  - ### convertLinkPlaceholdersToHyperlinks

    public static String convertLinkPlaceholdersToHyperlinks(String text)
    Takes HTML text wrapped by `wrapWithLinkPlaceholder(String, String)` and replaces the custom link comment tags with HTML anchor (`A`) tags, where the `HREF` value is the value that was in the `CONTENT` attribute.
    Parameters:
      `text` - the text for which to replace the markup
    Returns:
      the updated text

  - ### toHTML

    public static String toHTML(String text)
    Convert the given string to HTML by adding the HTML tag and replacing new line chars with HTML <BR> tags.
    Parameters:
      `text` - The text to convert to HTML
    Returns:
      the converted text

  - ### toWrappedHTML

    public static String toWrappedHTML(String text)
    This is just a convenience method to call `toWrappedHTML(String, int)` with a max line length of 75.
    Parameters:
      `text` - The text to convert
    Returns:
      converted text

  - ### toWrappedHTML

    public static String toWrappedHTML(String text, int maxLineLength)
    Similar to `toHTML(String)` in that it will wrap the given text in HTML tags and split the content into multiple lines. The difference is that this method will split lines that pass the given maximum length and on `'\n'` characters. Alternatively, `toHTML(String)` will only split the given text on `'\n'` characters.
    Parameters:
      `text` - The text to convert
      `maxLineLength` - The maximum number of characters that should appear in a line; 0 signals not to wrap the line based upon length
    Returns:
      converted text

  - ### toLiteralHTMLForTooltip

    public static String toLiteralHTMLForTooltip(String text)
    A very specific method that will:
    1. Make sure the HTML length is clipped to a reasonable size
    2. Escape any embedded HTML (so that it is not interpreted as HTML)
    3. Put the entire result in HTML
    Parameters:
      `text` - the text to convert
    Returns:
      the converted value.

  - ### friendlyEncodeHTML

    public static String friendlyEncodeHTML(String text)
    Converts any special or reserved characters in the specified string into HTML-escaped entities. Use this method when you have content containing HTML that you do not want interpreted as HTML, such as when displaying text that uses angle brackets around words.

    For example, consider the following

    Input | Output | Rendered as | (Without Friendly Encoding)
    --- | --- | --- | ---
    Hi <b>mom </b> | Hi &nbsp;&lt;b&gt;mom &nbsp;&lt;/b&gt; | Hi <b>mom </b> | Hi mom

    Parameters:
      `text` - string to be encoded
    Returns:
      the encoded HTML string

  - ### friendlyEncodeHTML

    public static String friendlyEncodeHTML(String text, boolean skipLeadingWhitespace)
    See `friendlyEncodeHTML(String)`
    Parameters:
      `text` - string to be encoded
      `skipLeadingWhitespace` - true signals to ignore any leading whitespace characters. This is useful when line wrapping to force wrapped lines to the left
    Returns:
      the encoded HTML string

  - ### escapeHTML

    public static String escapeHTML(String text)
    Escapes any HTML special characters in the specified text.

    Does not otherwise modify the input text or wrap lines.

    Calling this twice will result in text being double-escaped, which will not display correctly.

    See also `StringEscapeUtils#escapeHtml3(String)` if you need quote-safe html encoding.

    Parameters:
      `text` - plain-text that might have some characters that should NOT be interpreted as HTML
    Returns:
      string with any html characters replaced with equivalents

  - ### charNeedsHTMLEscaping

    public static boolean charNeedsHTMLEscaping(int codePoint)
    Tests a unicode code point (i.e., 32 bit character) to see if it needs to be escaped before being added to a HTML document because it is non-printable or a non-standard control character
    Parameters:
      `codePoint` - character to test
    Returns:
      boolean true if character should be escaped

  - ### toLiteralHTML

    public static String toLiteralHTML(String text, int maxLineLength)
    A convenience method to split the given HTML into lines, based on the given length, and then to `friendlyEncodeHTML(String)` the text.

    This method preserves all whitespace between line breaks.

    Note: This method is not intended to handle text that already contains entity escaped text. The result will not render correctly as HTML.

    Parameters:
      `text` - the text to update
      `maxLineLength` - the max line length upon which to wrap; 0 for no max length
    Returns:
      the updated text

  - ### lineWrapWithHTMLLineBreaks

    public static String lineWrapWithHTMLLineBreaks(String text)
    This is just a convenience call to `lineWrapWithHTMLLineBreaks(String, int)` with a max line length of 0, which signals to not to wrap on line length, but only on newline characters.
    Parameters:
      `text` - the text to wrap
    Returns:
      the updated text
    See Also:
      - `lineWrapWithHTMLLineBreaks(String, int)`

  - ### lineWrapWithHTMLLineBreaks

    public static String lineWrapWithHTMLLineBreaks(String text, int maxLineLength)
    Replaces all newline characters with HTML <BR> tags.

    Unlike `toWrappedHTML(String)`, this method does not add the <HTML> tag to the given text.

    Call this method when you wish to create your own HTML content, with parts of that content line wrapped.

    Parameters:
      `text` - the text to wrap
      `maxLineLength` - the max length of the line; 0 if no max is desired
    Returns:
      the updated text

  - ### fromHTML

    public static String fromHTML(String text)
    Checks the given string to see it is HTML, according to `BasicHTML` and then will return the text without any markup tags if it is.
    Parameters:
      `text` - the text to convert
    Returns:
      the converted String

  - ### toRGBString

    public static String toRGBString(Color color)
    Returns a color string of the format rrrgggbbb. As an example, `Color.RED` would be returned as 255000000 (the values are padded with 0s to make to fill up 3 digits per component).
    Parameters:
      `color` - The color to convert.
    Returns:
      a string of the format rrrgggbbb.

  - ### toHexString

    public static String toHexString(Color color)
    Returns a color string of the format #RRGGBB. As an example, `Color.RED` would be returned as #FF0000 (the values are padded with 0s to make to fill up 2 digits per component).
    Parameters:
      `color` - The color to convert.
    Returns:
      a string of the format #RRGGBB.