com.flagstone.transform.util
Class FSTextConstructor

java.lang.Object
  extended by com.flagstone.transform.util.FSTextConstructor

public class FSTextConstructor
extends java.lang.Object

The FSTextConstructor class greatly simplifies the use of fonts and text when creating Flash files. Font definitions can be created in three ways:

  1. Using TrueType or OpenType font definition stored in a file.
  2. Using a font definition stored in an existing Flash file.
  3. Using a given Java AWT font as a template.

Font definitions from TrueType, OpenType or Flash files are created by specifying the name of the file:

 FSTextConstructor font = new FSTextConstructor(id, trueTypeFile.getPath());
 FSTextConstructor font = new FSTextConstructor(id, swfFile.getPath());
 

The OpenType or TrueType file is parsed to construct the font definition. Files with the extensions ".otf" or ".ttf" may be used. Files containing collections of fonts ".otc" are not currently supported. For Flash files the first font definition encountered is used and all the text definition objects associated with the font are used to obtain the advance information for each character. An example Flash file can be found in the resources directory included in this release.

Font definitions from AWT templates are created by passing a font object:

 FSTextConstructor font = new FSTextConstructor(id, new Font("Arial", Font.PLAIN, 1));
 

Only the font or file name needs to specified. Unlike Java fonts, font definitions in Flash are size independent, the size and colour in which a given string in rendered is specified in the object that defines the text to be displayed avoiding the need to create multiple font definitions for the same font name.

An array of FSGlyph objects are created from the font definition. Each object contains the glyph for the font, the associated character code and information used to lay out each glyph when it is displayed.

Once a font has been created text strings can be generated:

    int fontSize = 280; // twips
    FSColor fontColor = FSColorTable.black();
    FSDefineText2 aString = font.defineText("This is a string", fontSize, fontColor);
 

The defineText method returns FSDefineText2 objects since they support transparent colours, while FSDefineText only supports opaque colours.

Once all the strings to be displayed have been generated the font definition object containing the glyphs can be generated.

    FSDefineFont2 defineFont = font.defineFont();
 

Remember however that objects in a Flash file must be defined before they are used so the font object must be added to the file before the first FSDefineText object that references the glyphs in the font.

To reduce the size of the Flash file only the glyphs actually displayed can be included in a font definition object. When a FSDefineText object is created the glyphs used are marked. This is why the text definition objects are generated before the font definition.

Glyphs are included in the font in the order they are used with each FSDefineText2 object referencing a glyph by its position in the array of glyphs contained in a font definition. Any unused glyphs can then easily be omitted.

When the font definition is created only the glyphs used (up to that point) are included. If subsequent FSDefineText objects are generated that include glyphs not previously used then the text will not be displayed correctly.

Text Fields

When creating text fields using the FSDefineTextField class, there are two options when specifying the font used to display the characters entered into the field:

  1. The glyphs for the font may be loaded from the host platform.
  2. The glyphs for the font are taken from a font definition object.

Using the glyphs loaded from the host platform is by far the easiest way of using text fields. First a font definition is created that specifies only the name of the font which will be loaded from the host platform. Then creating the text fields set the useFontGlyphs attribute to false.

    FSDefineFont2 fontDefinition = new FSDefineFont2(movie.newIdentifier(), "Arial");

    FSDefineTextField textField = new FSDefineTextField(movie.newIdentifier(), bounds);

    textField.setUseFontGlyphs(false);
 

This approach only works if the font is defined on the host platform otherwise the Flash Player will substitute a default font.

When using a font definition contained in the Flash file obviously the glyphs for all possible characters must be defined otherwise the character will not be displayed correctly. When using text fields the characters must be defined in the font, sorted by ascending character code, otherwise the text will not be displayed correctly. To do this the FSCharacterTable class provides arrays of characters sorted in the correct order. The array is passed to the willDisplay() method and the FSTextConstructor will add the glyphs for the characters in the order they appear in the array:

     char[] characterSet = FSCharacterTable.ascii();

     textConstructor.willDisplay(characterSet);
 

This will add ALL of the characters in the array to the font definition. Several character sets are provided in the FSCharacterTable class but any array of characters could be passed to the willDisplay() method - allowing smaller font definitions to be created when only a few characters are displayed.

Missing Characters

Characters that cannot be displayed using the font are handled by a displaying a default glyph which typically represents a space or an empty box. Both Java AWT and True/Open Type definitions explicitly define the missing glyph. For fonts parsed from Flash files the missing glyph is assumed (by default) to be the first glyph in the font definition.

When a font is loaded the missing glyph is added automatically to the font definition so there is no need to explicitly include it by creating a text object to force it to be included. The missing glyph will always be the first glyph in the font definition generated by the FSTextConstructor object so it may be substituted by another suitable shape if required.

Whether a string can be displayed using a font can be determined by the canDisplay() method which returns the index of the first character that cannot be displayed (the missing glyph will be displayed instead) or -1 if all the characters are represented in the font.


Constructor Summary
FSTextConstructor(int anIdentifier, java.awt.Font font)
          Creates a new FSTextConstructor object using the specified font.
FSTextConstructor(int anIdentifier, java.lang.String filename)
          Creates a new FSTextConstructor object using the specified font.
 
Method Summary
 int advanceForChar(char c, int fontSize)
          Returns the advance, in twips, to the next character.
 FSBounds boundsForText(java.lang.String text, int fontSize)
          Generates an FSBounds object that defines the bounding box that encloses the text, rendered in the specified font size.
 int canDisplay(char[] chars)
          Indicates whether or not this FSTextConstructor can display all the characters specified in the array.
 int canDisplay(java.lang.String aString)
          Indicates whether or not this FSTextConstructor can display a specified Unicode String.
 FSDefineFont2 defineFont()
          Generates a FSDefineFont2 object containing a complete definition of the font.
 FSDefineShape3 defineShape(int anIdentifier, java.lang.String text, int fontSize, FSColor aColor)
          defineShape converts a string into an equivalent shape representation.
 FSDefineText2 defineText(int anIdentifier, java.lang.String text, int fontSize, FSColor aColor)
          Generates an FSDefineText2 object for the text rendered in the specified font size and colour.
 FSDefineText2 defineTextBlock(int anIdentifier, java.util.ArrayList lines, int fontSize, FSColor aColor, int lineSpacing)
          Generates an FSDefineText2 object for a block of text.
 void reset(int anIdentifier)
          Resets the FSTextConstructor to generate a new set of font and text objects.
 void willDisplay(char[] chars)
          willDisplay is used to predefine the set of characters that will be used when defining text objects.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

FSTextConstructor

public FSTextConstructor(int anIdentifier,
                         java.lang.String filename)
                  throws java.io.IOException,
                         java.util.zip.DataFormatException
Creates a new FSTextConstructor object using the specified font.

The fontName can be used to identify a particular font in two ways, either specifying:

  1. the name of a file containing a TrueType or OpenType font definition.
  2. the name of a Flash file containing font definition.
IMPORTANT: This method previously allowed the name of a AWT Font to be specified as an argument. This will no longer be supported in future releases, use the FSTextCOnstructor(int, Font) method instead.

Parameters:
anIdentifier - a unique identifier that will be assigned to the font definition object generated and referenced by all the text object generated.
filename - either the name of a Flash, TrueType or OpenType file containing an existing font definition.
Throws:
java.io.FileNotFoundException - if the fontName specifies a file and the file cannot be found or opened.
java.io.IOException - if the fontName specifies a file and an error occurs while reading the file from disk.
java.util.zip.DataFormatException - if the fontName specifies a file and an error occurs while parsing the font definition.

FSTextConstructor

public FSTextConstructor(int anIdentifier,
                         java.awt.Font font)
Creates a new FSTextConstructor object using the specified font.

Parameters:
anIdentifier - a unique identifier that will be assigned to the font definition object generated and referenced by all the text object generated.
font - an AWT Font object.
Method Detail

reset

public void reset(int anIdentifier)
Resets the FSTextConstructor to generate a new set of font and text objects. The character sets defined for the font are cleared so the characters that will be used to generate the next font definition should be set with the willDisplay() method. This method is useful when generating objects for more than one Flash file as it avoids the penalty of reloading the font definition which can be very expensive.

Parameters:
anIdentifier - a unique identifier that will be assigned to the font definition object generated and referenced by all the text object generated.

canDisplay

public int canDisplay(char[] chars)
Indicates whether or not this FSTextConstructor can display all the characters specified in the array. This method returns the index of the first character that cannot be displayed using this font. If the Font can display all characters, -1 is returned.

Parameters:
chars - an array containing all the characters to be displayed.
Returns:
the index of the first character that cannot be displayed, -1 otherwise.

canDisplay

public int canDisplay(java.lang.String aString)
Indicates whether or not this FSTextConstructor can display a specified Unicode String. This method returns the index of the first character that cannot be displayed using this font. If the Font can display all characters, -1 is returned.

Parameters:
aString - the String to be displayed.
Returns:
the index of the first character that cannot be displayed, -1 otherwise.

willDisplay

public void willDisplay(char[] chars)
willDisplay is used to predefine the set of characters that will be used when defining text objects.

Parameters:
chars - an array of characters defining the character set that will be used when defining text objects and fonts. The characters must be sorted by the code used to represent the character.
See Also:
for lists of predefined character sets that can be used with different spoken languages.

defineFont

public FSDefineFont2 defineFont()
Generates a FSDefineFont2 object containing a complete definition of the font.

NOTE: Only the glyphs specified in the array of characters passed to the willDisplay method will be shown.

Returns:
a FSDefineFont2 object generated from the font definition.

defineText

public FSDefineText2 defineText(int anIdentifier,
                                java.lang.String text,
                                int fontSize,
                                FSColor aColor)
Generates an FSDefineText2 object for the text rendered in the specified font size and colour. This method is used to create FSDefineText2 objects for arbitrary strings, using the characters defined for the FSTextConstructor object when it is constructed. NOTE: The font size is specified in twips not points or pixels.

An FSDefineText2 object differs from an FSDefineText object in that it supports transparent colours.

If any of the Unicode characters in the String cannot be displayed using this font then the missing glyph is substituted.

Parameters:
anIdentifier - a unique identifier for the object.
text - the String to be displayed.
fontSize - the size of the font in twips.
aColor - the colour of the text including transparency.
Returns:
an FSDefineText object representing the text.

defineTextBlock

public FSDefineText2 defineTextBlock(int anIdentifier,
                                     java.util.ArrayList lines,
                                     int fontSize,
                                     FSColor aColor,
                                     int lineSpacing)
Generates an FSDefineText2 object for a block of text.

An FSDefineText2 object differs from an FSDefineText object in that it supports transparent colours.

If any of the Unicode characters in the String cannot be displayed using this font then the missing glyph is substituted.

Parameters:
anIdentifier - a unique identifier for the object.
lines - an array containing the lines of text to be displayed.
fontSize - the size of the font in twips.
aColor - the colour of the text including transparency.
lineSpacing - the distance, in twips, between successive lines.
Returns:
an FSDefineText object representing the text.

boundsForText

public FSBounds boundsForText(java.lang.String text,
                              int fontSize)
Generates an FSBounds object that defines the bounding box that encloses the text, rendered in the specified font size.

Parameters:
text - the String to be displayed.
fontSize - the size of the font in twips.
Returns:
an FSBounds object defining the bounding box enclosing the text.

advanceForChar

public int advanceForChar(char c,
                          int fontSize)
Returns the advance, in twips, to the next character. This method can be used when laying out sequences of individual characters, rather than as as single string.

Parameters:
c - the character that will be displayed.
fontSize - the size of the font the character will be rendered in.
Returns:
the distance to the next character.

defineShape

public FSDefineShape3 defineShape(int anIdentifier,
                                  java.lang.String text,
                                  int fontSize,
                                  FSColor aColor)
defineShape converts a string into an equivalent shape representation. The shape is constructed from glyphs used to represent each character in the string and filled with the specified colour.

Parameters:
anIdentifier - an unique identifier for the shape.
text - the string to convert into a shape.
fontSize - the font size in twips used to render the shape
aColor - the colour which will be used to fill the shape.
Returns:
an FSDefineShape3 object4 which contains a shape that represents the characters contained in the string argument.