The Effect and the Code

We show how to use the new AS3 text layout classes: TextFlow, ContainerController, TextLayoutFormat, and properties like TextFlow.flowComposer to lay out and format text programmatically. In our example, the number of columns in the layout can be changed on the fly by dragging a slider. Click the screenshot to open Flash movie.

Download

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

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

The Runtime Shared Library (RSL) for TLF Text

When you compile the fla file in the zip package, textcols.fla, you will notice a file called textLayout_1.0.0.595.swz (about 150 KB) appearing alongside the swf file. That is because TLF text requires a specific Runtime Shared Library to be available to the Flash Player at runtime. If the library is not already present on the user's computer, it will be downloaded from the Adobe site at runtime. The download will be necessary only once for a given computer. It is a good idea to place textLayout_1.0.0.595.swz on your server as a backup in the same directory as your swf file that uses TLF. Should the Adobe site be unavailable, the swf will look for the RSL in its directory.

Automatic Preloader

If you look at the default Publish Settings in a Flash CS5 fla file, you will notice under Flash ->ActionScript 3 Settings, a swf preloader file (loading_animation.swf) listed with a local path to it. Indeed, by default a little preloader is included in a published swf file. The preloder is hard to notice with the application in this example as the file is small even with textLayout_1.0.0.595.swz downloaded at runtime. The see the little preloader animation, open textcols.fla, go to Test Movie and Simulate Download with some really slow simulated connection speed.

Code and Comments

For simplicity, we placed the code on the MainTimeline. Here is the code and comments.

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.ParagraphElement;

import flashx.textLayout.elements.SpanElement;

import flashx.textLayout.elements.TextFlow;

import flashx.textLayout.formats.TextLayoutFormat;

The class we need for the slider on the Stage:

import fl.events.SliderEvent;

Four String variables that will hold text of four paragraphs in our example. The Strings are created in setStrings function defined below. It would be more interesting to import text at runtime. We will dicuss that case in upcoming tutorials.

var str1:String="";

var str2:String="";

var str3:String="";

var str4:String="";

setStrings();

We create a Sprite container that will serve as a container for our text. We have only one container. If we wanted to create linked text, we could create any number of containers to work with our instance of TextFlow defined below.

var container:Sprite=new Sprite();

this.addChild(container);

container.x = 40;

container.y = 50;

We are creating two instances of the new TextLayoutFormat class, format1 and format2. format1 will be applied to all text; format2 to the headers only. TextLayoutFormat class has a long list of properties and methods to format your text any way you wish.

var format1:TextLayoutFormat = new TextLayoutFormat();

format1.color = 0x660000;

format1.fontFamily = "Arial, Helvetica, _sans";

format1.fontSize = 14;

format1.paragraphSpaceBefore=0;

format1.paragraphSpaceAfter=20;

var format2:TextLayoutFormat = new TextLayoutFormat();

format2.color = 0x990000;

format2.fontSize = 16;

format2.fontWeight = FontWeight.BOLD;

The central class of the TLF text framework is TextFlow. We create an instance of TextFlow called 'flow'. 'flow' contains all of our text and via its property 'flowComposer' it creates a layout we want. An instance of TextLayoutFormat, format1, is assigened as 'hostFormat' to 'flow' and will apply to all the text in 'flow' unless it is overridden by local formatting of specific paragraphs or spans.

Most of TextLayoutFormat properties, e.g. fontSize can be assigned directly to 'flow': flow.fontSize=14. It is easier to keep track of different format properties used in our text if they are stored in separate instances of TextLayoutFormat, format1, format2.

var flow:TextFlow = new TextFlow();

We set initial number of columns to 2. The gap between columns is set to 30 pixels.

flow.columnCount=2;

flow.columnGap=30;

flow.hostFormat = format1;

TextFlow, ParagraphElement, SpanElement are all subclasses of the base FlowElement class that inherits from Object. Flow element classes are not DisplayObjects. Nonetheless, they have addChild(fe:FlowElement) method.

An instance of TextFlow is at the top of the tree of elements: paragraphs are its children, spans are children of paragraphs and so are graphical elements.

We create four paragraphs, p1, p2, p3, p4. They are assigned as children of 'flow'. Spans, s1, s2, s3, s4, are children of paragraphs. Text is assigned to spans. Additional formatting, format2, is assigned to p1 and p3 as they are the headers paragraphs.

var p1:ParagraphElement = new ParagraphElement();

var span1:SpanElement = new SpanElement();

span1.text = str1;

p1.addChild(span1);

p1.format=format2;

flow.addChild(p1);

var p2:ParagraphElement = new ParagraphElement();

var span2:SpanElement = new SpanElement();

span2.text = str2;

p2.addChild(span2);

flow.addChild(p2);

var p3:ParagraphElement = new ParagraphElement();

var span3:SpanElement = new SpanElement();

span3.text = str3;

p3.addChild(span3);

p3.format=format2;

flow.addChild(p3);

var p4:ParagraphElement = new ParagraphElement();

var span4:SpanElement = new SpanElement();

span4.text = str4;

p4.addChild(span4);

flow.addChild(p4);

After creating and formatting an instance of TextFlow, 'flow', we arrive at the next crucial step: adding a container (or several containers) for our 'flow'.

We use flowComposer property of TextFlow and its method addController. We assign our Sprite, 'container', as the flow's ContainerController and set the dimensions of the ContainerController to 570 by 340.

Whenever something about our TextFlow changes, the method flowComposer.updateAllControllers has to be called.

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

flow.flowComposer.updateAllControllers();

Every time the slider's value changes, we change the value for flow.columnCount and call updateAllControllers. The layout of our text changes accordingly.

slider.addEventListener(SliderEvent.CHANGE,sliderChange);

 

function sliderChange(e:SliderEvent):void {

var curVal:Number=e.target.value;

flow.columnCount=curVal;

flow.flowComposer.updateAllControllers();

}

The function that sets the Strings 'str1' contains the text of the first paragraph, 'str2' the text of the second paragraph etc.

function setStrings():void {

str1="TLF Text Layout and Formatting in Flash CS5 with AS3";

str2=".................";

str3=".................";

str4=".................";

}

You may notice that we do not use flash.text.TLFTextField in this example. We find manipulating instances of TextFlow and ContainerController in this example to be easier and more intuitive. TLFTextField class provides shorcuts for some steps (TLFTextField extends Sprite and automatically provides a container for an instance of TextFlow, for example), but it comes with built-in elements like an empty paragraph at the beginning which can be confusing.

The marked-up text that we created using methods of TextLayoutFormat and flow elements, can be exported to (and imported from) an XML file via the TextConverter.export and TextConverter.importToFlow methods. This is a subject for the next tutorial, though.

For a tutorial that shows how to created linked text fields in AS3 and more discussion of the new AS3 classes see: New AS3 Text Layout Classes in Flash CS5 - Tour and Example.

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.