Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.flagstone.transform
Class FSText

    java.lang.Object
      com.flagstone.transform.FSTransformObject
          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`

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD