Displaying Content with Flow Composer

The simple approach may be all you need, but if you want to have more control over the display of the text, or if you want to give your user the ability to select and edit the text, you need to use something called a flow composer instead. A flow composer—which is an instance of the StandardFlowComposer class in the flashx.textLayout.compose package—is an object that manages not only the conversion of your TextFlow into TextLine instances, but also the placement of those TextLine instances into one or more containers.

View full size graphic
An IFlowComposer has zero or more IContainerControllers

Every TextFlow instance has a corresponding object that implements the IFlowComposer interface. This IFlowComposer object is accessible through the TextFlow.flowComposer property. Through this property, you can call methods defined by the IFlowComposer interface that allow you to associate the text with one or more containers and prepare the text for display within a container.

Note: Currently only one class in the framework, StandardFlowComposer, implements the IFlowComposer interface. This means that for now, the TextFlow.flowComposer property, is either null or points to an instance of StandardFlowComposer. In the future, there may be new classes added to the framework that also implement IFlowComposer.

A container is an instance of the Sprite class, which is a subclass of the DisplayObjectContainer class. Both of these classes are part of the Flash Player display list API. If you are unfamiliar with the Flash Player display list, you can think of a DisplayObjectContainer as a container of objects that are in a format that Flash Player can render.

You can think of a container as a more advanced form of the bounding rectangle used in the simple approach to display a text flow with the TextLineFactory class. Like the bounding rectangle, a container defines the area where TextLine instances will appear. Unlike a bounding rectangle, a container has a corresponding “controller” object through which you can control scrolling, linking, formatting, and event handling for a container or set of containers.

This enhanced functionality, such as advanced formatting and the scrolling options, is managed by and stored in a controller object. Each container has a corresponding controller object that is an instance of the ContainerController class in the flashx.textLayout.container package. It is these controller objects, sometimes called “container controllers”, that are managed directly by the flow composer.

When you have your TextFlow populated and are ready to display it on screen, create a controller object and associate it with the flow composer. Once you have the container associated, you must compose the text before it can be displayed. Accordingly, you can think of containers as having two stages: composition and display. Composing the text is the process of converting the text from the text flow hierarchy into TextLine instances and calculating how those instances will fit into the container. Displaying the text involves updating the Flash Player display list by calling the flow composer's updateAllContainers() method.

For example, the following code creates a TextFlow instance named myFlow and a controller object to display it. Once the controller object is created, it must be associated with the TextFlow’s flowComposer property. Finally, the call to the updateAllContainers() method causes the text to be composed and the display list to be updated.

// import necessary classes 
import flashx.textLayout.container.*; 
import flashx.textLayout.compose.*; 
import flashx.textLayout.elements.TextFlow; 
import flashx.textLayout.conversion.TextConverter; 
// first, create a TextFlow instance named myFlow 
var markup:XML = <TextFlow><p><span>Hello, World</span></p></TextFlow>; 
var myFlow:TextFlow = TextConverter.importToFlow(markup, TextConverter.TEXT_LAYOUT_FORMAT); 
// second, create a controller 
// the first parameter, this, must point to a DisplayObjectContainer 
// the last two parameters set the initial size of the container in pixels 
var contr:ContainerController = new ContainerController(this, 600, 600); 
// third, associate it with the flowComposer property 
// fourth, update the display list