HtmlRenderer (NetBeans UI Utilities API) - NetBeans API Javadoc 5.5.0

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

org.openide.awt 6.7.22

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.openide.awt
Class HtmlRenderer

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

public final class HtmlRenderer
extends Object
extends Object

A lightweight HTML renderer supporting a minimal subset of HTML used for markup purposes only: basic font styles and some colors.

Provides a generic cell renderer implementation which can be used for trees, tables, lists, combo boxes, etc.

If you only need to paint some HTML quickly, use the static methods for painting. These methods behave 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).

This parser is designed entirely for performance; there are no separate parsing and rendering loops. In order to achieve its performance, some trade-offs are required. 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:

`<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, and nbsp. 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 overkill. 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:

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

Example usages:
org.openide.nodes.Node.getHtmlDisplayName
org.openide.filesystems.FileSystem.HtmlStatus

Since:: 4.30

Nested Class Summary

static interface HtmlRenderer.Renderer
          Interface aggregating table, tree, and list cell renderers.

Field Summary

static int STYLE_CLIP
          Constant used by renderString, renderPlainString, renderHTML, and HtmlRenderer.Renderer.setRenderStyle(int) 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.Renderer.setRenderStyle(int) if painting should produce an ellipsis (...) if the text would overlap the boundary of the coordinates passed.

Method Summary

static JLabel createLabel()
          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 createRenderer()
          Returns an instance of Renderer which may be used as a table/tree/list cell renderer.

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

Methods inherited from class java.lang.Object

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

Nested Class Summary
`static interface`	`HtmlRenderer.Renderer` Interface aggregating table, tree, and list cell renderers.

Field Summary
`static int`	`STYLE_CLIP` Constant used by `renderString`, `renderPlainString`, `renderHTML`, and `HtmlRenderer.Renderer.setRenderStyle(int)` 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.Renderer.setRenderStyle(int)` if painting should produce an ellipsis (...) if the text would overlap the boundary of the coordinates passed.

Method Summary
`static JLabel`	`createLabel()` 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`	`createRenderer()` Returns an instance of Renderer which may be used as a table/tree/list cell renderer.
`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>`.

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.Renderer.setRenderStyle(int) 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.Renderer.setRenderStyle(int) if painting should produce an ellipsis (...) if the text would overlap the boundary of the coordinates passed.

See Also:: Constant Field Values

Method Detail

createRenderer

public static final HtmlRenderer.Renderer createRenderer()

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.

createLabel

public static final JLabel createLabel()

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 HtmlRenderer.Renderer. Do not add the result of this call to the AWT hierarchy. It is not a general purpose JLabel, and will not behave correctly. Use the result of this call to paint or to measure text. Example:

 private final JLabel label = HtmlRenderer.createLabel();

 public void paint(Graphics g) {
    // background/whatever painting code here...
    label.setText(someHtmlText);
    label.paint(g);
 }

Returns:: a label which can render a subset of HTML very quickly

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>. Delegates to renderPlainString or renderHTML as appropriate. See the class documentation for for details of the subset of HTML that is supported.

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. See class Javadoc for details.

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.

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.