NASA World Wind

gov.nasa.worldwind.render
Class MultiLineTextRenderer

java.lang.Object
  extended by gov.nasa.worldwind.render.MultiLineTextRenderer

public class MultiLineTextRenderer
extends java.lang.Object

Multi line, rectangle bound text renderer with (very) minimal html support.

The MultiLineTextRenderer (MLTR) handles wrapping, measuring and drawing of multiline text strings using Sun's JOGL TextRenderer.

A multiline text string is a character string containing new line characters in between lines.

MLTR can handle both regular text with new line seprators and a very minimal implementation of HTML. Each type of text has its own methods though.

Usage:

Instantiation:

The MLTR needs a Font or a TextRenderer to be instanciated. This will be the font used for text drawing, wrapping and measuring. For HTML methods this font will be considered as the document default font.

 Font font = Font.decode("Arial-PLAIN-12");
 MultiLineTextRenderer mltr = new MultiLineTextRenderer(font);
 
or
 TextRenderer tr = new TextRenderer(Font.decode("Arial-PLAIN-10"));
 MultiLineTextRenderer mltr = new MultiLineTextRenderer(tr);
 

Drawing regular text:

 String text = "Line one.\nLine two.\nLine three...";
 int x = 10;             // Upper left corner of text rectangle.
 int y = 200;            // Origin at bottom left of screen.
 int lineHeight = 14;    // Line height in pixels.
 Color color = Color.RED;

 mltr.setTextColor(color);
 mltr.getTextRenderer().begin3DRendering();
 mltr.draw(text, x, y, lineHeight);
 mltr.getTextRenderer().end3DRendering();
 

Wrapping text to fit inside a width and optionaly a height

The MLTR wrap method will insert new line characters inside the text so that it fits a given width in pixels.

If a height dimension above zero is specified too, the text will be truncated if needed, and a continuation string will be appended to the last line. The continuation string can be set with mltr.setContinuationString();

 // Fit inside 300 pixels, no height constraint
 String wrappedText = mltr.wrap(text, new Dimension(300, 0));

 // Fit inside 300x400 pixels, text may be truncated
 String wrappedText = mltr.wrap(text, new Dimension(300, 400));
 

Measuring text

 Rectangle2D textBounds = mltr.getBounds(text);
 

The textBounds rectangle returned contains the width and height of the text as it would be drawn with the current font.

Note that textBounds.minX is the number of lines found and textBounds.minY is the maximum line height for the font used. This value can be safely used as the lineHeight argument when drawing - or can even be ommited after a getBounds: draw(text, x, y); ...

HTML support

Supported tags are:

...

See AbstractAnnotation.drawAnnotation() for more usage details.


Field Summary
static int ALIGN_CENTER
           
static int ALIGN_LEFT
           
static int ALIGN_RIGHT
           
static java.lang.String EFFECT_NONE
           
static java.lang.String EFFECT_OUTLINE
           
static java.lang.String EFFECT_SHADOW
           
 
Constructor Summary
MultiLineTextRenderer(TextRenderer textRenderer)
           
 
Method Summary
static boolean containsHTML(java.lang.String text)
          Return true if the text contains some sgml tags.
 void draw(java.lang.String text, int x, int y)
          Draw a multi-line text string with bounding rectangle top starting at the y position.
 void draw(java.lang.String text, int x, int y, int textLineHeight)
          Draw a multi-line text string with bounding rectangle top starting at the y position.
 void draw(java.lang.String text, int x, int y, int textLineHeight, java.lang.String effect)
          Draw a multi-line text string with bounding rectangle top starting at the y position.
 void draw(java.lang.String text, int x, int y, java.lang.String effect)
          Draw a multi-line text string with bounding rectangle top starting at the y position.
 void drawHTML(java.lang.String text, int x, int y, TextRendererCache renderers)
          Draw a multi-line html text string with bounding rectangle top starting at the y position.
static java.lang.String getAttributeFromTagHTML(java.lang.String text, java.lang.String attributeName)
          Extract an attribute value from a HTML tag string.
 java.awt.Color getBackColor()
          Get the background color used for EFFECT_SHADOW and EFFECT_OUTLINE.
 java.awt.Rectangle getBounds(java.lang.String text)
          Returns the bounding rectangle for a multi-line string.
 java.awt.geom.Rectangle2D getBoundsHTML(java.lang.String text, TextRendererCache renderers)
          Returns the bounding rectangle for a multi-line html string.
 int getLineHeight()
          Get the current line height in pixels.
 int getLineSpacing()
          Get the current line spacing height in pixels.
 java.awt.Color getLinkColor()
          Get the current link color.
 double getMaxLineHeight(TextRenderer tr)
          Get the maximum line height for the given text renderer.
 int getTextAlign()
          Get the current text alignment.
 java.awt.Color getTextColor()
          Get the current text color.
 TextRenderer getTextRenderer()
          Get the current TextRenderer.
 void pick(java.lang.String text, int x, int y, int textLineHeight, DrawContext dc, PickSupport pickSupport, java.lang.Object refObject, Position refPosition)
          Draw text with unique colors word bounding rectangles and add each as a pickable object to the provided PickSupport instance.
 void pickHTML(java.lang.String text, int x, int y, TextRendererCache renderers, DrawContext dc, PickSupport pickSupport, java.lang.Object refObject, Position refPosition)
          Draw text with unique colors word bounding rectangles and add each as a pickable object to the provided PickSupport instance.
static java.lang.String processLineBreaksHTML(java.lang.String text)
          Remove new line characters then replace BR and P tags with appropriate new lines
static java.lang.String removeTagsHTML(java.lang.String text)
          Remove all HTML tags from a text string.
 void setBackColor(java.awt.Color color)
          Set the background color used for EFFECT_SHADOW and EFFECT_OUTLINE.
 void setContinuationString(java.lang.String s)
          Set the character string appended at the end of text truncated during a wrap operation when exceeding the given height limit.
 void setLineHeight(int height)
          Set the current line height in pixels.
 void setLineSpacing(int height)
          Set the current line spacing height in pixels.
 void setLinkColor(java.awt.Color color)
          Set the link color.
 void setTextAlign(int align)
          Set the current text alignment.
 void setTextColor(java.awt.Color color)
          Set the text renderer color.
 java.lang.String wrap(java.lang.String text, java.awt.Dimension dimension)
          Add 'new line' characters inside a string so that it's bounding rectangle tries not to exceed the given dimension width.
 java.lang.String wrapHTML(java.lang.String text, java.awt.Dimension dimension, TextRendererCache renderers)
          Add 'new line' characters inside an html text string so that it's bounding rectangle tries not to exceed the given dimension width.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ALIGN_CENTER

public static final int ALIGN_CENTER
See Also:
Constant Field Values

ALIGN_LEFT

public static final int ALIGN_LEFT
See Also:
Constant Field Values

ALIGN_RIGHT

public static final int ALIGN_RIGHT
See Also:
Constant Field Values

EFFECT_NONE

public static final java.lang.String EFFECT_NONE
See Also:
Constant Field Values

EFFECT_OUTLINE

public static final java.lang.String EFFECT_OUTLINE
See Also:
Constant Field Values

EFFECT_SHADOW

public static final java.lang.String EFFECT_SHADOW
See Also:
Constant Field Values
Constructor Detail

MultiLineTextRenderer

public MultiLineTextRenderer(TextRenderer textRenderer)
Method Detail

containsHTML

public static boolean containsHTML(java.lang.String text)
Return true if the text contains some sgml tags.

Parameters:
text - The text string to evaluate.
Returns:
true if the string contains sgml or html tags

draw

public void draw(java.lang.String text,
                 int x,
                 int y)
Draw a multi-line text string with bounding rectangle top starting at the y position. Depending on the current textAlign, the x position is either the rectangle left side, middle or right side. Uses the current line height.

Parameters:
text - the multi-line text to draw.
x - the x position for top left corner of text rectangle.
y - the y position for top left corner of the text rectangle.

draw

public void draw(java.lang.String text,
                 int x,
                 int y,
                 int textLineHeight)
Draw a multi-line text string with bounding rectangle top starting at the y position. Depending on the current textAlign, the x position is either the rectangle left side, middle or right side. Uses the given line height.

Parameters:
text - the multi-line text to draw.
x - the x position for top left corner of text rectangle.
y - the y position for top left corner of the text rectangle.
textLineHeight - the line height in pixels.

draw

public void draw(java.lang.String text,
                 int x,
                 int y,
                 int textLineHeight,
                 java.lang.String effect)
Draw a multi-line text string with bounding rectangle top starting at the y position. Depending on the current textAlign, the x position is either the rectangle left side, middle or right side. Uses the given line height and effect.

Parameters:
text - the multi-line text to draw.
x - the x position for top left corner of text rectangle.
y - the y position for top left corner of the text rectangle.
textLineHeight - the line height in pixels.
effect - the effect to use for the text rendering. Can be one of EFFECT_NONE, EFFECT_SHADOW or EFFECT_OUTLINE.

draw

public void draw(java.lang.String text,
                 int x,
                 int y,
                 java.lang.String effect)
Draw a multi-line text string with bounding rectangle top starting at the y position. Depending on the current textAlign, the x position is either the rectangle left side, middle or right side. Uses the current line height and the given effect.

Parameters:
text - the multi-line text to draw.
x - the x position for top left corner of text rectangle.
y - the y position for top left corner of the text rectangle.
effect - the effect to use for the text rendering. Can be one of EFFECT_NONE, EFFECT_SHADOW or EFFECT_OUTLINE.

drawHTML

public void drawHTML(java.lang.String text,
                     int x,
                     int y,
                     TextRendererCache renderers)
Draw a multi-line html text string with bounding rectangle top starting at the y position. The x position is eiher the rectangle left side, middle or right side depending on the current text alignement.

Parameters:
text - the multi-line text to draw
x - the x position for top left corner of text rectangle
y - the y position for top left corner of the text rectangle
renderers - A HashMap of fonts and shared text renderers.

getAttributeFromTagHTML

public static java.lang.String getAttributeFromTagHTML(java.lang.String text,
                                                       java.lang.String attributeName)
Extract an attribute value from a HTML tag string. The attribute is expected to be formed on the pattern: name="...". Other variants will likely fail.

Parameters:
text - the HTML tage string.
attributeName - the attribute name.
Returns:
the attribute value found. Null if empty or not found.

getBackColor

public java.awt.Color getBackColor()
Get the background color used for EFFECT_SHADOW and EFFECT_OUTLINE.

Returns:
the current background color used when drawing shadow or outline..

getBounds

public java.awt.Rectangle getBounds(java.lang.String text)
Returns the bounding rectangle for a multi-line string. Note that the X component of the rectangle is the number of lines found in the text and the Y component of the rectangle is the max line height encountered. Note too that this method will automatically set the current line height to the max height found.

Parameters:
text - the multi-line text to evaluate.
Returns:
the bounding rectangle for the string.

getBoundsHTML

public java.awt.geom.Rectangle2D getBoundsHTML(java.lang.String text,
                                               TextRendererCache renderers)
Returns the bounding rectangle for a multi-line html string. Note that the X component of the rectangle is the number of lines found in the text and the Y component of the rectangle is the average line height encountered.

Parameters:
text - the multi-line html text to evaluate.
renderers - A HashMap of fonts and shared text renderers.
Returns:
the bounding rectangle for the rendered text.

getLineHeight

public int getLineHeight()
Get the current line height in pixels.

Returns:
the current line height in pixels.

getLineSpacing

public int getLineSpacing()
Get the current line spacing height in pixels.

Returns:
the current line spacing height in pixels.

getLinkColor

public java.awt.Color getLinkColor()
Get the current link color.

Returns:
the current link color.

getMaxLineHeight

public double getMaxLineHeight(TextRenderer tr)
Get the maximum line height for the given text renderer.

Parameters:
tr - the TextRenderer.
Returns:
the maximum line height.

getTextAlign

public int getTextAlign()
Get the current text alignment. Can be one of ALIGN_LEFT the default, ALIGN_CENTER or ALIGN_RIGHT.

Returns:
the current text alignment.

getTextColor

public java.awt.Color getTextColor()
Get the current text color.

Returns:
the current text color.

getTextRenderer

public TextRenderer getTextRenderer()
Get the current TextRenderer.

Returns:
the current TextRenderer.

pick

public void pick(java.lang.String text,
                 int x,
                 int y,
                 int textLineHeight,
                 DrawContext dc,
                 PickSupport pickSupport,
                 java.lang.Object refObject,
                 Position refPosition)
Draw text with unique colors word bounding rectangles and add each as a pickable object to the provided PickSupport instance.

Parameters:
text - the multi-line text to draw.
x - the x position for top left corner of text rectangle.
y - the y position for top left corner of the text rectangle.
textLineHeight - the line height in pixels.
dc - the current DrawContext.
pickSupport - the PickSupport instance to be used.
refObject - the user reference object associated with every picked word.
refPosition - the user reference Position associated with every picked word.

pickHTML

public void pickHTML(java.lang.String text,
                     int x,
                     int y,
                     TextRendererCache renderers,
                     DrawContext dc,
                     PickSupport pickSupport,
                     java.lang.Object refObject,
                     Position refPosition)
Draw text with unique colors word bounding rectangles and add each as a pickable object to the provided PickSupport instance.

Parameters:
text - the multi-line text to draw.
x - the x position for top left corner of text rectangle.
y - the y position for top left corner of the text rectangle.
renderers - A HashMap of fonts and shared text renderers.
dc - the current DrawContext.
pickSupport - the PickSupport instance to be used.
refObject - the user reference object associated with every picked word.
refPosition - the user reference Position associated with every picked word.

processLineBreaksHTML

public static java.lang.String processLineBreaksHTML(java.lang.String text)
Remove new line characters then replace BR and P tags with appropriate new lines

Parameters:
text - The html text string to process.
Returns:
The processed text string.

removeTagsHTML

public static java.lang.String removeTagsHTML(java.lang.String text)
Remove all HTML tags from a text string.

Parameters:
text - the string to filter.
Returns:
the filtered string.

setBackColor

public void setBackColor(java.awt.Color color)
Set the background color used for EFFECT_SHADOW and EFFECT_OUTLINE.

Parameters:
color - the color to use when drawing shadow or outline.

setContinuationString

public void setContinuationString(java.lang.String s)
Set the character string appended at the end of text truncated during a wrap operation when exceeding the given height limit.

Parameters:
s - the continuation character string.

setLineHeight

public void setLineHeight(int height)
Set the current line height in pixels.

Parameters:
height - the current line height in pixels.

setLineSpacing

public void setLineSpacing(int height)
Set the current line spacing height in pixels.

Parameters:
height - the line spacing height in pixels.

setLinkColor

public void setLinkColor(java.awt.Color color)
Set the link color.

Parameters:
color - the color to use when drawing hyperlinks.

setTextAlign

public void setTextAlign(int align)
Set the current text alignment. Can be one of ALIGN_LEFT the default, ALIGN_CENTER or ALIGN_RIGHT.

Parameters:
align - the current text alignment.

setTextColor

public void setTextColor(java.awt.Color color)
Set the text renderer color.

Parameters:
color - the color to use when drawing text.

wrap

public java.lang.String wrap(java.lang.String text,
                             java.awt.Dimension dimension)
Add 'new line' characters inside a string so that it's bounding rectangle tries not to exceed the given dimension width. If the dimension height is more than zero, the text will be truncated accordingly and the continuation string will be appended to the last line. Note that words will not be split and at least one word will be used per line so the longest word defines the final width of the bounding rectangle. Each line is trimmed of leading and trailing spaces.

Parameters:
text - the text string to wrap
dimension - the maximum dimension in pixels
Returns:
the wrapped string

wrapHTML

public java.lang.String wrapHTML(java.lang.String text,
                                 java.awt.Dimension dimension,
                                 TextRendererCache renderers)
Add 'new line' characters inside an html text string so that it's bounding rectangle tries not to exceed the given dimension width. If the dimension height is more than zero, the text will be truncated accordingly and the continuation string will be appended to the last line. Note that words will not be split and at least one word will be used per line so the longest word defines the final width of the bounding rectangle. Each line is trimmed of leading and trailing spaces.

Parameters:
text - the html text string to wrap
dimension - the maximum dimension in pixels
renderers - A HashMap of fonts and shared text renderers.
Returns:
the wrapped html string

NASA World Wind