An Example and the Code

The new TLF text AS3 classes are extremely useful for creating cool text effects, particularly if you can import your text on the fly, at runtime. TLF formatting and layout can be saved in a text file or in an XML file. But what is the correct TLF markup? In this tutorial, we show how to create a text file or an XML file containing TLF markup, load the file at runtime, and display the dynamically loaded text. Click the screenshot to open Flash movie.

Download

  • Download all source files corresponding to this effect: gettext.zip

Download the zip package linked above for the complete, well-commented, and easy to customize source code. Below, we present and comment on the code and the new AS3 classes that we used in the application.

The Timeline Code That Loads a TLF Markup File and Displays Formatted Text

You will find this code in the file gettext.fla. The TLF markup text file loaded at runtime is called markup.txt. You will find the file in the zip package as well. Here is the code in gettext.fla.

We are importing the AS3 classes from the flashx.textLayout package necessary to create and manipulate TLF text in our example.

import flashx.textLayout.container.ContainerController;

import flashx.textLayout.elements.TextFlow;

import flashx.textLayout.conversion.TextConverter;

We created a message TextField on the Stage, txtOutput, to display messages about loading. We set its wordWrap property.

txtOutput.wordWrap=true;

We create a URLLoader to load our text file, markup.txt.

var ldr:URLLoader = new URLLoader();

ldr.addEventListener(Event.COMPLETE, loadComplete);

ldr.addEventListener(IOErrorEvent.IO_ERROR, loadError);

We define a String variable to hold data from the loaded text file.

var fileContent:String;

We define a Sprite that will hold and display our TextFlow.

var container:Sprite=new Sprite();

this.addChild(container);

container.x = 40;

container.y = 40;

We create an instance of the TextFlow class, 'flow'. It is the TextFlow object that will read the information about layout and formatting of our text (contained in the external file markup.txt) and display it correctly.

var flow:TextFlow = new TextFlow();

We are loading the text file. Since the file is in the same directory as the html and swf files corresponding to this fla file, the address is the name of the text file.

ldr.load(new URLRequest("markup.txt"));

txtOutput.text="Loading an external file...";

function loadError(e:IOErrorEvent):void {

txtOutput.text = "Error loading an external file. The server may be busy. Try refreshing the page.";

}

When the load is complete, we call 'initText' function.

function loadComplete(e:Event):void {

fileContent = ldr.data;

txtOutput.text="An external text file, markup.txt, was loaded as the movie opened. The text and the information about layout and formatting are contained in the text file.";

ldr.removeEventListener(Event.COMPLETE, loadComplete);

ldr.removeEventListener(IOErrorEvent.IO_ERROR, loadError);

initText();

}

The initText function uses the static method of the TextConverter class, importToFlow, to import the data from markup.txt file into 'flow'. After that, we use flowComposer to add a display container, our Sprite 'container', to display our text. We set the size of the container to 570 by 370. Then we update everything with 'updateAllControllers'.

function initText():void {

flow = TextConverter.importToFlow(fileContent,TextConverter.TEXT_LAYOUT_FORMAT);

flow.flowComposer.addController(new ContainerController(container, 570, 370));

flow.flowComposer.updateAllControllers();

}

If we wanted to import an XML markup file instead of a text file, the changes would be minor:
var fileContent:XML;
Within loadComplete function, you would put:
fileContent = new XML(ldr.data);
and within initText the same line:
flow = TextConverter.importToFlow(fileContent,TextConverter.TEXT_LAYOUT_FORMAT);

Since the first argument of the importToFlow method is an Object it can be a String or an XML object.

The Markup File: markup.txt

Here is the content of markup.txt file. We present the content with spaces and carriage returns for easier reading but, if you look into the file markup.txt, there are no spaces (except for those that we do want to appear in our text) and no carriage returns. We do want to avoid carriage returns as they produce unwanted white spaces. Setting whiteSpaceCollapse="collapse" in TextFlow tag attributes, would get rid of much of white space but not of the white spaces created by carriage returns.

 

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

<p color="#990000" fontSize="16" fontWeight="bold">

<span>Loading TLF Text at Runtime with AS3 in Flash CS5</span>

</p>

<p>

<span>The new TLF text features available in Flash CS5 are great for creating advanced text effects. Especially, if you can load text dynamically at runtime. If you use predefined text, you can always work with the Classic Text and MovieClips.</span>

</p>

<p color="#990000" fontSize="16" fontWeight="bold">

<span>TLF Markup and Loading</span>

</p>

<p>

<span>In this tutorial, we show how to write an markup file that contains TLF text and formatting, load the file at runtime, and create a TLF TextFlow object containing loaded text. Since the documentation for TLF markup is a bit hard to find, we created a fla file, getmarkup.fla, that generates a correctly structured TLF markup file. See this tutorial's web page and getmarkup.fla file in the zip package for explanations. Once we have a correctly structured markup file, we can easily edit and customize it. Then we can load the text file at runtime and use the TextConverter class to import the information contained in the text file (text, layout, and formatting) into our instance of the TextFlow class. In this tutorial we use only some of the many formatting features of the TextFlow class. There are many more. You can find them in the AS3 Flash CS5 online documentation. See out tutorial: </span>

<a href="http://www.flashandmath.com/flashcs5/textcols" target="_self">

<linkActiveFormat><TextLayoutFormat color="#0000cc" textDecoration="underline"/></linkActiveFormat>

<linkHoverFormat><TextLayoutFormat color="#cc0000" textDecoration="underline"/></linkHoverFormat>

<linkNormalFormat><TextLayoutFormat color="#0000cc" textDecoration="underline"/></linkNormalFormat>

<span>Multicolumn Text on the Fly with AS3 Flash CS5</span>

</a>

<span> for more examples of how to use these TextLayout classes.</span>

</p>

</TextFlow>

 

How We Created the Markup File

Since the documentation that explains XML markup for TLF formatting is a bit hard to find, we chose the following route. We created a fla file, called getmarkup.fla (you will find it in the zip package). In getmarkup.fla, we formatted text the way we wanted via easy to use and well-documented AS3 classes ParagraphElement, SpanElement, LinkElement, and TextFlow. (See AS3 Flash CS5 Online Documentation.) Then we used the TextConverter class to export the layout and formatting to a text file. Once we have correct markup, editing and customizing the text file is easy as well as creating markup files from scratch in any text editor.

To be more specific, in getmarkup.fla we created and formatted an instance of the TextFlow class, 'flow'. Then we used the static method 'export' of the TextConverter class and sent the reslut to the Output window via the trace function:

var outString:String=TextConverter.export(flow,TextConverter.TEXT_LAYOUT_FORMAT,
                           ConversionType.STRING_TYPE) as String;

trace(outString);

You can copy and paste the result from the Output window into any text editor, save it in UTF-8 encoding, and edit to your liking.

You could export equaly easily to an XML file by:

var outXML:XML=TextConverter.export(flow,TextConverter.TEXT_LAYOUT_FORMAT,
                           ConversionType.XML_TYPE) as XML;

trace(outXML);

Then you save the result to an xml file.

Both text format and XML format have advantages and disadvatages. XML files are easier to read and edit but some white spaces that you want to be there will get lost. Text files are harder to read and edit but they give you a much more precise control over white spaces.

For another tutorial that discusses TextFlow, ParagraphElement, and SpanElement classes see: Multicolumn Text on the Fly with New AS3 TLF Text Classes in Flash CS5.

Back to Flash CS5 Tutorials              Back to Flash and Math Home

We welcome your comments, suggestions, and contributions. Click the Contact Us link below and email one of us.

Adobe®, Flash®, ActionScript®, Flex® are registered trademarks of Adobe Systems Incorporated.