com.davisor.graphics
Class LabelRenderer

java.lang.Object
  com.davisor.graphics.LabelRenderer

public class LabelRenderer

extends java.lang.Object

LabelRenderer is a high-precision and high-quality label renderer that can render a rotated, scaled, and aligned labels into restricted rectangular areas. A dedicated label rendering tool is needed for this because naive affine scaling implementations often producing visually unpleasing results. This label renderer tool offers much better quality scaling results in all Java environment implementations, and offers also a number of other advanced label rendering functions.

LabelRenderer fits text in given restrictive rectangle by first selecting the largest possible font size with which the text fits completely inside a given area. This quarantees superior rendering quality when compared to corresponding plain affine scaling. This may also however still leave the text smaller than strictly neccessary. The label renderer will therefore apply an additional enlarging affine scaling, but now only with a small multiplier. Small enlarging affine text scaling does not detoriate text visual quality as much as other kind of affine text scaling, so the text visual quality is quaranteed to stay high while the text is made to fit the given space exactly.

Text scaling is applied only if given text will not fit into given area when rendered with given target font. Instead, if the text fits, it is rendered with given target font and font size, and not scaled up to fill up entirely the given area. Some area may therefore be left over, and this raises the question of text alignment withing the area.

Label renderer supports vertical and horizontal text alignment for the whole text label, and row-spesific horizontal text aligment for the individual rows of a multi-line text label. Please see RenderAttributes for available alignments and their codes.

Label size computation can be carried out it many different ways, and the selected strategy affects text scaling and alignment computation in suble ways. Label renderer supports the folliwing label size computation methods. Please see getTextBounds(int) and getRowBounds(java.lang.String, java.awt.Font, java.awt.font.FontRenderContext, int) for more information.

• STRINGBOUNDS - use Font.getStringBounds
• LOGICALBOUNDS - use GlyphVector.getLogicalBounds
• VISUALBOUNDS - use GlyphVector.getVisualBounds
• MIN - use the visual bounds of the smallest glyph
• MAX - use the visual bounds of the largets glyph
• MEDIAN - use the visual bounds of the median sized glyph

Each label renderer instance is tuned to render only one label at a time, thanks to the complex high-precision text rendering issues involved.

Since:

JDK1.2

See Also:

draw(Graphics2D,Paint,Paint,float,float,int,int), getRowBounds(String,Font,FontRenderContext,int), getTextBounds(String,Font,FontRenderContext,int)

Field Summary

static int	LOGICALBOUNDS Logical bounds text bounding box resolvation mode.
protected float	M_ax
protected float	M_ay
protected float	M_derivedBloat
protected java.awt.Font	M_derivedFont
protected java.awt.font.FontRenderContext	M_frc
protected float	M_height
protected int	M_mode
protected java.awt.geom.Rectangle2D	M_naturalBounds
protected java.awt.Font	M_originalFont
protected java.awt.geom.Rectangle2D	M_rotatedBounds
protected float	M_rotation
protected java.lang.String	M_text
protected float	M_width
static int	MAX Maximum text bounding box resolvation mode.
static int	MEDIAN Median text bounding box resolvation mode.
static int	MIN Minimum text bounding box resolvation mode.
static int	STRINGBOUNDS String bounds text bounding box resolvation mode (the default).
static int	VISUALBOUNDS Visual bounds text bounding box resolvation mode.

Constructor Summary

LabelRenderer(java.awt.Font font, java.awt.font.FontRenderContext frc, float width, float height, float rotation, float ax, float ay, int mode)
Creates a new label renderer instance.

LabelRenderer(java.awt.Font font, java.awt.font.FontRenderContext frc, float width, float height, float rotation, float ax, float ay, int mode, java.lang.String text)
Creates a new label renderer instance.

LabelRenderer(java.lang.String text, java.awt.Font font, java.awt.font.FontRenderContext frc, float width, float height, float rotation, float ax, float ay, int mode)
Deprecated. Please use LabelRenderer(Font, FontRenderContext, float, float, float, float, float, int, String) instead.

Method Summary

static java.awt.geom.Rectangle2D	addBounds(java.awt.geom.Rectangle2D b1, java.awt.geom.Rectangle2D b2) Adds a text bounding box to another in null safe way.
void	draw(java.awt.Graphics2D g, java.awt.Paint color, java.awt.Paint paint, float x, float y, int boundsAlignment, int textAlignment) Draws current label into the given graphics context in the given position.
void	draw(java.awt.Graphics2D g, java.awt.Paint color, java.awt.Paint paint, float x, float y, int boundsAlignment, int textAlignment, java.lang.String text) Draws given label into the given graphics context in the given position.
java.awt.Font	getFont() Gets the font used to draw the label.
float	getHeight() Gets the height of the box bounding the label.
static java.awt.geom.Rectangle2D	getRowBounds(java.lang.String text, java.awt.Font font, java.awt.font.FontRenderContext frc, int mode) Returns text row bounding box.
static java.awt.geom.Rectangle2D	getRowBounds(java.lang.String text, java.awt.Font font, java.awt.font.FontRenderContext frc, int mode, java.awt.geom.Rectangle2D bounds) Adds text row bounding box to given bounds.
java.lang.String	getText() Gets the current label text.
java.awt.geom.Rectangle2D	getTextBounds(int mode) Wrapper for the static getTextBounds()method.
static java.awt.geom.Rectangle2D	getTextBounds(java.lang.String text, java.awt.Font font, java.awt.font.FontRenderContext frc, int mode) Returns multiline text bounding box.
static java.awt.geom.Rectangle2D	getTextBounds(java.lang.String text, java.awt.Font font, java.awt.font.FontRenderContext frc, int mode, java.awt.geom.Rectangle2D bounds) Adds multiline text bounding box to given bounds.
float	getWidth() Gets the width of the box bounding the label.
protected void	init() Prepares label rendering based on current settings.
void	setFont(java.awt.Font font) Sets label font.
void	setSize(float width, float height) Sets label size restrictions.
void	setText(java.lang.String text) Sets current label text.

Methods inherited from class java.lang.Object

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

Field Detail

STRINGBOUNDS

public static final int STRINGBOUNDS

String bounds text bounding box resolvation mode (the default).

See Also:

Constant Field Values

LOGICALBOUNDS

public static final int LOGICALBOUNDS

Logical bounds text bounding box resolvation mode.

See Also:

Constant Field Values

VISUALBOUNDS

public static final int VISUALBOUNDS

Visual bounds text bounding box resolvation mode.

See Also:

Constant Field Values

MEDIAN

public static final int MEDIAN

Median text bounding box resolvation mode.

See Also:

Constant Field Values

MIN

public static final int MIN

Minimum text bounding box resolvation mode.

See Also:

Constant Field Values

MAX

public static final int MAX

Maximum text bounding box resolvation mode.

See Also:

Constant Field Values

M_derivedFont

protected java.awt.Font M_derivedFont

M_originalFont

protected java.awt.Font M_originalFont

M_frc

protected java.awt.font.FontRenderContext M_frc

M_naturalBounds

protected java.awt.geom.Rectangle2D M_naturalBounds

M_rotatedBounds

protected java.awt.geom.Rectangle2D M_rotatedBounds

M_text

protected java.lang.String M_text

M_ax

protected float M_ax

M_ay

protected float M_ay

M_derivedBloat

protected float M_derivedBloat

M_height

protected float M_height

M_rotation

protected float M_rotation

M_width

protected float M_width

M_mode

protected int M_mode

Constructor Detail

LabelRenderer

public LabelRenderer(java.awt.Font font,
                     java.awt.font.FontRenderContext frc,
                     float width,
                     float height,
                     float rotation,
                     float ax,
                     float ay,
                     int mode)

Creates a new label renderer instance. The renderer is prepared to render text with given font and other attributes into given restricted space.

Parameters:

font - label font

frc - the font render context

width - label maximum width in device coordinates (non-positive values impose no width restrictions)

height - label maximum height in device coordinates (non-positive values impose no height restrictions)

rotation - the rotation of labels of this axis

ax - X font scaling (-1 flips the font)

ay - Y font scaling (-1 flips the font)

mode - bounds computing method (see class description) (invalid modes default to STRINGBOUNDS)

Throws:

java.lang.IllegalArgumentException - if font or frc is null

See Also:

getHeight(), getTextBounds(int), getWidth(), RenderAttributes

LabelRenderer

public LabelRenderer(java.awt.Font font,
                     java.awt.font.FontRenderContext frc,
                     float width,
                     float height,
                     float rotation,
                     float ax,
                     float ay,
                     int mode,
                     java.lang.String text)

Creates a new label renderer instance. The renderer is prepared to render given text with given font and other attributes into given restricted space.

Parameters:

font - label font

frc - the font render context

width - label maximum width in device coordinates (non-positive values impose no width restrictions)

height - label maximum height in device coordinates (non-positive values impose no height restrictions)

rotation - the rotation of labels of this axis

ax - X font scaling (-1 flips the font)

ay - Y font scaling (-1 flips the font)

mode - bounds computing method (see class description) (invalid modes default to STRINGBOUNDS)

text - label text

Throws:

java.lang.IllegalArgumentException - if font or frc is null

See Also:

getHeight(), getTextBounds(int), getWidth(), RenderAttributes

LabelRenderer

public LabelRenderer(java.lang.String text,
                     java.awt.Font font,
                     java.awt.font.FontRenderContext frc,
                     float width,
                     float height,
                     float rotation,
                     float ax,
                     float ay,
                     int mode)

Deprecated. Please use LabelRenderer(Font, FontRenderContext, float, float, float, float, float, int, String) instead.

Creates a new label renderer instance. The renderer is prepared to render given text with given font and other attributes into given restricted space.

Parameters:

font - label font

frc - the font render context

width - label maximum width in device coordinates (non-positive values impose no width restrictions)

height - label maximum height in device coordinates (non-positive values impose no height restrictions)

rotation - the rotation of labels of this axis

ax - X font scaling (-1 flips the font)

ay - Y font scaling (-1 flips the font)

mode - bounds computing method (see class description) (invalid modes default to STRINGBOUNDS)

text - label text

Throws:

java.lang.IllegalArgumentException - if font or frc is null

See Also:

getHeight(), getTextBounds(int), getWidth(), RenderAttributes

Method Detail

init

protected void init()

Prepares label rendering based on current settings. In particular, the font that will be used in upcoming renderings is selected now. The font will be the original font only if the current label text can be rendered with it within given bounds without any scaling. If scaling is needed, the original font will be replaced with suitable scaled down derived font.

See Also:

draw(Graphics2D,Paint,Paint,float,float,int,int), getFont()

draw

public void draw(java.awt.Graphics2D g,
                 java.awt.Paint color,
                 java.awt.Paint paint,
                 float x,
                 float y,
                 int boundsAlignment,
                 int textAlignment)

Draws current label into the given graphics context in the given position.

If a label background paint is given, the label bounding box will be filled with that paint before the label itself is drawn.

Parameters:

g - the graphics context

color - label foreground color (may be null)

paint - label background paint (may be null)

x - label X-position in device coordinates

y - label Y-position in device coordinates

boundsAlignment - text bounding box alignment (RenderAttributes alignment code)

textAlignment - text alignment within text bounding box (RenderAttributes alignment code)

See Also:

init()

draw

public void draw(java.awt.Graphics2D g,
                 java.awt.Paint color,
                 java.awt.Paint paint,
                 float x,
                 float y,
                 int boundsAlignment,
                 int textAlignment,
                 java.lang.String text)

Draws given label into the given graphics context in the given position.

This method first sets current text to given text with setText(java.lang.String), and then calls the actual drawing method draw(Graphics2D,Paint,Paint,float,float,int,int).

Parameters:

g - the graphics context

color - label foreground color (may be null)

paint - label background paint (may be null)

x - label X-position in device coordinates

y - label Y-position in device coordinates

boundsAlignment - text bounding box alignment (RenderAttributes alignment code)

textAlignment - text alignment within text bounding box (RenderAttributes alignment code)

text - label text

See Also:

draw(Graphics2D,Paint,Paint,float,float,int,int), setText(java.lang.String)

getFont

public java.awt.Font getFont()

Gets the font used to draw the label. The font size may differ from the one originally specified.

See Also:

init()

getHeight

public float getHeight()

Gets the height of the box bounding the label.

See Also:

init(), setSize(float, float)

getText

public java.lang.String getText()

Gets the current label text.

Returns:

current label text

See Also:

setText(java.lang.String)

getWidth

public float getWidth()

Gets the width of the box bounding the label.

See Also:

init(), setSize(float, float)

setFont

public void setFont(java.awt.Font font)

Sets label font.

See Also:

getFont()

setSize

public void setSize(float width,
                    float height)

Sets label size restrictions.

Parameters:

width - label maximum width in device coordinates (non-positive values impose no width restrictios)

height - label maximum height in device coordinates (non-positive values impose no height restrictios)

setText

public void setText(java.lang.String text)

Sets current label text.

Parameters:

text - label text

See Also:

getText()

addBounds

public static java.awt.geom.Rectangle2D addBounds(java.awt.geom.Rectangle2D b1,
                                                  java.awt.geom.Rectangle2D b2)

Adds a text bounding box to another in null safe way.

Parameters:

b1 - bounds to add the other bounds to (may be null)

b2 - bounds to add into the other bounds (may be null)

Returns:

a reference to b1 after addition, or a new high-precision copy of b2 if b1 was null, or null of both rectangles were null

getRowBounds

public static java.awt.geom.Rectangle2D getRowBounds(java.lang.String text,
                                                     java.awt.Font font,
                                                     java.awt.font.FontRenderContext frc,
                                                     int mode)

Returns text row bounding box. Any newline characters in text are ignored. A null text or font will give null bounds.

Parameters:

text - the text to be measured (may be null)

font - font to render text with (may be null)

frc - the font render context (if null, the one in g is used)

mode - bounds computing method (see class description) (invalid modes default to STRINGBOUNDS)

Returns:

text row bounding box (may be null)

See Also:

getRowBounds(String,Font,FontRenderContext,int,Rectangle2D)

getRowBounds

public static java.awt.geom.Rectangle2D getRowBounds(java.lang.String text,
                                                     java.awt.Font font,
                                                     java.awt.font.FontRenderContext frc,
                                                     int mode,
                                                     java.awt.geom.Rectangle2D bounds)

Adds text row bounding box to given bounds.

Parameters:

text - the text to be measured (may be null)

font - font to render text with (may be null)

frc - the font render context. If null, the one in g is used.

mode - bounds computing method (see class description) (invalid modes default to STRINGBOUNDS)

bounds - old bounds to add text bounding box to (may be null)

Returns:

text row bounding box (may be null)

See Also:

addBounds(java.awt.geom.Rectangle2D, java.awt.geom.Rectangle2D), getRowBounds(String,Font,FontRenderContext,int), getTextBounds(String,Font,FontRenderContext,int,Rectangle2D)

getTextBounds

public java.awt.geom.Rectangle2D getTextBounds(int mode)

Wrapper for the static getTextBounds()method. Uses instance attributes for text, font and frc. Derived, or transformed, font is used.

Parameters:

mode - bounds computing method (see class description)

See Also:

getTextBounds(String,Font,FontRenderContext,int)

getTextBounds

public static java.awt.geom.Rectangle2D getTextBounds(java.lang.String text,
                                                      java.awt.Font font,
                                                      java.awt.font.FontRenderContext frc,
                                                      int mode)

Returns multiline text bounding box. Each newline character signifies the end of a line, and the beginning of another. The lines are stacked under each other. Row height is computed with given font for each row separately. Other row metrics are computed with getRowBounds(String,Font,FontRenderContext,int).

Parameters:

text - the text to be measured (may be null)

font - font to render text with (may be null)

frc - the font render context. If null, the one in g is used.

mode - bounds computing method (see class description) (invalid modes default to STRINGBOUNDS)

Returns:

text bounding box (may be null)

See Also:

getRowBounds(String,Font,FontRenderContext,int), getTextBounds(String,Font,FontRenderContext,int,Rectangle2D)

getTextBounds

public static java.awt.geom.Rectangle2D getTextBounds(java.lang.String text,
                                                      java.awt.Font font,
                                                      java.awt.font.FontRenderContext frc,
                                                      int mode,
                                                      java.awt.geom.Rectangle2D bounds)

Adds multiline text bounding box to given bounds.

Parameters:

text - the text to be measured (may be null)

font - font to render text with (may be null)

frc - the font render context. If null, the one in g is used.

mode - bounds computing method (see class description) (invalid modes default to STRINGBOUNDS)

bounds - old bounds to add text bounding box to (may be null)

Returns:

text bounding box (may be null)

See Also:

addBounds(java.awt.geom.Rectangle2D, java.awt.geom.Rectangle2D), getRowBounds(String,Font,FontRenderContext,int,Rectangle2D), getTextBounds(String,Font,FontRenderContext,int)