com.ccg.awt
Class MultiLineText

java.lang.Object
  com.ccg.awt.MultiLineText

public class MultiLineText
extends Object

Class to draw text onto a graphic surface which may have multiple lines.

The java.awt package does not come with methods for drawing multiple lines of text onto a graphical surface. The purpose of this class is to simplify the process of drawing text onto a graphical surface and provides the following features:

• It can parse multiple lines from a single string.
• It can compute the width and height required to draw all of the lines of text.
• It can align the text within its drawing area (left, right or center).
• It can be combined with a Align object and nicely drawn.

Since:

1.0

Version:

$Revision: 1.3 $

Author:

$Author: pkb $

See Also:

Align

Field Summary

static int	CENTER Constant used to indicate CENTER alignment.
static int	LEFT Constant used to indicate LEFT alignment.
static int	RIGHT Constant used to indicate RIGHT alignment.

Constructor Summary

MultiLineText()
Default constructor for the object.

MultiLineText(String[] lines, int align)
Construct the object with some lines of text.

Method Summary

static String[]	breakString(String text) Break a string up into an array of strings.
void	draw(Graphics g, int x, int y) Draw the multi line text contained at the position specified.
int	getAlign() Get how the text should be aligned when drawn.
FontMetrics	getFontMetrics() Get the FontMetrics used to compute text size.
int	getHeight() Get the height necessary to draw all lines.
String	getLine(int index) Get one of the text lines which are displayed.
int	getLineLength(int index) Get the length in pixels of one of the lines of text.
int	getNumLines() Get the number of lines to display.
int	getWidth() Get the width necessary to draw all lines.
boolean	isSizeKnown() Indicates whether the size is known yet.
protected boolean	recompute() Recomputes area to draw all text.
void	setAlign(int val) Set how the text should be aligned when drawn.
boolean	setAlign(String val) Set the alignment based on the contents of a string.
void	setFontMetrics(FontMetrics val) Set the FontMetrics used to compute text size.
void	setLines(String[] val) Set the text lines which are displayed.
void	setNewLines(String lines) Parse a single line into multiple lines.

Methods inherited from class java.lang.Object

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

Field Detail

CENTER

public static final int CENTER

Constant used to indicate CENTER alignment. This constant is used when you want center alignment. This can be used for both horizontal or vertical alignment. This means that the rectangle which bounds your text will be centered to the horizontal and/or vertical anchor point.

Since:

1.0

See Also:

setAlign(int), Constant Field Values

LEFT

public static final int LEFT

Constant used to indicate LEFT alignment. This constant is used when you want left alignment. This means that the left side of the rectangle which bounds your text will be set to the horizontal anchor point.

Since:

1.0

See Also:

setAlign(int), Constant Field Values

RIGHT

public static final int RIGHT

Constant used to indicate RIGHT alignment. This constant is used when you want right alignment. This means that the right side of the rectangle which bounds your text will be set to the horizontal anchor point.

Since:

1.0

See Also:

setAlign(int), Constant Field Values

Constructor Detail

MultiLineText

public MultiLineText()

Default constructor for the object.

Constructed in this fashion, nothing will be drawn until text is assigned (and the width and height will both be 0).

Since:

1.0

See Also:

setNewLines(java.lang.String), setLines(java.lang.String[])

MultiLineText

public MultiLineText(String[] lines,
                     int align)

Construct the object with some lines of text. Construction the object in this fashion will enable you to immediately draw(java.awt.Graphics, int, int) the object. However, you won't be able to retrieve height or width information until you specify a FontMetrics object.

Parameters:

lines - An array of strings (one string per line). Null entries are treated the same a "" and result in blank lines of output. You may pass null (for no output/size).

align - The alignment mode you wish to set (CENTER, LEFT or RIGHT).

Since:

1.0

See Also:

draw(java.awt.Graphics, int, int)

Method Detail

breakString

public static String[] breakString(String text)

Break a string up into an array of strings. This method looks at a string to see if it contains any new line ("\n") characters. If the string does contain new line characters, an array of strings will be created where each element in the array contains one line from the original array (with the "\n" character removed). For example, if you pass "Hello\n\nWorld!", you'll get back a 3 element array { "Hello", "", "World!" }. Here are some of the rules:

• A new line which starts the string or immediately follows another newline, will trigger the addition of a blank line (""). For example: "\nHello" results in { "", "Hello"}, and "Hello\n\nWorld" results in { "Hello", "", "World" }.
• If the last character of the string contains a new line, it will be ignored unless the original line is exactly "\n". For example: "Hello\nWorld\n" results in { "Hello", "World" }, but "\n" results in { "" }.
• It is possible that you'll get an array back with exactly one element. This happens if there is exactly one new line character at the end of the string.

Parameters:

s - String to check and break apart (its OK to pass null)

Returns:

null if you pass null or a string which doesn't contain any new line ("\n") characters. Otherwise a array of strings.

Since:

1.0

See Also:

draw(java.awt.Graphics, int, int)

draw

public void draw(Graphics g,
                 int x,
                 int y)

Draw the multi line text contained at the position specified. This method lets you specify a (x,y) coordinate and then this object will take care of drawing the text for you. Since it uses the Font which is currently set for the graphics object, its possible that the size necessary to draw the text will change. That is, width and height may return new values after invoking this method.

You need to specify the top left corner where you want the text drawn. Think of the lines of text occupying a rectangular region - the (x,y) you specify will be treated as the upper left corner of where this rectangular region should be located.

Since this method invokes setFontMetrics(java.awt.FontMetrics) prior to drawing the text, you do not need to set the FontMetrics object prior to using this method. In other words, it is always safe to call this method.

Parameters:

g - The Graphics object to draw with.

x - The offset from the left side to the "drawing area". Text will not appear to the left of this point.

y - The offset from the top to the "drawing area". Text will not appear above this point.

Since:

1.0

See Also:

breakString(java.lang.String)

recompute

protected boolean recompute()

Recomputes area to draw all text. This method is used internally when the object needs to recompute the values necessary to draw the text.

Returns:

true if able to compute values, false if not.

Since:

1.0

See Also:

setFontMetrics(java.awt.FontMetrics), setLines(java.lang.String[])

isSizeKnown

public boolean isSizeKnown()

Indicates whether the size is known yet.

We can't compute the size necessary for the text we know what FontMetrics to use. This method lets you know that the getWidth(), getHeight(), and getLineLength(int) methods will return valid values.

Returns:

true if the size is known.

Since:

1.0

See Also:

setFontMetrics(java.awt.FontMetrics)

setFontMetrics

public void setFontMetrics(FontMetrics val)

Set the FontMetrics used to compute text size. Note, you don't have to do this prior to using the draw(java.awt.Graphics, int, int) method (it will invoke this method if necessary). However, you do need to use this method before getWidth(), getHeight() or getLineLength(int) will return valid information.

Parameters:

val - New FontMetrics value to assign.

See Also:

getFontMetrics()

getFontMetrics

public FontMetrics getFontMetrics()

Get the FontMetrics used to compute text size.

Returns:

Current FontMetrics value assigned.

See Also:

setFontMetrics(java.awt.FontMetrics)

setNewLines

public void setNewLines(String lines)

Parse a single line into multiple lines. This method is just a "easy access" method. It is the same as setLines(breakString(lines). This allows you to pass a single string like "Hello\nWorld" instead of an array of strings { "Hello", "World" }.

Parameters:

text - A single string which may new line characters ("\n") to separate each line.

Since:

1.0

See Also:

breakString(java.lang.String)

setLines

public void setLines(String[] val)

Set the text lines which are displayed. This method allows one to specify the lines of text to display as an array of strings. You may pass null if you don't want any text displayed. It should be noted that we will clone the array you pass, so that if you modify the contents of the original array passed, it will NOT affect the computations (or what is displayed) by this object.

Parameters:

val - New String[] value to assign (null is OK).

See Also:

getLine(int)

getLine

public String getLine(int index)

Get one of the text lines which are displayed.

Parameters:

index - Which line you want to retrieve (in the range of 0-getNumLines()). You can pass a index which is too large and get null back - don't pass negative values though.

Returns:

Current String[] value assigned.

See Also:

setLines(java.lang.String[]), getNumLines()

getLineLength

public int getLineLength(int index)

Get the length in pixels of one of the lines of text. After you draw the text on the screen (or explicitly set the FontMetrics), you can retrieve the length (in pixels) of each line using this method. In other words, this method only returns valid information if isSizeKnown() returns true.

Parameters:

index - Which line you want to retrieve the length of (in the range of 0-getNumLines()). You can pass a index which is too large and get -1 back - don't pass negative values though.

Returns:

The length of the line (in pixels) the last time the setFontMetrics(java.awt.FontMetrics) was invoked or the object was drawn).

Since:

1.0

See Also:

getLine(int)

getNumLines

public int getNumLines()

Get the number of lines to display.

Returns:

Number of text lines which we display.

Since:

1.0

See Also:

getLine(int)

getWidth

public int getWidth()

Get the width necessary to draw all lines. After you draw the text on the screen (or explicitly set the FontMetrics), you can retrieve the width (in pixels) required to draw all of the lines of text using this method. In other words, this method only returns valid information if isSizeKnown() returns true.

Returns:

Width of area to draw all lines of text.

See Also:

getHeight()

getHeight

public int getHeight()

Get the height necessary to draw all lines. After you draw the text on the screen (or explicitly set the FontMetrics), you can retrieve the height (in pixels) required to draw all of the lines of text using this method. In other words, this method only returns valid information if isSizeKnown() returns true.

Returns:

Height of area to draw all lines of text.

See Also:

getWidth()

setAlign

public void setAlign(int val)

Set how the text should be aligned when drawn.

This method allows you to specify how the lines of text are aligned as they are drawn within the computed drawing area.

Parameters:

val - Desired alignment (LEFT, CENTER, or RIGHT).

See Also:

getAlign()

setAlign

public boolean setAlign(String val)

Set the alignment based on the contents of a string. This method looks at the first character of a string and sets the alignment value accordingly. The alignment will be CENTER if the string passed starts with "c" or "C". It will be LEFT if the string passed starts with "l" or "L". It will be RIGHT if the string starts with "r" or "R". If you pass null, a zero length string, or a string which doesn't start with one of the previously mentioned characters, then nothing will be done and this method will return false.

This method returns true if the string passed was considered valid.

Parameters:

val - The alignment string to pass (you can pass null or "" - but you'll get false back).

Returns:

true if we used the value in the string, false if not.

Since:

1.0

See Also:

setAlign(int)

getAlign

public int getAlign()

Get how the text should be aligned when drawn.

Returns:

Current alignment value assigned (LEFT, CENTER, or RIGHT).

See Also:

setAlign(int)