com.rolemodelsoft.drawlet.util
Class BasicStringRenderer

java.lang.Object
  |
  +--com.rolemodelsoft.drawlet.util.BasicStringRenderer

Direct Known Subclasses:

BasicStringComposer

public class BasicStringRenderer

extends java.lang.Object

implements StringRenderer

This provides basic default functionality for StringRenderer. It doesn't do any wrapping. However, it handles tabs and new-lines and provides hooks for a lot of subclasses which might want to handle more complicated StringRendering. NOTE: If a font is not supplied when constructed, it will be determined by default or by the current font the first time it is asked to paint, whichever comes first. There are basically two main responsibilities of this class: 1. compose the characters of a string into lines and information about those lines that will be meaningful before, during, and after displaying them. 2. paint the parts of the composed string that should be visible when given a given area and medium on which to display. These two responsibilities are intertwined for efficiency. Nothing will be composed before it is necessary to either paint or respond to some query. It is very possible that only a small portion of the string will ever be composed, e.g. if only asked to paint the first few lines of a long string with no other action that would change the viewing area to display more. On the other hand, just because something wasn't ever completely viewed, doesn't mean it will not be totally composed (e.g. if asked for width, all lines must be composed in order to figure out what line is widest). Subclasses may provide for constraints that will make various scenarios more or less efficient as they change the amount of services dependent on composition.

Field Summary

protected static int	ALL_VERTICAL Symbolic name for identifying all vertical space to be composed or painted.
protected int	begin The following are all used to keep track of running counters when composing lines.
protected int[]	begins These hold information necessary to determine the beginning, end, and width of each line along with which indexes of characters within that line need manual intervention when displaying (e.g.
protected int	end The following are all used to keep track of running counters when composing lines.
protected int[]	ends
protected int	height The following are all used to keep track of running counters when composing lines.
protected int	last The following are all used to keep track of running counters when composing lines.
protected int[][]	manuals
protected java.awt.FontMetrics	metrics NOTE: We use lazy initialization for metrics to avoid problems of 1.
protected int	next The following are all used to keep track of running counters when composing lines.
protected static int	NO_INDEX Symbolic name for result of not finding an index when searched.
protected int[]	specials Provides a map of character values to types of special handling (see static attributes of StringRenderer) which are bitORed together.
protected int	startX This determines the starting x location to begin rendering the string;
protected int	startY This determines the starting y location to begin rendering the string;
protected java.lang.String	string
protected int	width The following are all used to keep track of running counters when composing lines.
protected int[]	widths

Fields inherited from interface com.rolemodelsoft.drawlet.util.StringRenderer

BREAK, BREAK_AFTER, BREAK_BEFORE, END_ABSORB, END_DELAY, NEW_LINE, NO_FONT, VERTICAL, VERTICAL_MOVE

Constructor Summary

BasicStringRenderer(java.lang.String string)
Answer an instance prepared to render a String.

BasicStringRenderer(java.lang.String string, java.awt.Font font)
Answer an instance prepared to render the given string using a particular font.

Method Summary

protected void	absorbEnd() Adjusts the theoretical end of the line to absorb whitespace in order to speed up display of the lines later.
protected void	addLine() Record the current settings as the end of a line.
protected void	adjustWidthForSpecial(java.lang.String string, int index) Adjust the width to account for the special character at the specified index.
protected boolean	areAllAbsorbed(int start, int stop) Answer whether all of the characters in the string between start (inclusive) and stop (exclusive) are END_ABSORBed characters.
protected void	beginNextLine() Set up to compose the next line.
protected void	closeLastLine() Make the last/pending line into a "real one" if indicated.
protected void	compose() Compose the text in such a way as to produce all lines necessary to display text properly.
protected void	compose(int ySize) Compose the text in such a way as to produce the lines necessary to display text up to the given vertical coordinate.
protected void	compose(int yBegin, int yEnd) Compose the text in such a way as to produce the lines necessary to display text between the given vertical coordinates.
protected void	composeAll() Assume something has changed that makes the current composition bogus.
protected void	composeIfNecessary() If no composing has happened yet, make it happen.
protected java.awt.Font	defaultFont() Answer the default/initial value for the Font.
protected java.awt.FontMetrics	defaultMetrics() Answer the default/initial value for metrics.
protected int[]	defaultSpecials() Answer the default/initial value for the array where characters can be marked as special.
protected int	defaultStartX() Answer the default/initial value for the x coordinate.
protected int	defaultStartY() Answer the default/initial value for the y coordinate.
protected int	getBaseline() Answer the baseline (coordinates in y direction from top) to display text.
java.awt.Font	getFont() Answer the Font the receiver is using.
protected int	getLineHeight() Answer the height of a line.
protected java.awt.FontMetrics	getMetrics() Answer the font metrics the receiver is using.
java.lang.String[]	getRawStringLines() Answers an array of the substrings, one for each line.
protected int	getSpecialFlags(char c) Answer the flags associated with a particular character.
protected int	getSpecialFlags(java.lang.String string, int index) Answer the flags associated with a particular character.
java.lang.String	getString() Answer the String associated with the receiver.
int	getStringHeight() Answer the height of the composed string.
java.lang.String[]	getStringLines() Answers an array of the substrings, one for each line.
int	getStringWidth() Answer the width of the composed string.
protected void	handleManually(int index) Flags the special character at index as one to display manually.
protected boolean	handleSpecial(java.lang.String string, int index) Handles the special character at index during composition.
protected int	indexOfSpecial(java.lang.String string, int start, int stop) Answers the index of the first special character in the specified range which is not END_ABSORB only, or -1 if none.
protected boolean	isFullyComposed() Answer whether the string has been fully composed.
protected void	newLine() Record the current settings as the end of a line, and set up to scan the next line.
protected int	nextTabStop(int x) Answer the next tab stop after the x position.
void	paint(java.awt.Graphics g) Paints the string.
void	paint(java.awt.Graphics g, int x, int y) Paints the string starting at the top left specified.
protected int	paintSpecial(java.awt.Graphics g, int index, int x, int y) Paints the special character at the specified index at the appropriate place.
protected void	paintTextBetween(java.awt.Graphics g, int topY, int bottomY) Paints the string between the given horizontal window.
protected void	reset() Reset the receiver to start composing.
protected int	scanToSpecial(java.lang.String string, int start, int stop) Scan the characters from start to stop, adding to the width until a special character is found.
void	setFont(java.awt.Font font) Set the receiver up to compose and display based on the given font.
void	setString(java.lang.String newString) Set the receiver up to display the string.
java.lang.String	toString() Returns the String representation of the receiver's values.
protected void	verifyMetrics(java.awt.Graphics g) Verify that the metrics used to compose the text is consistent with the font/metrics about to be used to render the string.

Methods inherited from class java.lang.Object

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

Field Detail

string

protected java.lang.String string

metrics

protected java.awt.FontMetrics metrics

NOTE: We use lazy initialization for metrics to avoid problems of 1. changing metrics mid-composition (as line height etc. is affected by the metrics), 2. performance problems of calculating default when one was not explicitly set. 3. delaying identification of metrics (and resetting of all composition-related attributes) until composition actually begins.

startX

protected int startX

This determines the starting x location to begin rendering the string;

startY

protected int startY

This determines the starting y location to begin rendering the string;

begins

protected int[] begins

These hold information necessary to determine the beginning, end, and width of each line along with which indexes of characters within that line need manual intervention when displaying (e.g. tabs are usually not displayed as characters, but rather an amount of space determined based on current placement must be determined... other special characters must also need special handling). All integers in these arrays (except widths) indicate indexes of characters within the entire string;

ends

protected int[] ends

widths

protected int[] widths

manuals

protected int[][] manuals

specials

protected int[] specials

Provides a map of character values to types of special handling (see static attributes of StringRenderer) which are bitORed together.

begin

protected int begin

The following are all used to keep track of running counters when composing lines. NOTE: "end", "next", "last" are often manipulated to a point that clouds their literal meaning. For example, "end" (of line) is set to be the last character of the string until it is determined that this assumption is invalid.

end

protected int end

The following are all used to keep track of running counters when composing lines. NOTE: "end", "next", "last" are often manipulated to a point that clouds their literal meaning. For example, "end" (of line) is set to be the last character of the string until it is determined that this assumption is invalid.

next

protected int next

The following are all used to keep track of running counters when composing lines. NOTE: "end", "next", "last" are often manipulated to a point that clouds their literal meaning. For example, "end" (of line) is set to be the last character of the string until it is determined that this assumption is invalid.

last

protected int last

The following are all used to keep track of running counters when composing lines. NOTE: "end", "next", "last" are often manipulated to a point that clouds their literal meaning. For example, "end" (of line) is set to be the last character of the string until it is determined that this assumption is invalid.

width

protected int width

The following are all used to keep track of running counters when composing lines. NOTE: "end", "next", "last" are often manipulated to a point that clouds their literal meaning. For example, "end" (of line) is set to be the last character of the string until it is determined that this assumption is invalid.

height

protected int height

The following are all used to keep track of running counters when composing lines. NOTE: "end", "next", "last" are often manipulated to a point that clouds their literal meaning. For example, "end" (of line) is set to be the last character of the string until it is determined that this assumption is invalid.

NO_INDEX

protected static int NO_INDEX

Symbolic name for result of not finding an index when searched.

ALL_VERTICAL

protected static int ALL_VERTICAL

Symbolic name for identifying all vertical space to be composed or painted.

Constructor Detail

BasicStringRenderer

public BasicStringRenderer(java.lang.String string)

Answer an instance prepared to render a String.

Parameters:

string - the string to render

BasicStringRenderer

public BasicStringRenderer(java.lang.String string,
                           java.awt.Font font)

Answer an instance prepared to render the given string using a particular font.

Parameters:

string - the string to render.

font - the font to use when rendering.

Method Detail

absorbEnd

protected void absorbEnd()

Adjusts the theoretical end of the line to absorb whitespace in order to speed up display of the lines later. Width of characters are still accounted for.

addLine

protected void addLine()

Record the current settings as the end of a line. Leave the running counters alone so others may use them before preparing to start the next line. Used during composition.

See Also:

beginNextLine

adjustWidthForSpecial

protected void adjustWidthForSpecial(java.lang.String string,
                                     int index)

Adjust the width to account for the special character at the specified index. Used during composition.

Parameters:

string - string to check

index - the index of the special character

areAllAbsorbed

protected boolean areAllAbsorbed(int start,
                                 int stop)

Answer whether all of the characters in the string between start (inclusive) and stop (exclusive) are END_ABSORBed characters.

Parameters:

start - an integer representing the starting index, inclusive.

stop - an integer representing the stopping index, exclusive.

Returns:

boolean

beginNextLine

protected void beginNextLine()

Set up to compose the next line. Reset the running counters and buffers which may be needed. Used during composition. Often after addLine().

See Also:

addLine()

closeLastLine

protected void closeLastLine()

Make the last/pending line into a "real one" if indicated. This will be only when the string is empty.

compose

protected void compose()

Compose the text in such a way as to produce all lines necessary to display text properly.

compose

protected void compose(int ySize)

Compose the text in such a way as to produce the lines necessary to display text up to the given vertical coordinate.

Parameters:

ySize - the vertical coordinate at which we'll stop composing.

compose

protected void compose(int yBegin,
                       int yEnd)

Compose the text in such a way as to produce the lines necessary to display text between the given vertical coordinates.

Parameters:

yBegin - the vertical coordinate at which we need to begin composing.

yEnd - the vertical coordinate at which we'll stop composing.

composeAll

protected void composeAll()

Assume something has changed that makes the current composition bogus. Do it again.

composeIfNecessary

protected void composeIfNecessary()

If no composing has happened yet, make it happen. If something has changed since the last time the string was composed, do it again. No matter what, make sure the entire string is composed.

defaultFont

protected java.awt.Font defaultFont()

Answer the default/initial value for the Font.

Returns:

the default/initial value for the Font.

defaultMetrics

protected java.awt.FontMetrics defaultMetrics()

Answer the default/initial value for metrics.

Returns:

the default/initial value for metrics.

defaultSpecials

protected int[] defaultSpecials()

Answer the default/initial value for the array where characters can be marked as special. By default, we assume ASCII. Subclasses can easily override this but may wish to address special characters in a more compact way (perhaps as a different implementer of the base interface).

Returns:

an array of ints.

defaultStartX

protected int defaultStartX()

Answer the default/initial value for the x coordinate.

Returns:

the default/initial value for the x coordinate.

defaultStartY

protected int defaultStartY()

Answer the default/initial value for the y coordinate.

Returns:

the default/initial value for the y coordinate.

getBaseline

protected int getBaseline()

Answer the baseline (coordinates in y direction from top) to display text. NOTE: Assumes metrics have been set. Used during painting.

Returns:

an integer representing the baseline from which to display text.

getFont

public java.awt.Font getFont()

Answer the Font the receiver is using.

Specified by:

getFont in interface StringRenderer

Returns:

the Font the receiver is using.

getLineHeight

protected int getLineHeight()

Answer the height of a line. Used during composition.

Returns:

an integer representing the height of a line.

getMetrics

protected java.awt.FontMetrics getMetrics()

Answer the font metrics the receiver is using.

Returns:

the FontMetrics the receiver is using.

getRawStringLines

public java.lang.String[] getRawStringLines()

Answers an array of the substrings, one for each line. Don't strip off any ending white space. NOTE: This will probably be changed to return an Enumeration or Iterator.

Specified by:

getRawStringLines in interface StringRenderer

Returns:

an array of Strings.

getSpecialFlags

protected int getSpecialFlags(char c)

Answer the flags associated with a particular character.

Parameters:

c - the character.

Returns:

the flags associated with the given character, encoded in an integer.

getSpecialFlags

protected int getSpecialFlags(java.lang.String string,
                              int index)

Answer the flags associated with a particular character.

Parameters:

string - string to check.

index - point to look at.

Returns:

the flags associated with the given character, encoded in an integer.

getString

public java.lang.String getString()

Answer the String associated with the receiver.

Specified by:

getString in interface StringRenderer

Returns:

the String associated with the receiver.

getStringHeight

public int getStringHeight()

Answer the height of the composed string.

Specified by:

getStringHeight in interface StringRenderer

Returns:

an integer representing the height of the composed string.

getStringLines

public java.lang.String[] getStringLines()

Answers an array of the substrings, one for each line. This will strip off any ending characters identified as END_ABSORB. NOTE: This will probably be changed to return an Enumeration or Iterator.

Specified by:

getStringLines in interface StringRenderer

Returns:

an array of Strings.

getStringWidth

public int getStringWidth()

Answer the width of the composed string.

Specified by:

getStringWidth in interface StringRenderer

Returns:

an integer representing the width of the composed string.

handleManually

protected void handleManually(int index)

Flags the special character at index as one to display manually. Used during composition. Assumes the special character is part of current/last line composed.

Parameters:

index - index of special character to flag.

handleSpecial

protected boolean handleSpecial(java.lang.String string,
                                int index)

Handles the special character at index during composition. Answer true if a new line is necessary.

Parameters:

string - the string in which to find the special character.

index - index of special character.

Returns:

boolean whether or not a new line is necessary.

indexOfSpecial

protected int indexOfSpecial(java.lang.String string,
                             int start,
                             int stop)

Answers the index of the first special character in the specified range which is not END_ABSORB only, or -1 if none. Used during composition.

Parameters:

string - string to check.

start - starting point to look.

ending - point to look.

Returns:

an integer representing the index of the first special character.

isFullyComposed

protected boolean isFullyComposed()

Answer whether the string has been fully composed.

Returns:

a boolean value of true if the string is fully composed; false otherwise.

newLine

protected void newLine()

Record the current settings as the end of a line, and set up to scan the next line. Used during composition.

nextTabStop

protected int nextTabStop(int x)

Answer the next tab stop after the x position.

Parameters:

x - the x position from which to tab.

Returns:

an integer representing the next tab stop.

paint

public void paint(java.awt.Graphics g)

Paints the string.

Specified by:

paint in interface StringRenderer

Parameters:

g - the specified Graphics window

paint

public void paint(java.awt.Graphics g,
                  int x,
                  int y)

Paints the string starting at the top left specified.

Specified by:

paint in interface StringRenderer

Parameters:

g - the specified Graphics window.

x - the X coordinate at which to start.

y - the Y coordinate at which to start.

paintSpecial

protected int paintSpecial(java.awt.Graphics g,
                           int index,
                           int x,
                           int y)

Paints the special character at the specified index at the appropriate place. Answer the new x coordinate.

Parameters:

g - the specified Graphics window.

index - the index of the special character.

x - the x coordinate.

y - the y coordinate.

paintTextBetween

protected void paintTextBetween(java.awt.Graphics g,
                                int topY,
                                int bottomY)

Paints the string between the given horizontal window.

Parameters:

g - the specified Graphics window.

topY - int identifying the top of the area in which we would like to paint.

bottomY - int identifying the bottom of the area in which we would like to paint.

reset

protected void reset()

Reset the receiver to start composing.

scanToSpecial

protected int scanToSpecial(java.lang.String string,
                            int start,
                            int stop)

Scan the characters from start to stop, adding to the width until a special character is found. Answers the index of the first special character, or NO_INDEX if none.

Parameters:

string - string to check

start - starting point to look, inclusive

stop - stopping point to look, exclusive

Returns:

an integer representing the first special character.

setFont

public void setFont(java.awt.Font font)

Set the receiver up to compose and display based on the given font.

Specified by:

setFont in interface StringRenderer

Parameters:

font - the font to use as a base.

setString

public void setString(java.lang.String newString)

Set the receiver up to display the string.

Specified by:

setString in interface StringRenderer

Parameters:

string - the string to use as a base.

toString

public java.lang.String toString()

Returns the String representation of the receiver's values.

Overrides:

toString in class java.lang.Object

Returns:

a String representation of the receiver's values.

verifyMetrics

protected void verifyMetrics(java.awt.Graphics g)

Verify that the metrics used to compose the text is consistent with the font/metrics about to be used to render the string.

Parameters:

g - the specified Graphics window.