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

  • Field Details

  • 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 - (e.g., "#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 - (e.g., "#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 of 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 <span> 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 <span> tags.
      Parameters:
      text - the text to size
      color - the color of the text
      ptSize - the point size of the text
      Returns:
      the updated String

    • styleText

      public static String styleText(SimpleAttributeSet attributes, String text)
      Escapes and wraps the given text in SPAN tag with font attributes specified in the given attributes. Specifically, these attributes are used:

      See GAttributes for a convenient way to create the correct attributes for a font and color.

      Parameters:
      attributes - the attributes
      text - the content to style
      Returns:
      the styled content
      See Also:

    • 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

      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

    • 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, boolean makeSpacesNonBreaking)
      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
      makeSpacesNonBreaking - true to convert spaces into "&nbsp;"
      Returns:
      string with any html characters replaced with equivalents

    • escapeHTML

      public static String escapeHTML(String text)
      Escapes any HTML special characters in the specified text.
      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
      See Also:

    • 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

      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.