com.flagstone.transform.text
Class TextSpan

java.lang.Object
  com.flagstone.transform.text.TextSpan

All Implemented Interfaces:

Copyable<TextSpan>, SWFEncodeable

public final class TextSpan
extends Object
implements SWFEncodeable, Copyable<TextSpan>

TextSpan is used to display a group of characters with a selected font and colour. TextSpan objects are used in DefineText and DefineText2 to display a line or block of text.

TextSpan contains a list of Character objects which identify the glyphs that will be displayed along with style information that sets the colour of the text, the size of the font and the relative placement of the line within a block of text.

Whether the alpha channel in the colour needs to be specified depends on the class the Text is added to. The DefineText2 class supports transparent text while DefineText class does not.

The x and y offsets are used to control how several TextSpan objects are laid out to create a block of text. The y offset is specified relative to the bottom edge of the bounding rectangle, which is actually closer to the top of the screen as the direction of the y-axis is from the top to the bottom of the screen. In this respect Flash is counter-intuitive. Lines with higher offset values are displayed below lines with lower offsets.

The x and y offsets are also optional and may be set to the constant VALUE_NOT_SET when more than one TextSpan object is created. If the y offset is not specified then a TextSpan object is displayed on the same line as the previous TextSpan. If the x offset is not specified then the TextSpan is displayed after the previous TextSpan. This makes it easy to lay text out on a single line.

Similarly the font and colour information is optional. The values from a previous TextSpan object will be used if they are not set.

The creation and layout of the glyphs to create the text is too onerous to perform from scratch. It is easier and more convenient to use the TextTable class to create the TextSpan objects.

See Also:

DefineText, DefineText2, TextTable, Font

Constructor Summary

TextSpan(Integer uid, Integer aHeight, Color aColor, Integer xOffset, Integer yOffset, List<GlyphIndex> list)
Creates a Text object, specifying the colour and position of the following Text.

TextSpan(SWFDecoder coder, Context context)
Creates and initialises a TextSpan object using values encoded in the Flash binary format.

TextSpan(TextSpan object)
Creates and initialises a TextSpan object using the values copied from another TextSpan object.

Method Summary

TextSpan	add(GlyphIndex aCharacter) Adds an Character object to the list of characters.
protected int	advanceBits() The number of bits used to encode the advances.
TextSpan	copy() Creates a complete copy of this object.
void	encode(SWFEncoder coder, Context context) Encode an object to the Flash binary format.
List<GlyphIndex>	getCharacters() Returns the list of characters to be displayed.
Color	getColor() Get the colour used to display the text.
Integer	getHeight() Get the height of the text.
Integer	getIdentifier() Get the identifier of the font in which the text will be displayed.
Integer	getOffsetX() Get the location of the start of the text relative to the left edge of the bounding rectangle in twips.
Integer	getOffsetY() Get the location of the start of the text relative to the bottom edge of the bounding rectangle in twips.
protected int	glyphBits() The number of bits used to encode the glyph indices.
int	prepareToEncode(Context context) Prepare an object for encoding, returning the expected size of an object when it is encoded.
void	setCharacters(List<GlyphIndex> list) Sets the list of characters to be displayed.
void	setColor(Color aColor) Sets the colour of the font in which the text will be displayed.
void	setHeight(Integer aHeight) Sets the height of the text in twips.
void	setIdentifier(Integer uid) Sets the identifier of the font in which the text will be displayed.
void	setOffsetX(Integer offset) Sets the location of the start of the text relative to the left edge of the bounding rectangle in twips.
void	setOffsetY(Integer offset) Sets the location of the start of the text relative to the bottom edge of the bounding rectangle in twips.
String	toString()

Methods inherited from class java.lang.Object

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

Constructor Detail

TextSpan

public TextSpan(SWFDecoder coder,
                Context context)
         throws IOException

Creates and initialises a TextSpan object using values encoded in the Flash binary format.

Parameters:

coder - an SWFDecoder object that contains the encoded Flash data.

context - a Context object used to manage the decoders for different type of object and to pass information on how objects are decoded.

Throws:

IOException - if an error occurs while decoding the data.

TextSpan

public TextSpan(Integer uid,
                Integer aHeight,
                Color aColor,
                Integer xOffset,
                Integer yOffset,
                List<GlyphIndex> list)

Creates a Text object, specifying the colour and position of the following Text.

Parameters:

uid - the identifier of the font that the text will be rendered in. Must be in the range 1..65535.

aHeight - the height of the text in the chosen font. Must be in the range 1..65535.

aColor - the colour of the text.

xOffset - the location of the text relative to the left edge of the bounding rectangle enclosing the text.

yOffset - the location of the text relative to the bottom edge of the bounding rectangle enclosing the text.

list - a list of Character objects. Must not be null.

TextSpan

public TextSpan(TextSpan object)

Creates and initialises a TextSpan object using the values copied from another TextSpan object.

Parameters:

object - a TextSpan object from which the values will be copied.

Method Detail

getIdentifier

public Integer getIdentifier()

Get the identifier of the font in which the text will be displayed.

Returns:

the unique identifier of the font.

getColor

public Color getColor()

Get the colour used to display the text.

Returns:

the text colour.

getOffsetX

public Integer getOffsetX()

Get the location of the start of the text relative to the left edge of the bounding rectangle in twips.

Returns:

the left offset.

getOffsetY

public Integer getOffsetY()

Get the location of the start of the text relative to the bottom edge of the bounding rectangle in twips.

Returns:

the top offset.

getHeight

public Integer getHeight()

Get the height of the text.

Returns:

the size, in twips, of the font used to display the text.

setIdentifier

public void setIdentifier(Integer uid)

Sets the identifier of the font in which the text will be displayed.

Parameters:

uid - the identifier of the font that the text will be rendered in. Must be in the range 1..65535.

setColor

public void setColor(Color aColor)

Sets the colour of the font in which the text will be displayed.

Parameters:

aColor - the colour of the text.

setOffsetX

public void setOffsetX(Integer offset)

Sets the location of the start of the text relative to the left edge of the bounding rectangle in twips.

Parameters:

offset - the location of the text relative to the left edge of the bounding rectangle enclosing the text. Must be in the range -32768..32767 or null if no offset is specified.

setOffsetY

public void setOffsetY(Integer offset)

Sets the location of the start of the text relative to the bottom edge of the bounding rectangle in twips.

Parameters:

offset - the location of the text relative to the bottom edge of the bounding rectangle enclosing the text. Must be in the range -32768..32767 or null if no offset is specified.

setHeight

public void setHeight(Integer aHeight)

Sets the height of the text in twips.

Parameters:

aHeight - the height of the text in the chosen font. Must be in the range 0..65535.

add

public TextSpan add(GlyphIndex aCharacter)

Adds an Character object to the list of characters.

Parameters:

aCharacter - an Character object. Must not be null.

Returns:

this object.

getCharacters

public List<GlyphIndex> getCharacters()

Returns the list of characters to be displayed.

Returns:

the list of Character objects.

setCharacters

public void setCharacters(List<GlyphIndex> list)

Sets the list of characters to be displayed.

Parameters:

list - a list of Character objects. Must not be null.

copy

public TextSpan copy()

Creates a complete copy of this object.

Specified by:

copy in interface Copyable<TextSpan>

Returns:

a deep-copy of this object. New instances of mutable objects are copied and immutable instances are shared.

toString

public String toString()

Overrides:

toString in class Object

prepareToEncode

public int prepareToEncode(Context context)

Prepare an object for encoding, returning the expected size of an object when it is encoded. This method also used to initialise variables, such as offsets and flags that will be used when the object is encoded. Generally the method returns the size in bytes, however when called on objects that use bit fields such as shapes the methods will return the size in bits.

Specified by:

prepareToEncode in interface SWFEncodeable

Parameters:

context - an Context that allows information to be passed between objects to control how they are initialised for encoding.

Returns:

the size of the object when it is encoded.

encode

public void encode(SWFEncoder coder,
                   Context context)
            throws IOException

Encode an object to the Flash binary format.

Specified by:

encode in interface SWFEncodeable

Parameters:

coder - an SWFEncoder object.

context - an Context that allows information to be passed between objects to control how they are initialised for encoding.

Throws:

IOException - if an error occurs while encoding the object.

glyphBits

protected int glyphBits()

The number of bits used to encode the glyph indices.

Returns:

the number of bits used to encode each glyph index.

advanceBits

protected int advanceBits()

The number of bits used to encode the advances.

Returns:

the number of bits used to encode each advance.