Using the Text Layout Framework in Adobe Flash Professional CS5

by Tommi West

Text Layout Framework (TLF) text is the new default text type in Adobe Flash Professional CS5. Using TLF text, you can control text at the character level with advanced typography features (such as kerning and leading). You can also display global language characters, including bidirectional and vertical text, with new formatting capabilities and more precise control over the appearance of text in Flash than ever before. In this article, I examine TLF and show you how you can use it to display TLF text objects in a SWF file.

Getting to know TLF

The Text Layout Framework is a library of ActionScript 3 classes. Projects that incorporate TLF text objects require Flash Player 10 (or later) to play. You can create and style TLF text using the Flash authoring environment as well as by using ActionScript code. When using ActionScript 3 to create TLF text objects, you need to use the TLFTextField class. The previous type of text in Flash (now called Classic text) uses the Flash Text Engine and the TextField class to display text in Flash Player 9 and earlier.

This sample project illustrates how to create a Flash file that is populated and styled by an external text document (an XML file). Once you've set this up, you never have to alter the FLA code, and you can directly control the SWF file's content and appearance by editing the external file in a text editor. This enables team members to directly affect the output of the project without updating the FLA file and republishing the SWF file in the Flash authoring environment.

The project displays a few lines of text; the last line contains a mailto link above the loaded image file in Figure 1.

Figure 1. The published SWF file displays the loaded TLF text and image file.

To follow along with this tutorial, download the sample files (ZIP, 290 KB). Uncompress the TLF-Text.zip archive and save the folder to your desktop.

The Sample Files folder contains the following files:

• index.html: The HTML page containing the SWF file
• example.html: A second HTML page used as a placeholder page to test the link locally
• Scripts folder: A folder that contains two files necessary for SWF playback, generated by Adobe Dreamweaver
• star.png: The image file referenced in the XML file that is loaded at runtime into the SWF file
• tlf.fla: The Flash authoring file that uses ActionScript 3 to load the XML data
• tlf.swf: The published Flash file that is inserted in the HTML page
• tlf.xml: The XML data file containing the text content and formatting to populate the SWF file

Open the folder and locate the file named tlf.fla. Double-click it to open it in Flash Professional CS5.

Reviewing the code

The Timeline in the project contains two layers. The top layer, named Actions, contains the ActionScript. The bottom layer, named Background, contains the background graphic. To review the ActionScript code, select Frame 1 of the Actions layer. Choose Window > Actions to open the Actions panel, and view the code in the Script window. At the top of the script, the last four import statements are used to import the classes needed to work with TLF text objects programmatically:

import flashx.textLayout.elements.TextFlow;
import flashx.textLayout.container.ContainerController;
import flashx.textLayout.conversion.TextConverter;
import flashx.textLayout.events.StatusChangeEvent;

You must import these classes at the beginning of the code — before attempting to reference their methods, properties, and events — because the TLF text classes are not included in Flash Player 10; they must be imported at runtime.

Scroll down near the bottom and locate the function named initText. The code looks like this:

function initText():void {
textFlow = TextConverter.importToFlow(externalFileContent,TextConverter.TEXT_LAYOUT_FORMAT);
textFlow.addEventListener(StatusChangeEvent.INLINE_GRAPHIC_STATUS_CHANGE,statusChangeHandler,false,0,true);
textFlow.flowComposer.addController(new ContainerController(textContainer, 350, 200));
textFlow.flowComposer.updateAllControllers();
}

The first line inside the initText function sets the default formatting for the text content:

textFlow = TextConverter.importToFlow(externalFileContent,TextConverter.TEXT_LAYOUT_FORMAT);

In this example, the text content is using the Text Layout Format formatting, rather than the other two options (plain text or HTML formatting).

The second line creates an event listener to update the text flow composer controller once the image has finished loading. It references the last function in the script:

textFlow.addEventListener(StatusChangeEvent.INLINE_GRAPHIC_STATUS_CHANGE,statusChangeHandler,false,0,true);

The third line adds the text to the flow composer controller:

textFlow.flowComposer.addController(new ContainerController(textContainer, 350, 200));

This method is similar to the DisplayObjectContainer.addChild() method, which displays the content on the Stage. The parameters at the end define the height and width of the loaded container area on the Stage.

The last line of the function causes the flow composer to update the text controller:

textFlow.flowComposer.updateAllControllers();

The last function is statusChangeHandler:

function statusChangeHandler(e:Event):void
{
	textFlow.flowComposer.updateAllControllers();
}

This function causes the flow composer to update the text controller again once the image file has loaded.

When you are finished reviewing the code, close the tlf.fla file and quit Flash.

Previewing the project

Next, let's preview the project to see how it will appear when it's published online.

1. In the Sample Files folder, right-click (or Control-click) index.html and open it in a browser. The embedded SWF file plays in Flash Player 10, and you can see the TLF text content and image file displayed. The TLF text content, the link to the image, and the formatting properties are stored in the external XML file.

2. Roll your cursor over the linked text to see the rollover effect. Click the link to launch your email client and note that the To field is populated by the mailto link in the SWF file in Figure 2.

   

   Figure 2. When clicked, the email link invokes your email client and composes a new message.

3. After reviewing the project, leave the browser window open. You'll return to the browser later, to refresh the HTML page and see the SWF update.

Examining the XML data

Next, let's review the XML data and formatting properties that are loaded into the SWF file.

In the Sample Files folder, locate the file named tlf.xml. Open it in a text editor such as Adobe Dreamweaver. (You can also use Notepad or Text Edit to open the XML file, if desired.)

The top portion of the XML code defines the default formatting properties of the TextFlow, including the font size, padding, and alignment of the text content:

<TextFlow color="#000000" columnCount="1" fontSize="14" lineBreak="toFit" paddingTop="0" paddingBottom="0" 
paddingLeft="0" paddingRight="0" paragraphSpaceBefore="0" paragraphSpaceAfter="20" verticalAlign="top" 
xmlns="http://ns.adobe.com/textLayout/2008">

Note: The xmlns attribute is the XML namespace declaration. This is required, so be sure not to edit or delete the link to adobe.com in the code above.

Inside the <div> tag below the TextFlow definition are several paragraphs. The first paragraph contains text that uses the default formatting, as applied by the TextFlow tag properties shown above:

<p>
    <span>This text is formatted by the TextFlow definition.</span>
</p>

The second paragraph contains text that is formatted with styles in the surrounding

tag, causing the text to display with a white font color, a larger font size, and a bold font weight. These styles override the default formatting applied in the TextFlow tag:

<p color="#ffffff" fontSize="16" fontWeight="bold">
    <span>This text is formatted with unique styles.</span>
</p>

The third paragraph contains linked content that includes font color and text decoration styles to affect the normal, active, and hover states. These styles change the link formatting from the default blue underlined text.

<p>		
    <a href="mailto:info@mysite.com">		
    <linkNormalFormat><TextLayoutFormat color="#990000" textDecoration="none"/></linkNormalFormat>
    <linkActiveFormat><TextLayoutFormat color="#990000" textDecoration="none"/></linkActiveFormat>	       
    <linkHoverFormat><TextLayoutFormat color="#cccccc" textDecoration="underline"/></linkHoverFormat>
    <span>This link has custom formatting and a rollover effect.</span>
    </a>	
</p>

As your cursor hovers over the link, the underline appears, and the linked text turns gray.

The last paragraph contains the path to the image file, named star.png:

<p textAlign="center">
    <img source="star.png" height="61" width="61" />	
</p>

The <p> tag includes the alignment parameter to align the image file to the center of the Stage.

Updating the text and formatting

Now that you've reviewed the sample code, try experimenting by updating the text and formatting properties in the XML file:

1. Edit the text content of the file. Change the first line of text to "The updated text content is displayed here."
2. Change the font color in the TextFlow tag to reset the default font color from #000000 (black) to #00ccff (light blue).
3. Save the XML file. Return to the browser and reload the HTML page. The SWF file updates without changing the FLA file.
4. Return to the text editor and change the second line of text to "The external file is updating the content and the formatting."
5. This time, try adjusting the parameters in the tag surrounding the second paragraph. For example, change the font color from #ffffff (white) to #ffcc00 (yellow). And then change the font size from 16 to 12.
6. Save the XML file again. Reload the page in the browser again to see the SWF file reflect the recent changes.

7. Update the XML text file again to change the link. This time you'll change the mailto link to a relative path that references the example HTML page in the sample files folder, like this:

   <a href="example.html">

8. Save the XML file and reload the browser. This time, click the link to see the placeholder HTML page display locally in a new tab.

Note: If you update the link property with an absolute path to a live page on the Internet (such as www.adobe.com), you'll encounter the error message in Figure 3.

Figure 3. The error states that a local SWF file is attempting to access a file on the Internet.

This error appears because of the Flash Player security that is applied to local SWF files attempting to access remote files. To learn more, read What is Flash Player security for local content? in the Adobe Flash Player help documentation.

To continue testing the link, you can place another HTML file (or an image file) in the local TLF-Text folder and update the link using a relative path (the element's filename). If you refresh the browser again and click the link, you'll see that the new local content loads in the browser as expected.

And if you like, you can save a different image file in the TLF-Text folder (alongside the tlf.swf, tlf.xml, and index.html files) and then update the image source in the last paragraph to reference the filename of the new image file. If you don't update the height and width attributes, the image file you supply will be resized to the dimensions specified in the XML file.

There's one more thing you may notice when developing projects using TLF text. When you publish the SWF file from Flash, you may see an SWZ file appear in the project folder. This file is generated by Flash and is considered a backup file for the TLF text classes, which you can optionally upload to the host server along with the HTML, Scripts folder, SWF file, XML file, and image files. To learn more about the SWZ file that Flash generates (and how to optionally merge it into the code of the SWF file), read the article entitled How to publish SWF files with TLF text on the FlashConf.com site.

Where to go from here

As you can see from this simple example, you can use TLF text objects to separate text content, image content, and formatting from the SWF file itself. Without even opening the FLA file, you've updated the contents of the SWF file by editing the external XML file. Making real-time changes without touching the FLA file enables you to reduce your development time, especially when working on projects that are likely to change often.

This is only a small example of what you can achieve. To extend this project further, experiment with creating multiple SWF files with different backgrounds and graphics that load the same XML data. For example, you can create a series of SWF files for a site that look completely different but display the same text, images, and links.

Also check out some of the other capabilities of the Text Layout Framework:

• Display text across multiple columns and linked containers.
• Apply advanced typography settings, including kerning, leading, and ligatures.
• Enable selection and editing (including cut, copy, and paste) of TLF text objects in SWF files.
• Create projects using global languages with vertical or right-to-left character orientation.
• Use embedded fonts to fit specific design requirements, rather than using device fonts.

Text Layout Framework offers exciting new opportunities to manipulate text and control its appearance in Flash projects. You can also use TLF text objects when developing applications in Adobe Flash Builder and Adobe AIR.

To learn more about working with TLF text, watch the video tutorial on Adobe TV entitled Creating text with the Text Layout Framework. Also read Introducing the new Adobe ActionScript 3 SDK for Facebook Platform in this issue of the Edge. Also be sure to visit the ActionScript Technology Center and read about TLF text in the Flash glossary to get more information about controlling TLF text with ActionScript.

‹ Back