public final class HtmlRenderer extends Object
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 arguments as renderHTML, but will also honor
HtmlRenderer.STYLE_TRUNCATE, so strings can be rendered with trailing
ellipsis if there is not enough spacerenderHTML 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 |
<a> |
Link 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 hexadecimal 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:
HtmlRenderer.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.HtmlRenderer.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
| Modifier and Type | Class and Description |
|---|---|
static interface |
HtmlRenderer.Renderer
Interface aggregating table, tree, and list cell renderers.
|
| Modifier and Type | Field and Description |
|---|---|
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 coordinates 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. |
| Modifier and Type | Method and Description |
|---|---|
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>. |
public static final int STYLE_CLIP
renderString, renderPlainString,
renderHTML, and HtmlRenderer.Renderer.setRenderStyle(int)
if painting should simply be cut off at the boundary of the coordinates passed.public static final int STYLE_TRUNCATE
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.public static final HtmlRenderer.Renderer createRenderer()
setHtml(true) on the
result of this call after calling getNNNCellRenderer to provide this hint.public static final JLabel createLabel()
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);
}
public static double renderPlainString(String s, Graphics g, int x, int y, int w, int h, Font f, Color defaultColor, int style, boolean paint)
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
HtmlRenderer.STYLE_CLIP. Returns the width in pixels successfully painted.
This method is not thread-safe and should not be called off
the AWT thread.public static double renderString(String s, Graphics g, int x, int y, int w, int h, Font f, Color defaultColor, int style, boolean paint)
<html>. Delegates to renderPlainString
or renderHTML as appropriate. See the class documentation for
for details of the subset of HTML that is
supported.s - The string to renderg - A graphics object into which the string should be drawn, or which should be
used for calculating the appropriate sizex - 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 tagsstyle - The wrapping style to use, either HtmlRenderer.STYLE_CLIP,
or HtmlRenderer.STYLE_TRUNCATEpaint - 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.w if it is
smaller than the required width.public static double renderHTML(String s, Graphics g, int x, int y, int w, int h, Font f, Color defaultColor, int style, boolean paint)
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.
s - The string to renderg - A graphics object into which the string should be drawn, or which should be
used for calculating the appropriate sizex - 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 tagsstyle - The wrapping style to use, either HtmlRenderer.STYLE_CLIP,
or HtmlRenderer.STYLE_TRUNCATEpaint - 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.w if it is
smaller than the required width.