The goal of this article is to explain what the Text Layout Framework is and how you can use it to display rich text inside of Flash Player 10. While I will not cover all the possibilities of this framework, I hope I will give you enough of a push to get up to cruising speed.

As usual, you can find a demo and the source code for the examples in this article packaged as a Flex 3.2 project ZIP file. So if you prefer to see the code before reading the theory, then see the section “Code time: An example using the Text Layout Framweork in Flex 3.2″.

What is the Text Layout Framework

The Flash Text Engine (FTE) available in Flash Player 10 and Adobe AIR 1.5 brings support for many new text capabilities. There is an API that provides low-level access to this engine, but if you want to use the API you have to write a lot of code. Thus, the FTE is intended to provide the foundation for libraries that leverage these capabilities and make life easier for the developer.

And this is exactly what the Text Layout Framework is. It is a library written in pure ActionScript, and thus can be used in Flash CS4, Flex 3.2 or Gumbo, or AIR 1.5.

The Text Layout Framework provides support for:

• Bidirectional text, vertical text and over 30 writing systems including Arabic, Hebrew, Chinese, Japanese, Korean, Thai, Lao, the major writing systems of India, and others.
• Selection, editing and flowing text across multiple columns and linked containers, as well as around inline images
• Vertical text, Tate-Chu-Yoko (horizontal within vertical text) and justifier for East Asian typography
• Rich typographical controls, including kerning, ligatures, typographic case, digit case, digit width and discretionary hyphens
• Cut, copy, paste, undo and standard keyboard and mouse gestures for editing
• Rich developer APIs to manipulate text content, layout, markup and create custom text components.

Below are some screen shots from the samples you can find on http://labs.adobe.com/technologies/textlayout/:

Understanding Text Layout Framework components

The Text Layout Framework (TLF) comprises three components and ten packages. All the packages are subpackages of the flashx.textlayout package. As I said this framework is implemented using pure ActionScript 3, and thus can be used in Flash CS4, Flex 3.2, Gumbo (the Text Layout Framework is part of Gumbo), or AIR 1.5. And of course you have to target Flash Player 10. Here is a short description of the three components in TLF:

1. textLayout_core.swc is the main component and handles data storage, flowing text into containers, and rendering the containers
2. textLayout_conversion.swc is used to import text into the framework, and to export it
3. textLayout_edit.swc facilitates text selection and text editing

One way to look at the TLF, is by comparing it with the MVC pattern. If you apply this pattern, then you will have:

1. The model is defined mainly by the flashx.textlayout.elements package, which includes classes/interfaces that define the data structure that holds the text. Another package, flashx.textlayout.formats, is used for storing the format information. The package flashx.textlayout.conversion can be considered part of the model as it embodies the rules for importing/exporting the data
2. The view includes three packages that handle the rendering of text for display. You can choose to display the text using one of the two different methods: using flashx.textlayout.factory package you can display static text, and using flashx.textlayout.container you can display containers for dynamic text. The flashx.textlayout.compose package defines the methods for positioning and displaying dynamic text in containers
3. The controller is represented by two packages that define how the user can interact with the text (selecting, editing, copy/paste, undo, and so on): flashx.textlayout.edit and flashx.textlayout.operations

The Model and Text Flow hierarchy

The model uses a hierarchical tree to represent text. Each element of the tree is a class from the package flashx.textlayout.elements. The root element is always an instance of the TextFlow class, and conceptually represents an entire story of text (the term story comes from DTP, and means a collection of text that should be treated as one unit). For example, the article you are reading now could be a story.

The rest of the elements are:

• div - a division of text, can contains only div or p elements
• p - a paragraph, can contain any element but div
• a - a link; can contain tcy, span, img, tab, br
• tcy - a run of horizontal text, used in vertical text; for example in Japanese you can have this type of element; can contain a, span, img, tab, br
• span - a run of text in a paragraph; can contain only text
• img - an image in a paragraph
• tab - a tab character
• br - a break character. Text will continue on the next line, but it doesn’t start a new paragraph

The TextFlow can have only these two elements as children: div and p. Here is how the model can look for a story:

This Text Flow hierarchy translates to an XML document, using TLF Markup. Basically the nodes can be: TextFlow, div, p, a, img, span, tcy, br, and tab. At the same time, each node has an ActionScript class implementation: TextFlow, DivElement, ParagraphElement, LinkElement, TCYElement, SpanElement, InlineGraphicElement, TabElement, and BreakElement. All these classes inherit directly or indirectly from the class FlowElement.

Now, let’s see how you can create a TextFlow element. Basically, there are two ways you can create a TextFlow element: by using an XML object, or by creating the nodes and assembling them together in a tree (similar to creating an XML using DOM).

Creating a TextFlow element using an XML:

   1: private static const textInput:XML = <TextFlow xmlns="http://ns.adobe.com/textLayout/2008">

   2: <div>

   3:     <p>

   4:         <img source="air.png"/>

   5:         <span>Flex is a highly productive, free open source framework for building and maintaining expressive web applications...</span>

   6:         <br/>

   7:     </p>
      </div>

   8: </TextFlow>;

   9:

  10: private var textFlow:TextFlow = TextFilter.importToFlow(textInput, TextFilter.TEXT_LAYOUT_FORMAT);

As you can see TextFilter class is used for importing the XML and creates an instance of TextFlow. The second parameter of the import method tells what format the XML is written in. In this case I am using TLF Markup.

Creating a TextFlow using the FlowElement classes:

   1: var textFlow:TextFlow = new TextFlow();

   2: var p:ParagraphElement = new ParagraphElement();

   3: var span:SpanElement = new SpanElement();

   4: span.text = "Hello, World!";

   5: p.addChild(span);

   6: textFlow.addChild(p);