echopoint.image
Class TextImageReference

java.lang.Object
  nextapp.echo.AbstractImageReference
      nextapp.echo.StreamImageReference
          echopoint.image.EncodedImageReference
              echopoint.image.TextImageReference

All Implemented Interfaces:

nextapp.echo.ImageReference, java.io.Serializable

public class TextImageReference

extends EncodedImageReference

implements java.io.Serializable

The TextImageReference class is an ImageReference implementation that can draw text onto a background image. This makes the class perfect for "dynamic" button icons since a "button-like" background image can be used and then button text can be dynamically drawn on it.

If the text to be rendered wont fit within the background image (plus its Insets) then the background image can be "scaled" to fit the text. The scaling options are :

• SCALE_NONE - no scaling is performed
• SCALE_FAST - a fast scaling algorithm is used. Not always the best look but its fast
• SCALE_SMOOTH - a better looking scaling algorithm is used at the cost of speed
• SCALE_SPLICE_V_THEN_H - this will splice the image at its x,y, first in the vertical direction and then in the horizontal direction.
• SCALE_SPLICE_H_THEN_V - this will splice the image at its x,y, first in the horizontal direction and then in the vertical direction.

The last two scaling options are very useful for "button-like" background images. This is because they will not scale the "outer" edges of the image but rather "splice and fill". This means that "button-like shadows and outlines" will not be lost or scaled unecesarily.

TextImageReference will also "break" strings on carriage return boundaries, to allow for multi line text. This may result in the need to "auto-resize" the background image.

The text is drawn at a specific {x,y} position. If you use a contructor without the {x,y} parameters, then the text is automatically centred within the height and width of the backgroundImage. You can use the horizontal and vertical alignment properties to control where the text is placed in relation to the {x,y} position. The {x,y} position will be the base line of the text.

AttributedString's are used to render the image text. These contain formatting instructions for specific characters. While the formatting information uses java.awt.* visual classes, a series of static helper methods have been provided to help create java.text.AttributedStrings using Echo color/font objects. You can also use the ColorKit and FontKit classes.

AttributedStrings have a great feature whereby the Unicode replacement character u'FFFC' can be substituted with another visual element. This is supported via the replacementImages and the replacementImageAlignment properties. The images in the replacementImages will be substituted, in a round robin fashion, for each Unicode replacement character in the AttributedString.

This class by default does not keep the encoded output image bytes in memory. You can change this by setKeptInMemory(true).

You should think about loading the background images via ImageKit.loadCachedImage(...) so that these static images are cached even if the dynamic TextImageReference is not.

Author:

Brad Baker

See Also:

AttributedString, TextAttribute, Image, Image.SCALE_FAST, Image.SCALE_SMOOTH, Serialized Form

Field Summary

static nextapp.echo.Insets	DEFAULT_INSETS The default insets between the text and the outer edge of the background image
static int	SCALE_DEFAULT The default scaling option is SCALE_SPLICE_V_THEN_H
static int	SCALE_FAST Choose a scaling algorithm to optimize speed more than smoothness of the scaled image
static int	SCALE_NONE Dont scale the background image to the text size
static int	SCALE_SMOOTH Choose a scaling algorithm to optimize smoothness of the scaled image more than speed
static int	SCALE_SPLICE_H_THEN_V Choose a scaling algorithm that splices horizontally then vertically
static int	SCALE_SPLICE_V_THEN_H Choose a scaling algorithm that splices vertically then horizontally

Fields inherited from class nextapp.echo.AbstractImageReference

listenerList

Fields inherited from interface nextapp.echo.ImageReference

SIZE_UNKNOWN

Constructor Summary

TextImageReference(java.text.AttributedString string, java.awt.Image backgroundImage)
Constructs a TextImageReference that will be drawn centered within the background image.

TextImageReference(java.text.AttributedString string, java.awt.Image backgroundImage, int scaleOption)
Constructs a TextImageReference that will be drawn centered within the background image and scalled according to the scaling option.

TextImageReference(java.text.AttributedString string, java.lang.String imageFileName)
Constructs a TextImageReference that will be drawn centered within the background image, which is loaded from a file.

TextImageReference(java.text.AttributedString string, java.net.URL imageURL)
Constructs a TextImageReference that will be centered within the background image, which is loaded from an URL.

TextImageReference(int x, int y, java.text.AttributedString string, java.awt.Image backgroundImage)
Constructs a TextImageReference that will be drawn at the x,y points within the background image.

TextImageReference(int x, int y, java.text.AttributedString string, java.lang.String imageFileName)
Constructs a TextImageReference that will be drawn at the x,y points within the background image, which is loaded from a file.

TextImageReference(int x, int y, java.text.AttributedString string, java.net.URL imageURL)
Constructs a TextImageReference that will be drawn at the x,y points within the background image, which is loaded from an URL.

Method Summary

static java.text.AttributedString	getAttributedString(java.lang.String s) Returns an AttributedString with no color or font information
static java.text.AttributedString	getAttributedString(java.lang.String s, nextapp.echo.Color foreground, nextapp.echo.Font font) Returns an AttributedString with the specified forground color and font based on nextapp.echo.* visual objects.
java.awt.Image	getBackgroundImage() Returns the backgroundImage in use
int	getHeight() This returns the height of the backgroundImage
int	getHorizontalAlignment() Returns the horizontal alignment of the text relative to the x,y drawing point.
java.awt.Image	getImage() We override getImage() so that the resultant image is "painted" every time it is needed.
nextapp.echo.Insets	getInsets() Returns the Insets in use
int	getReplacementImageAlignment() Returns the alignment of the replacement images within the AttributedString.
java.awt.Image[]	getReplacementImages() Returns the array of replacement images that will be substituted for the Unicode replacement character 'u'FFFC'.
int	getScaleOption() Returns the scaling option in effect.
java.text.AttributedString	getString() Returns the AttributedString in use.
int	getTextAngle() Returns the current textAngle.
protected java.awt.font.TextLayout[]	getTextLayouts(java.awt.Graphics2D g, java.text.AttributedString as) This methods returns an array of TextLayouts that will be used to draw the attributed string.
int	getVerticalAlignment() Returns the vertical alignment of the text relative to the x,y drawing point.
int	getWidth() This returns the width of the backgroundImage.
int	getX() The x position where the etxt will be drawn.
int	getY() The y position where the etxt will be drawn.
boolean	isBestQuality() Returns true if the image produce is of the best quality.
protected java.awt.geom.Rectangle2D	paintText(java.awt.Graphics2D g, int x, int y) Called to paint the text of the TextImageReference.
protected void	replaceAttributedImages(java.awt.Graphics2D g, java.awt.font.FontRenderContext frc, java.text.AttributedString as) Replaces all Unicode replacement characters u'FFFC' with the images from getReplacementImages() array in a round robin fashion.
void	setBackgroundImage(java.awt.Image image) Sets the background image to be used
void	setBackgroundImage(java.lang.String imageFileName) Sets the background image by loading from an image file.
void	setBackgroundImage(java.net.URL imageURL) Sets the background image by loading from an image URL.
void	setBestQuality(boolean b) Set this to true if you want the best quality images to be drawn.
void	setHorizontalAlignment(int i) Sets the horizontal alignment of the text relative to the x,y drawing point.
void	setInsets(nextapp.echo.Insets insets) Sets the Insets between the text and the background image outer edge.
void	setReplacementImageAlignment(int i) Sets the alignment of the replacement images within the AttributedString.
void	setReplacementImages(java.awt.Image[] images) Sets the array of replacement images that will be substituted for the Unicode replacement character u'FFFC'.
void	setScaleOption(int scalingOption) Sets the scaling option that will be used to draw the background image.
void	setString(java.text.AttributedString string) This is the AttributedString to be drawn onto the image.
void	setTextAngle(int i) Sets the text angle in degrees to be used.
void	setVerticalAlignment(int i) Sets the vertical alignment of the text relative to the x,y drawing point.
void	setX(int i) Sets the X position to draw the text on the image.
void	setY(int i) Sets the y position for drawing the text on the image.
java.lang.String	toString()

Methods inherited from class echopoint.image.EncodedImageReference

getContentType, getEncoder, isKeptInMemory, isValid, render, setEncoder, setImage, setKeptInMemory, setValid, update

Methods inherited from class nextapp.echo.AbstractImageReference

addImageUpdateListener, removeImageUpdateListener

Methods inherited from class java.lang.Object

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

Field Detail

SCALE_NONE

public static final int SCALE_NONE

Dont scale the background image to the text size

See Also:

Constant Field Values

SCALE_FAST

public static final int SCALE_FAST

Choose a scaling algorithm to optimize speed more than smoothness of the scaled image

See Also:

Constant Field Values

SCALE_SMOOTH

public static final int SCALE_SMOOTH

Choose a scaling algorithm to optimize smoothness of the scaled image more than speed

See Also:

Constant Field Values

SCALE_SPLICE_V_THEN_H

public static final int SCALE_SPLICE_V_THEN_H

Choose a scaling algorithm that splices vertically then horizontally

See Also:

Constant Field Values

SCALE_SPLICE_H_THEN_V

public static final int SCALE_SPLICE_H_THEN_V

Choose a scaling algorithm that splices horizontally then vertically

See Also:

Constant Field Values

SCALE_DEFAULT

public static final int SCALE_DEFAULT

The default scaling option is SCALE_SPLICE_V_THEN_H

See Also:

Constant Field Values

DEFAULT_INSETS

public static final nextapp.echo.Insets DEFAULT_INSETS

The default insets between the text and the outer edge of the background image

Constructor Detail

TextImageReference

public TextImageReference(java.text.AttributedString string,
                          java.awt.Image backgroundImage)

Constructs a TextImageReference that will be drawn centered within the background image.

Parameters:

string - - the attributed string to draw. Can be null.

backgroundImage - - the background image to draw on. Must not be null.

TextImageReference

public TextImageReference(java.text.AttributedString string,
                          java.awt.Image backgroundImage,
                          int scaleOption)

Constructs a TextImageReference that will be drawn centered within the background image and scalled according to the scaling option.

Parameters:

string - - the attributed string to draw. Can be null.

backgroundImage - - the background image to draw on. Must not be null.

scaleOption - - the scaling option to use

TextImageReference

public TextImageReference(java.text.AttributedString string,
                          java.lang.String imageFileName)

Constructs a TextImageReference that will be drawn centered within the background image, which is loaded from a file.

Parameters:

string - - the attributed string to draw. Can be null.

imageFileName - - the background image file to draw on. Must not be null.

TextImageReference

public TextImageReference(java.text.AttributedString string,
                          java.net.URL imageURL)

Constructs a TextImageReference that will be centered within the background image, which is loaded from an URL.

Parameters:

string - - the attributed string to draw. Can be null.

imageURL - - the background image URL to draw on. Must not be null.

TextImageReference

public TextImageReference(int x,
                          int y,
                          java.text.AttributedString string,
                          java.awt.Image backgroundImage)

Constructs a TextImageReference that will be drawn at the x,y points within the background image.

Parameters:

x - - where to draw the text in the x direction

y - - where to draw the text in the y direction

string - - the attributed string to draw. Can be null.

backgroundImage - - the background image to draw on. Must not be null.

TextImageReference

public TextImageReference(int x,
                          int y,
                          java.text.AttributedString string,
                          java.lang.String imageFileName)

Constructs a TextImageReference that will be drawn at the x,y points within the background image, which is loaded from a file.

Parameters:

x - - where to draw the text in the x direction

y - - where to draw the text in the y direction

string - - the attributed string to draw. Can be null.

imageFileName - - the background image to draw on. Must not be null.

TextImageReference

public TextImageReference(int x,
                          int y,
                          java.text.AttributedString string,
                          java.net.URL imageURL)

Constructs a TextImageReference that will be drawn at the x,y points within the background image, which is loaded from an URL.

Parameters:

x - - where to draw the text in the x direction

y - - where to draw the text in the y direction

string - - the attributed string to draw. Can be null.

imageURL - - the background image to draw on. Must not be null.

Method Detail

paintText

protected java.awt.geom.Rectangle2D paintText(java.awt.Graphics2D g,
                                              int x,
                                              int y)

Called to paint the text of the TextImageReference. The background image is already present when this method is called

Subclasses are expected to draw the AttributedString, respecting the other parameters that are in force such as textAngle

This method returns a Rectangle2D that outlines the boundaries of any text painted, whcih may be larger than the actual drawing space.

Parameters:

g - the Graphics2D

x - the x co-ord to paint the text

y - the y co-ord to paint the text

Returns:

returns a boundary Rectangle enclosing all text painted

getTextLayouts

protected java.awt.font.TextLayout[] getTextLayouts(java.awt.Graphics2D g,
                                                    java.text.AttributedString as)

This methods returns an array of TextLayouts that will be used to draw the attributed string. In this default version of the method, the TextLayouts are broken down on carriage return boundaries. These TextLayouts can then be used to determine the height and width of the attributed string.

This is called to determine the dimensions of the current text. This is used to decide whether to "scale" the background image if the text inside it is bigger then these plus the insets. This method should return the same dimensions that are used in the paintText() method.

Parameters:

g - - the Graphics 2D

as - - the attributed string

Returns:

an array of TextLayout to be used for painting

replaceAttributedImages

protected void replaceAttributedImages(java.awt.Graphics2D g,
                                       java.awt.font.FontRenderContext frc,
                                       java.text.AttributedString as)

Replaces all Unicode replacement characters u'FFFC' with the images from getReplacementImages() array in a round robin fashion.

getImage

public java.awt.Image getImage()

We override getImage() so that the resultant image is "painted" every time it is needed. This is a computation vs memory tradeoff.

Overrides:

getImage in class EncodedImageReference

Returns:

Image - the AWT image object

See Also:

EncodedImageReference.getImage()

getBackgroundImage

public java.awt.Image getBackgroundImage()

Returns the backgroundImage in use

Returns:

Image - the backgroundImage in use

getHeight

public int getHeight()

This returns the height of the backgroundImage

Specified by:

getHeight in interface nextapp.echo.ImageReference

Overrides:

getHeight in class EncodedImageReference

See Also:

ImageReference.getHeight()

getHorizontalAlignment

public int getHorizontalAlignment()

Returns the horizontal alignment of the text relative to the x,y drawing point.

Returns:

The horizontal alignment of the text relative to the x,y drawing point, one of the following values:

• EchoConstants.LEFT
• EchoConstants.CENTER (the default)
• EchoConstants.RIGHT

getReplacementImageAlignment

public int getReplacementImageAlignment()

Returns the alignment of the replacement images within the AttributedString. This can be EchoConstants.TOP, EchoConstants.CENTER or EchoConstants.BOTTOM

Returns:

the replacement image alignment

getReplacementImages

public java.awt.Image[] getReplacementImages()

Returns the array of replacement images that will be substituted for the Unicode replacement character 'u'FFFC'. These are replaced in a round-robin fashion, by circling around the array. This can be a null array.

Returns:

the array of replacement images

getString

public java.text.AttributedString getString()

Returns the AttributedString in use.

Returns:

AttributedString - the AttributedString in use.

getTextAngle

public int getTextAngle()

Returns the current textAngle.

Returns:

int - the current textAngle.

getVerticalAlignment

public int getVerticalAlignment()

Returns the vertical alignment of the text relative to the x,y drawing point.

Returns:

The vertical alignment of the text relative to the x,y drawing point, one of the following values:

• EchoConstants.TOP
• EchoConstants.CENTER (the default)
• EchoConstants.BOTTOM

getWidth

public int getWidth()

This returns the width of the backgroundImage.

Specified by:

getWidth in interface nextapp.echo.ImageReference

Overrides:

getWidth in class EncodedImageReference

See Also:

ImageReference.getWidth()

getX

public int getX()

The x position where the etxt will be drawn.

Returns:

int - The x position where the etxt will be drawn.

getY

public int getY()

The y position where the etxt will be drawn.

Returns:

int - The y position where the etxt will be drawn.

isBestQuality

public boolean isBestQuality()

Returns true if the image produce is of the best quality.

Returns:

boolean - true if the image produce is of the best quality.

setBackgroundImage

public void setBackgroundImage(java.awt.Image image)

Sets the background image to be used

Parameters:

image - - the background image to be used

setBackgroundImage

public void setBackgroundImage(java.lang.String imageFileName)

Sets the background image by loading from an image file.

Parameters:

imageFileName - - the background image file to be used

setBackgroundImage

public void setBackgroundImage(java.net.URL imageURL)

Sets the background image by loading from an image URL.

Parameters:

imageURL - - the background image URL to be used

setBestQuality

public void setBestQuality(boolean b)

Set this to true if you want the best quality images to be drawn. This setting affects the rendering hints used during image drawing.

Parameters:

b -

setHorizontalAlignment

public void setHorizontalAlignment(int i)

Sets the horizontal alignment of the text relative to the x,y drawing point.

Parameters:

i - - The horizontal alignment of the text relative to the x,y drawing point, one of the following values:

• EchoConstants.LEFT
• EchoConstants.CENTER (the default)
• EchoConstants.RIGHT

setReplacementImageAlignment

public void setReplacementImageAlignment(int i)

Sets the alignment of the replacement images within the AttributedString. This can be EchoConstants.TOP, EchoConstants.CENTER or EchoConstants.BOTTOM

Parameters:

i -

setReplacementImages

public void setReplacementImages(java.awt.Image[] images)

Sets the array of replacement images that will be substituted for the Unicode replacement character u'FFFC'. These are replaced in a round-robin fashion, for each Unicode replacement character in the AttribuedtString. This can be a null array and hence no replacement will be done.

Parameters:

images -

See Also:

for more details

setString

public void setString(java.text.AttributedString string)

This is the AttributedString to be drawn onto the image. This can be null.

Parameters:

string -

setTextAngle

public void setTextAngle(int i)

Sets the text angle in degrees to be used.

Parameters:

i - int - the text angle to use.,

setVerticalAlignment

public void setVerticalAlignment(int i)

Sets the vertical alignment of the text relative to the x,y drawing point.

Parameters:

i - - The vertical alignment of the text relative to the x,y drawing point, one of the following values:

• EchoConstants.TOP
• EchoConstants.CENTER (the default)
• EchoConstants.BOTTOM

setX

public void setX(int i)

Sets the X position to draw the text on the image. If this is set to Integer.MAX_VALUE then the text will be centered within the background image.

Parameters:

i -

setY

public void setY(int i)

Sets the y position for drawing the text on the image. If this is set to Integer.MAX_VALUE then the text will be centered within the background image.

Parameters:

i -

getAttributedString

public static java.text.AttributedString getAttributedString(java.lang.String s)

Returns an AttributedString with no color or font information

Parameters:

s -

Returns:

AttributedString

getAttributedString

public static java.text.AttributedString getAttributedString(java.lang.String s,
                                                             nextapp.echo.Color foreground,
                                                             nextapp.echo.Font font)

Returns an AttributedString with the specified forground color and font based on nextapp.echo.* visual objects.

Parameters:

s - - must not be null

foreground - - can be null

font - - can be null

Returns:

AttributedString

getScaleOption

public int getScaleOption()

Returns the scaling option in effect.

Returns:

the scaling option in effect.

setScaleOption

public void setScaleOption(int scalingOption)

Sets the scaling option that will be used to draw the background image. If the text of the TextImageReference is to large for the background image, then the image will be scaled up to the requireed size, using this scaling option.

Parameters:

scalingOption - the new scaling option

getInsets

public nextapp.echo.Insets getInsets()

Returns the Insets in use

Returns:

the Insets in use

setInsets

public void setInsets(nextapp.echo.Insets insets)

Sets the Insets between the text and the background image outer edge.

Parameters:

insets - the Insets between the text and the background image outer edge.

toString

public java.lang.String toString()

See Also:

Object.toString()