com.flagstone.transform
Class FSText

java.lang.Object
  extended by com.flagstone.transform.FSTransformObject
      extended by com.flagstone.transform.FSText
All Implemented Interfaces:
java.lang.Cloneable

public class FSText
extends FSTransformObject

FSText is used to display a line of text.

It contains an array of FSCharacter 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.

Attributes
identifier The identifier, in the range 1..65535, of the font object which contains the glyphs representing each character displayed. Optional. Set to 0 if the font is not being changed.
color An FSColor object describing colour of the text. Optional. Set to null if the colour is not being changed.
offsetX The offset, in twips, relative to the left side bounding rectangle of the text block where the text will be displayed. Optional. Set to zero if no indent is being specified.
offsetY The offset, in twips, relative to the bottom of the bounding rectangle of the text block where the text will be displayed. Optional. Set to the height of the font if only a single line of text is being displayed so the characters are placed correctly within the bounding rectangle defined for the text object.
height The height of the font, in twips, used to render the characters. Optional. Set to zero if the font size is not being changed.
characters An array of FSCharacter objects which identify the glyph that will be displayed along with the spacing to the next character in the line of text.

Whether the alpha channel in the colour needs to be specified depends on the class the FSText is added to. The FSDefineText2 class supports transparent text while FSDefineText class does not.

The x and y offsets are used to control how several FSText 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.

When several FSText objects are used to define a block of text using the FSDefineText or FSDefineText2 classes the attributes such as the font selected, size and colour must be specified in the first FSText object. For the remaining FSText objects these may be set to null or zero. The attributes will apply to all following FSText object until explicitly changed.

Examples

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 existing font definitions either by parsing an existing Flash file or by converting a font definition from a specification such as TrueType in order to obtain the glyphs and layout information.

1. Creating a simple string.
This examples assumes a font definition that contains glyphs for the following set of characters ' ', 'a', 'b', 'c' .... 'x', 'y', 'z'. The font used fixed size for the spacing between glyphs .e.g. Courier.

 ArrayList characters = new ArrayList();
 
 characters.add(new FSCharacter(1, 120)); // 'a'
 characters.add(new FSCharacter(0, 120)); // ' '
 characters.add(new FSCharacter(19, 120)); // 's'
 characters.add(new FSCharacter(10, 120)); // 't'
 characters.add(new FSCharacter(18, 120)); // 'r'
 characters.add(new FSCharacter(9, 120)); // 'i'
 characters.add(new FSCharacter(14, 120)); // 'n'
 characters.add(new FSCharacter(6, 120)); // 'g'
 
 // Create the string setting the height to be 12-point (240 twips) and displaying 
 // the characters in black. The text is not indented or offset.
 
 int xOffset = 0;
 int yOffset = 240;
 int fontSize = 240;
 
 FSText string = new FSText(font.getIdentifier(), FSColorTable.black(), xOffset,
                                yOffset, fontSize, characters);
 

2. Creating a block of text.
Again this examples assumes a fixed size font definition that contains glyphs for the set of characters.

 ArrayList line1 = new ArrayList();
 
 line1.add(new FSCharacter(19, 120)); // 's'
 line1.add(new FSCharacter(10, 120)); // 't'
 line1.add(new FSCharacter(18, 120)); // 'r'
 line1.add(new FSCharacter(9, 120)); // 'i'
 line1.add(new FSCharacter(14, 120)); // 'n'
 line1.add(new FSCharacter(6, 120)); // 'g'
 line1.add(new FSCharacter(0, 120)); // ' '
 line1.add(new FSCharacter(28, 120)); // '1'
 
 // Create the string setting the height to be 12-point (240 twips) and 
 // displaying the characters in black. The text is not indented or offset.
 
 int fontSize = 240;
 int yOffset = 240;
 
 FSText string1 = new FSText(font.getIdentifier(), FSColorTable.black(), 0,
                                yOffset, fontSize, line1);
 
 ArrayList line1 = new ArrayList();
 
 line2.add(new FSCharacter(19, 120)); // 's'
 line2.add(new FSCharacter(10, 120)); // 't'
 line2.add(new FSCharacter(18, 120)); // 'r'
 line2.add(new FSCharacter(9, 120)); // 'i'
 line2.add(new FSCharacter(14, 120)); // 'n'
 line2.add(new FSCharacter(6, 120)); // 'g'
 line2.add(new FSCharacter(0, 120)); // ' '
 line2.add(new FSCharacter(29, 120)); // '2'
 
 // Display the second string 'one line' height (240 twips) below the first. 
 // The font size and colour remain unchanged.
 
 yOffset += fontSize;
 
 FSText string2 = new FSText(0, yOffset, line2);
 

History

The FSText class represents both the TextRecordType0 and TextRecordType1 structures from the Macromedia Flash (SWF) File Format Specification. It was introduced in Flash 1.


Field Summary
static int ANSI
          Defines that the font character set is based on the ANSI UTF-8 standard which supports standard ASCII encoded strings.
static int Japanese
           
static int Korean
           
static int Latin
           
static int SimplifiedChinese
           
static int SJIS
          Defines that the font character set is based on the SJIS standard for representing Kanji characters.
static int TraditionalChinese
           
static int Unicode
          Defines that the font character set is based on the Unicode standard.
 
Constructor Summary
FSText(FSCoder coder)
          Construct an FSText object, initalizing it with values decoded from an encoded object.
FSText(FSText obj)
          Constructs an FSText object by copying values from an existing object.
FSText(int anIdentifier, FSColor aColor, int xOffset, int yOffset, int aHeight, java.util.ArrayList anArray)
          Constructs an FSText object, specifying the colour and position of the following FSText.
FSText(int xOffset, int yOffset, java.util.ArrayList anArray)
          Constructs an FSText object specifying the array of characters to be displayed and their relative placement within a block of text.
 
Method Summary
 void add(FSCharacter aCharacter)
          Adds an FSCharacter object to the array of characters.
 void appendDescription(java.lang.StringBuffer buffer, int depth)
          AppendDescription is used to present a string description of the object including all nested objects up to a specified depth.
 java.lang.Object clone()
          Creates a deep copy of the entire object.
 void decode(FSCoder coder)
           
 void encode(FSCoder coder)
           
 boolean equals(java.lang.Object anObject)
          Returns true if anObject is equal to this one.
 java.util.ArrayList getCharacters()
          Gets the array of characters to be displayed.
 FSColor getColor()
          Gets the colour of the font in which the text will be displayed.
 int getHeight()
          Gets the height of the text.
 int getIdentifier()
          Gets the identifier of the font in which the text will be displayed.
 int getOffsetX()
          Gets the location of the start of the text relative to the left edge of the bounding rectangle in twips.
 int getOffsetY()
          Gets the location of the start of the text relative to the bottom edge of the bounding rectangle in twips.
 int length(FSCoder coder)
           
 void setCharacters(java.util.ArrayList anArray)
          Sets the array of characters to be displayed.
 void setColor(FSColor aColor)
          Sets the colour of the font in which the text will be displayed.
 void setHeight(int aHeight)
          Sets the height of the text.
 void setIdentifier(int anIdentifier)
          Sets the identifier of the font in which the text will be displayed.
 void setOffsetX(int xOffset)
          Sets the location of the start of the text relative to the left edge of the bounding rectangle in twips.
 void setOffsetY(int yOffset)
          Sets the location of the start of the text relative to the bottom edge of the bounding rectangle in twips.
 
Methods inherited from class com.flagstone.transform.FSTransformObject
name, toString
 
Methods inherited from class java.lang.Object
finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

Unicode

public static final int Unicode
Defines that the font character set is based on the Unicode standard.

See Also:
Constant Field Values

SJIS

public static final int SJIS
Defines that the font character set is based on the SJIS standard for representing Kanji characters.

See Also:
Constant Field Values

ANSI

public static final int ANSI
Defines that the font character set is based on the ANSI UTF-8 standard which supports standard ASCII encoded strings.

See Also:
Constant Field Values

Latin

public static final int Latin
See Also:
Constant Field Values

Japanese

public static final int Japanese
See Also:
Constant Field Values

Korean

public static final int Korean
See Also:
Constant Field Values

SimplifiedChinese

public static final int SimplifiedChinese
See Also:
Constant Field Values

TraditionalChinese

public static final int TraditionalChinese
See Also:
Constant Field Values
Constructor Detail

FSText

public FSText(FSCoder coder)
Construct an FSText object, initalizing it with values decoded from an encoded object.

Parameters:
coder - an FSCoder containing the binary data.

FSText

public FSText(int xOffset,
              int yOffset,
              java.util.ArrayList anArray)
Constructs an FSText object specifying the array of characters to be displayed and their relative placement within a block of text. The selected font, colour of the text and height will remain unchanged from previous settings.

Parameters:
xOffset - the location of the text relative to the left edge of the bounding rectangle enclosing the block of text.
yOffset - the location of the text relative to the bottom edge of the bounding rectangle enclosing the block of text.
anArray - an array of FSCharacter objects.

FSText

public FSText(int anIdentifier,
              FSColor aColor,
              int xOffset,
              int yOffset,
              int aHeight,
              java.util.ArrayList anArray)
Constructs an FSText object, specifying the colour and position of the following FSText.

Parameters:
anIdentifier - the identifier of the font that the text will be rendered in.
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.
aHeight - the height of the text in the chosen font.
anArray - an array of FSCharacter objects.

FSText

public FSText(FSText obj)
Constructs an FSText object by copying values from an existing object.

Parameters:
obj - an FSText object.
Method Detail

getIdentifier

public int getIdentifier()
Gets the identifier of the font in which the text will be displayed.

Returns:
the identifier of the font.

getColor

public FSColor getColor()
Gets the colour of the font in which the text will be displayed.

Returns:
the colour of the text.

getOffsetX

public int getOffsetX()
Gets the location of the start of the text relative to the left edge of the bounding rectangle in twips.

Returns:
the indentation applied to the text.

getOffsetY

public int getOffsetY()
Gets the location of the start of the text relative to the bottom edge of the bounding rectangle in twips.

Returns:
the location of the text relative to the bottom of the bounding rectangle.

getHeight

public int getHeight()
Gets the height of the text.

Returns:
the height of the font used to displayed the text.

setIdentifier

public void setIdentifier(int anIdentifier)
Sets the identifier of the font in which the text will be displayed.

Parameters:
anIdentifier - the identifier of the font that the text will be rendered in.

setColor

public void setColor(FSColor 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(int xOffset)
Sets the location of the start of the text relative to the left edge of the bounding rectangle in twips.

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

setOffsetY

public void setOffsetY(int yOffset)
Sets the location of the start of the text relative to the bottom edge of the bounding rectangle in twips.

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

setHeight

public void setHeight(int aHeight)
Sets the height of the text.

Parameters:
aHeight - the height of the text in the chosen font.

add

public void add(FSCharacter aCharacter)
Adds an FSCharacter object to the array of characters.

Parameters:
aCharacter - an FSCharacter object.

getCharacters

public java.util.ArrayList getCharacters()
Gets the array of characters to be displayed.

Returns:
the array of FSCharacter objects.

setCharacters

public void setCharacters(java.util.ArrayList anArray)
Sets the array of characters to be displayed.

Parameters:
anArray - an array of FSCharacter objects.

clone

public java.lang.Object clone()
Description copied from class: FSTransformObject
Creates a deep copy of the entire object.

Overrides:
clone in class FSTransformObject
Returns:
a copy of the object.

equals

public boolean equals(java.lang.Object anObject)
Description copied from class: FSTransformObject
Returns true if anObject is equal to this one. Objects are considered equal if they would generate identical binary data when they are encoded to a Flash file.

Overrides:
equals in class FSTransformObject
Returns:
true if this object would be identical to anObject when encoded.

appendDescription

public void appendDescription(java.lang.StringBuffer buffer,
                              int depth)
Description copied from class: FSTransformObject
AppendDescription is used to present a string description of the object including all nested objects up to a specified depth. This method provide a more controlled way of creating a string representation of an object since large objects such as font or shape definitions can contain dozens of nested objects. The representation of the object is appended to the StringBuffer, showing the name of the class and values of the attributes it contains. If the object contains any attributes that are objects then the object graph will be traversed up to the specified depth. If objects are nested at a level less than specified depth then the full string representation of the object is displayed. For objects at the specified depth only the name of the class is displayed. Any objects below this depth are not displayed.

Specified by:
appendDescription in class FSTransformObject
Parameters:
buffer - a StringBuffer to which the description of each object is appended.
depth - the maximum level of nesting up to which objects will be displayed.

length

public int length(FSCoder coder)
Specified by:
length in class FSTransformObject

encode

public void encode(FSCoder coder)
Specified by:
encode in class FSTransformObject

decode

public void decode(FSCoder coder)
Specified by:
decode in class FSTransformObject