|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectcom.flagstone.transform.util.FSTextConstructor
public class FSTextConstructor
The FSTextConstructor class greatly simplifies the use of fonts and text when creating Flash files. Font definitions can be created in three ways:
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 FieldsWhen creating text fields using the FSDefineTextField class, there are two options when specifying the font used to display the characters entered into the field:
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 CharactersCharacters 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 |
---|
public FSTextConstructor(int anIdentifier, java.lang.String filename) throws java.io.IOException, java.util.zip.DataFormatException
The fontName can be used to identify a particular font in two ways, either specifying:
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.
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.public FSTextConstructor(int anIdentifier, java.awt.Font font)
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 |
---|
public void reset(int anIdentifier)
anIdentifier
- a unique identifier that will be assigned to the
font definition object generated and referenced by all the text object
generated.public int canDisplay(char[] chars)
chars
- an array containing all the characters to be displayed.
public int canDisplay(java.lang.String aString)
aString
- the String to be displayed.
public void willDisplay(char[] chars)
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.for lists of predefined character sets that can be
used with different spoken languages.
public FSDefineFont2 defineFont()
NOTE: Only the glyphs specified in the array of characters passed to the willDisplay method will be shown.
public FSDefineText2 defineText(int anIdentifier, java.lang.String text, int fontSize, FSColor aColor)
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.
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.
public FSDefineText2 defineTextBlock(int anIdentifier, java.util.ArrayList lines, int fontSize, FSColor aColor, int lineSpacing)
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.
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.
public FSBounds boundsForText(java.lang.String text, int fontSize)
text
- the String to be displayed.fontSize
- the size of the font in twips.
public int advanceForChar(char c, int fontSize)
c
- the character that will be displayed.fontSize
- the size of the font the character will be rendered in.
public FSDefineShape3 defineShape(int anIdentifier, java.lang.String text, int fontSize, FSColor aColor)
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 shapeaColor
- the colour which will be used to fill the shape.
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |