org.openide.awt
Class HtmlRenderer

java.lang.Object
  org.openide.awt.HtmlRenderer

public final class HtmlRenderer

extends Object

A generic cell renderer class which implements a lightweight html renderer supporting a minimal subset of HTML used for markup purposes only - basic font styles, colors, etc. Also supports named logical colors specified by a preceding ! character for specifying colors that should be looked up in the current look and feel's UIDefaults (e.g. <font color=&!textText&>).

If you only need to paint some HTML quickly, use the static methods for painting - renderString, renderPlainString or renderHtml. These methods differ as follows:

• renderString will check the string for opening HTML tags (upper or lower but not mixed case) and call either renderPlainString or renderHtml as appropriate. Note this method does not tolerate whitespace in opening html tags - it expects exactly 6 characters to make up the opening tag if present.
• renderPlainString simply renders a string to the graphics context, takes the same agruments as renderHtml, but will also honor STYLE_TRUNCATE, so strings can be rendered with trailing elipsis if there is not enough space
• renderHtml renders whatever is passed to it as HTML, regardless of whether it has opening HTML tags or not. It can be used to render plain strings, but renderPlainString is faster for that. It is useful if you want to render a string you know to be compliant HTML markup, but which does not have opening and closing HTML tags (though they are harmless if present).

To reiterate: This is not a forgiving HTML parser - the HTML supplied must follow the guidelines documented here!

The following tags are supported, in upper or lower (but not mixed) case, with no excess whitespace in the tags:

<B>	Boldface text
<S>	Strikethrough text
<U>	Underline text
<I>	Italic text
<EM>	Emphasized text (same as italic)
<STRONG>	Strong text (same as bold)
<font>	Font color - font attributes other than color are not supported. Colors may be specified as hexidecimal strings, such as #FF0000 or as logical colors defined in the current look and feel by specifying a ! character as the first character of the color name. Logical colors are colors available from the current look and feel's UIManager. For example, <font color="!Tree.background"> will set the font color to the result of UIManager.getColor("Tree.background"). Font size tags are not supported.

The lightweight html renderer supports the following named sgml character entities: quot, lt, amp, lsquo, rsquo, ldquo, rdquo, ndash, mdash, ne, le, ge, copy, reg, trade. . It also supports numeric entities (e.g. &8822;).

Why not use the JDK's HTML support? The JDK's HTML support works well for stable components, but suffers from performance problems in the case of cell renderers - each call to set the text (which happens once per cell, per paint) causes a document tree to be created in memory. For small, markup only strings, this is a huge performance penalty. For rendering short strings (for example, in a tree or table cell renderer) with limited HTML, this method is approximately 10x faster than standard Swing HTML rendering.

Specifying logical colors
Hardcoded text colors are undesirable, as they can be incompatible (even invisible) on some look and feels or themes, depending on the background color. The lightweight HTML renderer supports a non-standard syntax for specifying font colors via a key for a color in the UI defaults for the current look and feel. This is accomplished by prefixing the key name with a ! character. For example: <font color='!controlShadow'>.

Modes of operation
This method supports two modes of operation:

1. STYLE_CLIP - as much text as will fit in the pixel width passed to the method should be painted, and the text should be cut off at the maximum width or clip rectangle maximum X boundary for the graphics object, whichever is smaller.
2. STYLE_TRUNCATE - paint as much text as will fit in the pixel width passed to the method, but paint the last three characters as .'s, in the same manner as a JLabel truncates its text when the available space is too small.

The paint methods can also be used in non-painting mode to establish the space necessary to paint a string. This is accomplished by passing the value of the paint argument as false. The return value will be the required width in pixels to display the text. Note that in order to retrieve an accurate value, the argument for available width should be passed as Integer.MAX_VALUE or an appropriate maximum size - otherwise the return value will either be the passed maximum width or the required width, whichever is smaller. Also, the clip shape for the passed graphics object should be null or a value larger than the maximum possible render size, or text size measurement will stop at the clip bounds. HtmlRenderer.getGraphics() will always return non-null and non-clipped, and is suitable to pass in such a situation.

Using the shared renderer instance
HtmlRenderer provides a simple cell renderer instance which can be used in trees, lists, tables, combo boxes, etc. The nested Renderer interface extends all of the appropriate interfaces (TreeCellRenderer, TableCellRenderer, ListCellRenderer), to make it easy to drop it into a table, tree, list, etc. If the objects you want to render do not return their display name from their toString() method, you may need a wrapper renderer class which will set the text appropriately before painting.

The Renderer interface has a reset() method, which resets all of the things that may have been altered (color, border, text alignment, icon, etc.). This is called whenever get[nnn]CellRenderer is called, to ensure that its previous use in one component does not affect its appearance in another.

When get[nnn]CellRenderer is called, the renderer does not know if it has HTML text to render or plain text. If nothing else is done, it will check for an opening HTML and thus decide whether to use plain text or HTML rendering.

If you know the text is going to contain compliant HTML markup, or the string contains HTML markup without opening/closing HTML tags, call Renderer.setHtml(true) after get[nnn]CellRenderer() is called, but before painting happens. This may be before or after setting the text. If your string contains HTML markup which you want rendered literally, call Renderer.setHtml(false) at the same point, and plain text rendering will be used regardless of the content of the string.

A convenience method exists to fetch a HTML renderer JLabel. This is useful either for painting a string onto the screen using the html renderer - just call HtmlRenderer.sharedLabel(), set its text, icon, etc., and call paint(). It is also useful if you need to measure the number of screen pixels a string will consume - set the text and font and call getPreferredSize()^*. The returned label is guaranteed to be able to paint itself and calculate its preferred size correctly without needing to be added to a parent component.

^*The size measured will be the size this HTML renderer will use on the screen for the text in question. While usually close, this is not guaranteed to be exactly the same as a JLabel with the standard UI delegate would required.

This class is absolutely not thread safe, and may not be called on any thread but the AWT event dispatch thread.

Nested Class Summary

static interface

HtmlRenderer.Renderer Interface aggregating TableCellRenderer, TreeCellRenderer and ListCellRenderer.

Field Summary

static int	STYLE_CLIP Constant used by renderString, renderPlainString renderHTML, and HtmlRenderer.setRenderStyle if painting should simply be cut off at the boundary of the cooordinates passed.
static int	STYLE_TRUNCATE Constant used by renderString, renderPlainString renderHTML and HtmlRenderer.setRenderStyle if painting should produce an ellipsis (...) if the text would overlap the boundary of the coordinates passed

Method Summary

static double	renderHTML(String s, Graphics g, int x, int y, int w, int h, Font f, Color defaultColor, int style, boolean paint) Render a string as HTML using a fast, lightweight renderer supporting a limited subset of HTML.
static double	renderPlainString(String s, Graphics g, int x, int y, int w, int h, Font f, Color defaultColor, int style, boolean paint) Render a string to a graphics instance, using the same API as renderHTML().
static double	renderString(String s, Graphics g, int x, int y, int w, int h, Font f, Color defaultColor, int style, boolean paint) Render a string to a graphics context, using HTML markup if the string begins with html tags.
static JLabel	sharedLabel() For HTML rendering jobs outside of trees/lists/tables, returns a JLabel which will paint its text using the lightweight HTML renderer.
static HtmlRenderer.Renderer	sharedRenderer() Returns an instance of Renderer which may be used as a table/tree/list cell renderer.

Methods inherited from class java.lang.Object

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

Field Detail

STYLE_CLIP

public static final int STYLE_CLIP

Constant used by renderString, renderPlainString renderHTML, and HtmlRenderer.setRenderStyle if painting should simply be cut off at the boundary of the cooordinates passed.

See Also:

Constant Field Values

STYLE_TRUNCATE

public static final int STYLE_TRUNCATE

Constant used by renderString, renderPlainString renderHTML and HtmlRenderer.setRenderStyle if painting should produce an ellipsis (...) if the text would overlap the boundary of the coordinates passed

See Also:

Constant Field Values

Method Detail

sharedRenderer

public static final HtmlRenderer.Renderer sharedRenderer()

Returns an instance of Renderer which may be used as a table/tree/list cell renderer. This method must be called on the AWT event thread. If you know you will be passing it legal HTML (legal as documented here), call setHtml(true) on the result of this call after calling getNNNCellRenderer to provide this hint.

Returns:

A cell renderer that can render HTML.

sharedLabel

public static final JLabel sharedLabel()

For HTML rendering jobs outside of trees/lists/tables, returns a JLabel which will paint its text using the lightweight HTML renderer. The result of this call will implement the Renderer interface. The state of the renderer is reset before it is returned, so any artifacts of previous usage (border, etc) are eliminated.

Do not add the result of this call to the AWT hierarchy - it is designed for offscreen painting, and may be reconfigured to paint something else at any time.

This method must be called from the AWT event thread.

Returns:

A JLabel

renderPlainString

public static double renderPlainString(String s,
                                       Graphics g,
                                       int x,
                                       int y,
                                       int w,
                                       int h,
                                       Font f,
                                       Color defaultColor,
                                       int style,
                                       boolean paint)

Render a string to a graphics instance, using the same API as renderHTML(). Can render a string using JLabel-style ellipsis (...) in the case that it will not fit in the passed rectangle, if the style parameter is STYLE_CLIP. Returns the width in pixels successfully painted. This method is not thread-safe and should not be called off the AWT thread.

See Also:

renderHTML(java.lang.String, java.awt.Graphics, int, int, int, int, java.awt.Font, java.awt.Color, int, boolean)

renderString

public static double renderString(String s,
                                  Graphics g,
                                  int x,
                                  int y,
                                  int w,
                                  int h,
                                  Font f,
                                  Color defaultColor,
                                  int style,
                                  boolean paint)

Render a string to a graphics context, using HTML markup if the string begins with html tags. Delegates to renderPlainString() or renderHTML() as appropriate. See the documentation for renderHTML() for details of the subset of HTML that is supported.

This method is not thread-safe and should not be called off the AWT thread.

Parameters:

s - The string to render

g - A graphics object into which the string should be drawn, or which should be used for calculating the appropriate size

x - The x coordinate to paint at.

y - The y position at which to paint. Note that this method does not calculate font height/descent - this value should be the baseline for the line of text, not the upper corner of the rectangle to paint in.

w - The maximum width within which to paint.

h - The maximum height within which to paint.

f - The base font to be used for painting or calculating string width/height.

defaultColor - The base color to use if no font color is specified as html tags

style - The wrapping style to use, either STYLE_CLIP, or STYLE_TRUNCATE

paint - True if actual painting should occur. If false, this method will not actually paint anything, only return a value representing the width/height needed to paint the passed string.

Returns:

The width in pixels required to paint the complete string, or the passed parameter w if it is smaller than the required width.

renderHTML

public static double renderHTML(String s,
                                Graphics g,
                                int x,
                                int y,
                                int w,
                                int h,
                                Font f,
                                Color defaultColor,
                                int style,
                                boolean paint)

Render a string as HTML using a fast, lightweight renderer supporting a limited subset of HTML. The following tags are supported, in upper or lower case:

<B>	Boldface text
<S>	Strikethrough text
<U>	Underline text
<I>	Italic text
<EM>	Emphasized text (same as italic)
<STRONG>	Strong text (same as bold)
<font>	Font color - font attributes other than color are not supported. Colors may be specified as hexidecimal strings, such as #FF0000 or as logical colors defined in the current look and feel by specifying a ! character as the first character of the color name. Logical colors are colors available from the current look and feel's UIManager. For example, <font color="!Tree.background"> will set the font color to the result of UIManager.getColor("Tree.background"). Font size tags are not supported.

The lightweight html renderer supports the following named sgml character entities: quot, lt, amp, lsquo, rsquo, ldquo, rdquo, ndash, mdash, ne, le, ge, copy, reg, trade. . It also supports numeric entities (e.g. &8822;).

When to use this method instead of the JDK's HTML support: when rendering short strings (for example, in a tree or table cell renderer) with limited HTML, this method is approximately 10x faster than JDK HTML rendering (it does not build and parse a document tree).

Specifying logical colors
Hardcoded text colors are undesirable, as they can be incompatible (even invisible) on some look and feels or themes. The lightweight HTML renderer supports a non-standard syntax for specifying font colors via a key for a color in the UI defaults for the current look and feel. This is accomplished by prefixing the key name with a ! character. For example: <font color='!controlShadow'>.

Modes of operation
This method supports two modes of operation:

1. STYLE_CLIP - as much text as will fit in the pixel width passed to the method should be painted, and the text should be cut off at the maximum width or clip rectangle maximum X boundary for the graphics object, whichever is smaller.
2. STYLE_TRUNCATE - paint as much text as will fit in the pixel width passed to the method, but paint the last three characters as .'s, in the same manner as a JLabel truncates its text when the available space is too small.

This method can also be used in non-painting mode to establish the space necessary to paint a string. This is accomplished by passing the value of the paint argument as false. The return value will be the required width in pixels to display the text. Note that in order to retrieve an accurate value, the argument for available width should be passed as Integer.MAX_VALUE or an appropriate maximum size - otherwise the return value will either be the passed maximum width or the required width, whichever is smaller. Also, the clip shape for the passed graphics object should be null or a value larger than the maximum possible render size.

This method will log a warning if it encounters HTML markup it cannot render. To aid diagnostics, if NetBeans is run with the argument -J-Dnetbeans.lwhtml.strict=true an exception will be thrown when an attempt is made to render unsupported HTML.

This method is not thread-safe and should not be called off the AWT thread!

Parameters:

s - The string to render

g - A graphics object into which the string should be drawn, or which should be used for calculating the appropriate size

x - The x coordinate to paint at.

y - The y position at which to paint. Note that this method does not calculate font height/descent - this value should be the baseline for the line of text, not the upper corner of the rectangle to paint in.

w - The maximum width within which to paint.

h - The maximum height within which to paint.

f - The base font to be used for painting or calculating string width/height.

defaultColor - The base color to use if no font color is specified as html tags

style - The wrapping style to use, either STYLE_CLIP, or STYLE_TRUNCATE

paint - True if actual painting should occur. If false, this method will not actually paint anything, only return a value representing the width/height needed to paint the passed string (height only in the case of word wrap, which is currently not exposed in the API).

Returns:

The width in pixels required to paint the complete string, or the passed parameter w if it is smaller than the required width.