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

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:

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.

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`

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.

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

Built on December 7 2006. | Portions Copyright 1997-2005 Sun Microsystems, Inc. All rights reserved.