Package ghidra.util

Class HTMLUtilities

  • public class HTMLUtilities
extends java.lang.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 CaseFunctionDescription
    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.

    • Constructor Summary

      Constructors 
      Constructor Description
      HTMLUtilities()  

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static java.lang.String bold​(java.lang.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 java.lang.String colorString​(java.awt.Color color, java.lang.String text)
      Surrounds the indicated text with HTML font coloring tags so that the text will display in color within HTML.
      static java.lang.String colorString​(java.lang.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 java.lang.String colorString​(java.lang.String rgbColor, java.lang.String text)
      Surrounds the indicated text with HTML font coloring tags so that the text will display in color within HTML.
      static java.lang.String convertLinkPlaceholdersToHyperlinks​(java.lang.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 java.lang.String escapeHTML​(java.lang.String text)
      Escapes any HTML special characters in the specified text.
      static java.lang.String friendlyEncodeHTML​(java.lang.String text)
      Converts any special or reserved characters in the specified string into HTML-escaped entities.
      static java.lang.String fromHTML​(java.lang.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​(java.lang.String text)
      Returns true if the given text is HTML.
      static java.lang.String italic​(java.lang.String text)
      Surrounds the specified text with the HTML begin and end tags for italic.
      static java.lang.String lineWrapWithHTMLLineBreaks​(java.lang.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 java.lang.String lineWrapWithHTMLLineBreaks​(java.lang.String text, int maxLineLength)
      Replaces all newline characters with HTML <BR> tags.
      static java.lang.String setFont​(java.lang.String text, java.awt.Color color, int ptSize)
      Sets the font size and color of the given text by wrapping it in <font> tags.
      static java.lang.String setFontSize​(java.lang.String text, int ptSize)
      Sets the font size of the given text by wrapping it in <font> tags.
      static java.lang.String spaces​(int num)
      Creates a string with the indicated number of HTML space characters (&nbsp;).
      static java.lang.String toHexString​(java.awt.Color color)
      Returns a color string of the format #RRGGBB.
      static java.lang.String toHTML​(java.lang.String text)
      Convert the given string to HTML by adding the HTML tag and replacing new line chars with HTML <BR> tags.
      static java.lang.String toLiteralHTML​(java.lang.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 java.lang.String toLiteralHTMLForTooltip​(java.lang.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 java.lang.String toRGBString​(java.awt.Color color)
      Returns a color string of the format rrrgggbbb.
      static java.lang.String toWrappedHTML​(java.lang.String text)
      This is just a convenience method to call toWrappedHTML(String, int) with a max line length of 75.
      static java.lang.String toWrappedHTML​(java.lang.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 java.lang.String underline​(java.lang.String text)
      Surrounds the specified text with the HTML begin and end tags for underlined text.
      static java.lang.String wrapAsHTML​(java.lang.String text)
      Marks the given text as HTML in order to be rendered thusly by Java widgets.
      static java.lang.String wrapWithLinkPlaceholder​(java.lang.String htmlText, java.lang.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

    • Constructor Detail

      • HTMLUtilities

        public HTMLUtilities()

    • Method Detail

      • wrapAsHTML

        public static java.lang.String wrapAsHTML​(java.lang.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 java.lang.String colorString​(java.awt.Color color,
                                           java.lang.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 java.lang.String colorString​(java.lang.String rgbColor,
                                           java.lang.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 java.lang.String colorString​(java.lang.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 java.lang.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 java.lang.String bold​(java.lang.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 java.lang.String underline​(java.lang.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 java.lang.String italic​(java.lang.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​(java.lang.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

      • setFontSize

        public static java.lang.String setFontSize​(java.lang.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 java.lang.String setFont​(java.lang.String text,
                                       java.awt.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 java.lang.String wrapWithLinkPlaceholder​(java.lang.String htmlText,
                                                       java.lang.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 java.lang.String convertLinkPlaceholdersToHyperlinks​(java.lang.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 java.lang.String toHTML​(java.lang.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 java.lang.String toWrappedHTML​(java.lang.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 java.lang.String toWrappedHTML​(java.lang.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 java.lang.String toLiteralHTMLForTooltip​(java.lang.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 java.lang.String friendlyEncodeHTML​(java.lang.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

        InputOutputRendered 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

      • escapeHTML

        public static java.lang.String escapeHTML​(java.lang.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 java.lang.String toLiteralHTML​(java.lang.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 java.lang.String lineWrapWithHTMLLineBreaks​(java.lang.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 java.lang.String lineWrapWithHTMLLineBreaks​(java.lang.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 java.lang.String fromHTML​(java.lang.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 java.lang.String toRGBString​(java.awt.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 java.lang.String toHexString​(java.awt.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.