You can manipulate the renderer by editing CSS or switching which HTML document is rendered. I threw in a circular paragraph renderer just for fun. I also included a time indicator to show how long Flash takes to parse each HTML source. Even though Flash takes forever to serialize Strings to XML, this shows that tinytlf renders it almost instantaneously every time. I’ll talk about this more in my next post.

This is now the official tinytlf demo, so I’ll be updating it as I add features in the future. To demonstrate tinytlf’s capabilities beyond sanitized HTML input, I’ve included examples from Idle Words and the HTML version of Christian Cantrell’s eBook, Farmer One.

Watch or fork the project on Github.

First, I gotta apologize for pushing v1 out into the world. It was crap. I’ve changed almost everything in v2, making it smaller, faster, and more feature rich. Crazy you say? Here’s a few of the additions and changes that make version 2 smarter than version 1:

• Using Dependency Injection instead of the Facade pattern
• Consolidating all the maps into a single implementation
• Integrating HTML and CSS into the core
• Rewriting the paragraph and line renderer that handles all variations of layout [PDF], floats, and virtualization (I’m proud of my work in this area)
• Alongside the renderer, adding a parser for content blocks, which is a better abstraction for implementing percent sizing, margins, padding, lists, tables, and floats than the way I did it in v1
• A rewrite of the interaction model, implementing gestures using raix, a port of Microsoft’s incredible Rx.NET framework. (events are fun again!)
• Because of the addition of raix, I can do away with the Flash Text Engine’s EventMirrors. I’ve implemented a (faster, smaller) replacement. You can see this action in AnchorMirror.as

Dependency Injection

Instead of wiring everything up through the combination of a Facade and maps, I’ve switched to SwiftSuspenders for Dependency Injection. Using a formal IoC framework makes tinytlf infinitely more extensible, rids the framework of ceremony for the sake of it, and gives us sweet [Inject] syntax to boot. And SwiftSuspenders is only 15K; fucking awesome.

Maps maps maps

I’ve written a generic mapping class, implemented a few interfaces for the sake of IoC mappings (and to reduce map collisions), and stuck them all in the IoC container. This reduces file size and cyclomatic complexity, as each map implementation is the same. That’s not to say you can’t extend it; feel free to extend the map and replace it in the IoC container if required.

HTML and CSS

The only way anybody is going to work with text is with markup and CSS. So I wrote a small CSS parser to inject and lookup styles, and the model is a DOM built from XML.

New Rendering Algorithm

I completely rewrote the render and layout algorithms. The new algorithm is referentially transparent, with zero side effects (aside from a bit of TextLine caching for performance’ sake).

What does that mean to you? There should be no weird bugs or race conditions caused by variables you can’t replicate in testing.

The previous rendering algorithm was shit. It’s the primary reason I never implemented editing. Virtualization was hacked in. It suffered from race conditions and required property synchronization, due to an architecture that maintained state and only worked if started in the correct configuration.

I’ve rewritten the layout algorithm from the ground up, solved all these problems, and exposed more points of extension.

If you want to see the speed of the new layout algorithm, scroll through this as fast as you can (looks cool with OS X Lion’s inertial scrolling). I already know of many places it should be improved, but it’s a hell of a lot better than what it was!

New interactions via Reactive eXtensions

Reactive Programming is already a wave breaking over the .NET (and maybe JS?) world, but unfortunately ActionScript developers have been largely left behind by this revolution in interactive programming, and have suffered for it.

Big thanks to Richard Szalay for raix, his port of Rx.NET to AS3.

I wrote a class called Observables which creates and manages IObservable streams for various interaction
events, some of which (like drag, doubleDown, doubleDrag, tripleDown, and tripleDrag) are compositions of event streams.

Observables.as also allows you to register IEventDispatchers to be included in master IObservable streams. A developer can subscribe to the master streams if he’s interested in receiving events from all IEventDispatchers registered with Observables.

HTML Demo

For my demos, I’ve chosen to work with the unaltered HTML from a few posts on idlewords.com, specifically Why Arabic is Terrific, and the July 2010 index page. The text has many features I wish to support: malformed XHTML, CSS, inline styles, tables, lists, anchors, bidirectional text, and floats. Here’s the demo source, HTML, and CSS. Click here to open the SWF in a fullscreen window.

Where does that leave things?

I wrote this post to show people that the framework is back in active development. There are already many places I know where performance can be improved. I don’t have a TextField component yet, decorations aren’t done, and most HTML tags (and their layout configurations) haven’t been implemented. Editing is back on the roadmap, but not done either.

Like always, feel free to email me with questions or feature requests, and I’m always monitoring github for forks and pull requests. Happy coding!

I’m working on an official tinytlf demo explorer app, ala minimalcomps but it’s going to let you do lots of cool stuff. In the meantime, I’ll post a few choice demos to this post, kind of show off what I’ve been working on.

Mobile TextField

First up, huge updates to gestures, behaviors, and decorations. So much that I’ve been able to come up with this demo, primarily meant for Android devices, but still usable on the desktop. Highlight in this TextField:

Better HTML support

Here’s some awesome HTML demos that Tanya Gray has put together…

and… maybe Divs and Tables?

Advanced Constraint Layouts

Floats aren’t just for HTML. Floats take advantage of a more generalized layout algorithm, which flows text around constraints. Floats are just a simple (Rectangle) constraint. You can implement the ITextConstraint interface with your own constraint implementation.

Here’s a few demos that show off the layout algorithm. Special thanks to Jim Armstrong (the Algorithmist) for the spline math.

Experimental, Just for Fun

A gmail-style link editing behavior!

So you can see I haven’t been idle! It’s just a lot of work. All the code for these demos is here. Fork the framework at github!

This algorithm only works for left-aligned paragraphs, if you try it with any other alignment I can’t guarantee it’ll look good. These images don’t respect float, they’re just placed at fortuitous positions in the content. They respect box-model padding properties (padding-left, etc.). Also, I changed the default selection colors to be as close to Aqua Blue as possible.

Here’s the original Wikipedia article for comparison. As always, here’s the source for this demo. Just XHTML and CSS.

Selection

Tinytlf’s selection algorithms are character and line level algorithms, not block level algorithms like most web browsers. That means that even if you select an entire paragraph, tinytlf only knows you’re selecting from the paragraph begin index to the paragraph end index.

This leads to some interesting consequences, like an image on the first atomIndex in a line causing the entire line height to be as tall as him. You see some overlap, because tinytlf’s default selectionAlpha is 0.28.

In addition, all the decorations in tinytlf only draw underneath the TextLines. Therefore you don’t see selection over images, like you would in a web browser. Later I might allow the option for decorating on top of the Lines layer, but I’ve left it out for 1.0.

As always, the source is available here: source for these demos.

Text Layout

Ok, so say we have this wikipedia entry about the fascinating Atrophaneura hector (Crimson Rose) butterfly. It’s a nice article, and tinytlf formats it well (except for the TLMR bug):

Don’t encyclopedia entries come with an image?

Much better!

Put that image where you want it

Alright, now we’re rockin’

Ok, I know this is ugly, but I thought I’d show off a little bit. You aren’t constricted to docking on the left or the right, the new layout algorithm will wrap text around images no matter where they are in the markup.

Features

This shows off some features I’ve never talked about before. Of course there’s flow around the image, but that’s really just some fancy layout math, it’s not too complicated. I’m probably most proud of the fact that tinytlf intelligently renders only the invalid TextLines.

Invalidation

This is a Flash Text Engine feature, but it’s one that I love: when members of the FTE ContentElement model change (text, ElementFormat, etc.), the TextBlock will tag the TextLines which render the content “invalid.” The FTE can’t automatically update the TextLines; whomever renders the TextLines (tinytlf, in this case), is responsible for surgically removing and re-rendering the invalid lines.

It’s a delicate procedure, but tinytlf handles it like a champ. You see the result of this in the examples whenever you roll over an anchor tag and it changes fontPosture or color.

Layout

The second part of this is the little bit of fancy math I did to break and layout the lines in the proper order. If you want to see the algorithm, check out the newest ImageFlowContainer here.

It’s not too difficult. Basically, as I lay out the lines, I calculate the (x, y) position for the next TextLine. Because I can change the x and y independently of each other, I can break TextLines across the plane of the graphic.

Where can it go from here? My next feature will be to respect padding set on the <img/> tag. After that will be allowing a way for the <img/> to specify whether it renders inline, causes line/paragraph breaking, etc. There’s a lot that can be done.

Caveats

I haven’t tested this with more than one image. In theory it should work, but I’ve been awake for longer than 24 hours, so I can’t trust I’m actually thinking as clearly as I think I am o.O.

And yes, there’s a bug with the links. It’s especially prominent here, but basically when you move the mouse very quickly, the FTE TextLineMirrorRegions dispatch a “mouseOver” but never its corresponding “mouseOut.” If anybody on Adobe’s TLF or FTE team can shed some light on this situation, I’d be very grateful.

That’s it, happy coding. Fork it on github!

Part of that feedback was a request for more information. What makes tinytlf different? What are the features/goals of the project? And (truly) my favorite inquiries, “does tinytlf have feature X?” So I thought I’d write a followup, explaining a bit about my motivations for writing it, my goals for the framework, and a high level overview of some of its key processes.

Note: When I say TextField, I’m talking about Flash’s legacy TextField, flash.text.TextField.

Goals

Tinytlf has ambitious goals. With tinytlf, I want to create a small, extensible library for developers to write advanced text controls. I want to give developers full control over every facet of the TextField; nothing is sacred, and every piece replaceable with a more suitable implementation. I want a TextField that finally parses real HTML, and applies real CSS stylesheets. I want a TextField that, while still visually consistent, finally provides interactive capabilities on par with the OS native text controls.

Native

Flash’s TextField has never been as good as the native OS offering. Like it or not, text is a place where [the dreaded] HTML5 has a clear advantage over Flash. I’d be willing to go as far as to say that it’s one of the main reasons many web developers, “technologists” (yes I’ve seen that job description), and web-savvy users hate on Flash content. They expect their text to be selectable across TextField instances. They expect the mouse and keyboard interactions to be the same as their OS of choice. They expect the text decorations to be just as eye-popping as the rest of Flash’s visuals. And it’s sad to say they aren’t.

HTML and CSS

It’s never been very easy for Flash developers either. The most common representation of rich text on the web is HTML. The TextField does support a subset of HTML tags; 11 of them to be exact. But you are stuck with those 11, and you have virtually no control over the styling or rendering of the content. Want stars for list items instead of bullets? Too bad. Don’t want your links underlined? Tough luck.

The CSS support is pitiful too. You can import CSS into a StyleSheet object, then apply the StyleSheet to the TextField, but it too only supports a subset of styles. On top of that, the TextField is no longer editable. So bon voyage to a Rich Text Editor that respects CSS! For that, you have to use the alternate and incompatible TextFormat class, but that requires management by developers and doesn’t offer any more styling options than StyleSheet!

Modularity

These days, modularity is a buzz word thrown around for good measure. Writing modular systems is the goal of every developer and framework, but it’s a promise that is seldom kept. Tinytlf ensures modularity by keeping strict separation of concern and delegating the bulk of the functionality to small, externally defined controller classes. Tinytlf has four actor maps, which allows for controllers to be defined or replaced from the outside.

For example, every text decoration in tinytlf is written externally and mapped into the framework at startup. There’s nothing inherently special about the word “underline”, or the class that draws underline decorations. It’s only what was defined and mapped in at runtime. So if you want to write your own class that draws underlines, you can, and externally map it in and replace tinytlf’s default implementation.

This same pattern is used over and over throughout the system, and gives you a new level of control over the TextField like you’ve never had before. If you want to support a new HTML tag, you can write a controller which parses that HTML tag. If you want a new decoration, write the implementation and map it in! If you need to fix a bug in one of tinytlf’s controllers, write the fix and replace the default controller. (Then contribute it back!)

A Text Layout Framework

Allow me to define the general problems a TLF has to solve:

• Model definition and resolution/parsing
• Text decorations (underline, strikethrough, etc).
• Text interaction (both generic and context-sensitive)
• Styles/formatting (notably inline and cascading styles)
• Rendering algorithms for the font glyphs that respects styles and formatting
• Layout algorithms that respect the model, decorations, and styles of the text

Luckily, tinytlf doesn’t have to solve all these problems alone. Tinytlf gets a tremendous amount of help from the Flash Player, through the Flash Text Engine API.

Architecture Overview

Tinytlf’s architecture allows all these pieces to come together, ensuring tinytlf is more than the sum of its parts.

Tinytlf is broken into five separate projects: utils, core, gestures, extensions, and components, respectively. Each project builds on the features of the previous project. You “pay as you go,” deciding for yourself what features you need and at what cost. For ease of use, you can use the components library, which is the default TextField, and depends on every project.

If you want, you can start over from core. Tinytlf is 100% interfaces, so, much like robotlegs, the default classes are just the reference implementation.

A Text Engine

The core of tinytlf is the TextEngine actor, responsible for invalidation, selection, and tracking the TextBlocks in the TextField. TextEngine is also a facade pattern, which unifies tinytlf’s four unique subsystems: TextLayout, TextDecor, TextStyler, and TextInteractor.

Every tinytlf actor or controller class receives a reference to the central TextEngine actor. Because TextEngine is a facade, any subsystem can call into any other subsystem. For example, the interaction controllers can add or remove text decorations by accessing the TextDecor actor from the TextEngine (e.g. when you mouse over, the controller can add an underline, then when you mouse out, remove it).

Engine Configuration

In tinytlf, every actor and controller class is externally defined. So tinytlf’s TextEngine accepts an ITextEngineConfiguration implementation to set up the default actors and mappings. For example, see the tinytlf TextField’s TextFieldEngineConfiguration.

Model Agnosticism

Tinytlf is model agnostic. It doesn’t care what format your data originally comes in, only if you can convert it into a tree of FTE ContentElements. The FTE already defined the model, it’s tinytlf’s job to resolve the differences between your model and FTE’s.

The default tinytlf TextField parses XHTML. There’s nothing inherently special about XHTML; XHTML is ubiquitous and easily converted into a tree of ContentElements. But if your model is not XHTML, you can write an implementation of ILayoutFactoryMap, then replace ITextLayout's textBlockFactory instance with your own.

Maps Maps Maps

Tinytlf exposes four maps, which allows for controllers to be externally defined. Tinytlf’s actors rely on definitions in their maps, then delegate functionality to the controllers. For example, tinytlf’s TextDecor exposes a map to define the classes which draw different text decorations. Then, when TextDecor receives instructions to decorate, it checks its map for the decoration definitions:

decor.mapDecoration("bgColor", BackgroundColorDecoration);
decor.mapDecoration("strike", StrikeThroughDecoration);
decor.decorate(someObj, {bgColor: 0xFF0000, bgAlpha: 0.7, strike:true});

In this example, TextDecor will instantiate two decorations, one for “bgColor” and one for “strike.” There’s nothing inherently special about those two strings, only that they exist in the map. Because of this, the TextDecor uses the mapped classes.

This is the pattern in three other areas as well: ILayoutFactoryMap, ITextInteractor, and ITextStyler.

Gestures

For context-insensitive text interaction, tinytlf includes a gestures library. A gesture is similar in spirit to iPhone and Android gestures; a sequence of events that occur in a certain order, so that when the last event occurs, the gesture is “unlocked,” and activates its behaviors. Behaviors are tiny command classes that are meant to control one facet of interaction. A great example is the IBeamBehavior, which controls whether the cursor is an IBeam or an arrow. Gestures can have multiple behaviors, and the same behavior can be mapped to multiple gestures.

The potential here is for interactivity on par with native text controls, but also allows for flexibility between platforms, like different gestures whether the user is on a PC or Mac. Moving from desktop to mobile? Just swap out mouse-based gestures for touch-based gestures, keeping all the same behaviors, allowing you to keep a consistent experience between devices.

Layout

Layout is a complicated problem, but tinytlf manages to cope. Tinytlf has a central ITextLayout actor for the ITextEngine, which renders lines from multiple TextBlocks between multiple DisplayObjectContainers (DOC). Each DOC gets its own layout controller, called an ITextContainer. I have previously blogged about various techniques for text layout, which are part of tinytlf’s default layout controllers. I’m still working on features for tinytlf v.1.0, but the current algorithm is pretty good.

During layout and re-render, tinytlf will only render the invalid TextLines from each TextBlock. This is one of many optimizations provided by the FTE of which tinytlf takes advantage.

Still rough around the edges…

Tinytlf isn’t finished. I’m working furiously to have 1.0 for my 360|Flex session. It needs more gestures and behaviors. I’m working on the layout algorithm to get text flow around images. Of course, editability is a huge feature everybody requests. I have a general idea of where the bottle necks in the framework are, but I haven’t done much formal testing. And of course I’m committed to releasing it with full test coverage.

If you would like to help, you can email me and/or jump in any time. The simplest thing you can do is request features. I’ve built this for myself, so I’m curious about other people’s requirements. I’ve already received some awesome feature requests that have kept my brain churning. At the very least I can keep them in the back of my mind, and try to keep from short-circuiting the framework, making those features impossible.

What are you waiting for? Fork it on github!

Adobe’s TLF and tinytlf

Tinytlf isn’t affiliated in any way with Adobe’s TLF. Adobe has their project and I have mine. Tinytlf is not an add-on to Adobe’s TLF, it has no dependencies on Adobe’s TLF, and I haven’t recycled any TLF code. Tinytlf is a different effort than Adobe’s TLF.

Why?

If the TLF already exists, why create another rich-text framework? Because tinytlf represents a fundamental departure from the design concepts that drove Adobe’s TLF. Tinytlf has no dedicated model. Tinytlf doesn’t define the interactions, decorations, layouts, or styles in the framework code, tinytlf expects external definitions of what a “Text Field” is.

How does a TextField draw underlines or background colors? How does a TextField manage mouse and keyboard interaction? Instead of answering these questions in the core framework, tinytlf instead says: “here, you can draw decorations,” and “hey, you can interact with text, so how do you want to do it?”

Extreme modularity, everything is exposed and/or expected to be defined externally. Tinytlf has an interface specifically for external configuration. Take a look at the configuration for the default TextField component. Everything, from how to parse and interpret data, to which classes render text decorations, to the user gestures and behaviors that govern interaction, is mapped externally.

Tinytlf is 5 individual projects: utils, core, gestures, extensions, and components, respectively. Each adds new features and builds on top of the previous projects. It is explicitly structured with pay-as-you-go modularity. The core framework is tiny: 36kb. Including components, the whole project is 135kb.

Features

Here’s a quick list of features from the framework so far:

• Standards compliant XHTML, including inline and some block-level styles.
• Real CSS stylesheets: style inheritance, pseudo-classes, and cascading.
• A completely configurable decoration engine for drawing shapes in with text.
• A two pronged approach to interaction: inclusion of a powerful gestures API, but also the ability to keep interaction contextual to FTE ContentElements.
• Complex text layouts, including text flow between DisplayObjectContainers.
• Unordered and ordered lists.
• Did I mention CSS pseudo-classes?
• Hooking into the FTE’s performance enhancing techniques, such as only re-rendering invalid TextLines.
• The speed you expect from a TextField, the power you expect from a Text Engine.

…and so much more.

Demos

Source for both demos

From Here?

Tinytlf still has a long way to go. In the next few days and weeks leading up to my 360|Flex D.C. session, I’m going to be putting more documentation on the github wiki. I have a lengthy “Deep Dive” article that I’m editing and will post soon, as well as break up for entry into the wiki. I am aiming for a 1.0 launch at 360|Flex D.C. As always, feel free to email me with any questions, feature requests, or general feedback. Thanks!

By now you should know this series isn’t about Adobe’s Text Layout Framework, which is an advanced typography and text layout framework. The Flash Text Engine is the low-level API that TLF is built on. In Flash Player 10, the FTE resides in the flash.text.engine package.

FP 10 has this great new font rendering library, the Flash Text Engine, but it only fashions characters into TextLines of a specific width. When you think about everything else a TextField does, you begin to understand that rendering the glyphs is only a small (but still important!) percentage of the total work that’s done.

Text Layout

If you recall from my previous overview of the FTE, the main “Controller” class is TextBlock. TextBlock is a factory for TextLines. You supply a ContentElement to the TextBlock, it computes and creates the necessary TextLines to show that content. TextBlock’s rendering algorithms operate on a paragraph level; that is, one TextBlock per paragraph/one paragraph per TextBlock. For example, in the FTE, this paragraph should be represented as a single TextBlock, with multiple ContentElements that define formatting.

Paradigms from a superior layout engine

If you’re familiar with HTML styles, you know that HTML has two distinct layout paradigms: block layout and inline formatting. Block layout affects an entire block of text. Styles like padding, indentation, and margins affect layout on the block level. Inline formatting affects how the characters are rendered within blocks, such as color, size, posture, weight, justification, etc.

TextBlock’s algorithms take care of the inline formatting, because inline formatting affects whether characters flow between TextLines. It’s left up to you to apply any block formatting. For example, when you call the TextBlock’s createTextLine method, you choose the width of the TextLine. This simple option allows us, with some fancy math-e-matics, to achieve many properties of block level layout.

Layout Algorithms

We want some generalized methods for accomplishing various layouts. Everything from simple, single paragraph layouts, to layouts with block formatting, to complex mutli-TextBlock and multi-column (newspaper style) layouts.

I’ve already demonstrated the absolute simplest way: render all the lines in a while loop, finishing once the TextBlock returns null from createTextLine. This is easy and straightforward, and you can apply any kind of block formatting you wish.

var y:Number = 0;
var line:TextLine = block.createTextLine(null, 200);
while(line)
{
    addChild(line);
    y += line.ascent;
    line.y = y;
    y += line.descent;
    line = block.createTextLine(line, 200);
}

Source

Even though all it seems I’ve done is render a TextField, I’ve accomplished two tasks here: I’ve rendered every TextLine that the TextBlock decides I need, and, by incrementing a counter for the Y dimension, I’ve calculated a rudimentary layout for the TextLines.

Indentation

Now, applying indentation is super easy. Make the first line a little smaller, and change his x position to compensate.

var y:Number = 0;
var line:TextLine = block.createTextLine(null, 185);
line.x = 15;
while(line)
{
    addChild(line);
    y += line.ascent;
    line.y = y;
    y += line.descent;
    line = block.createTextLine(line, 200);
}

Source

Alignment

Center:

var y:Number = 0;
var line:TextLine = block.createTextLine(null, 200);
while(line)
{
    addChild(line);
    y += line.ascent;
    line.y = y;
    line.x = (200 - line.width) * 0.5;
    y += line.descent;
    line = block.createTextLine(line, 200);
}

Source

Right alignment is the same, only don’t multiply the calculated x by 0.5.

Source

See? Standard layout practices, ultimately the same math we use every day in component layouts. But, you say, “indentation and alignment are easy, it’s just calculating the x of the lines”. You’re right, it is easy. But so are the other block formatting properties like padding, margins, line spacing, etc. They’re all just calculating the correct x or y and conditionally applying them in the loop.

Multi-TextBlock layout

Ok, now we know how to layout lines from a single TextBlock. With a little code reuse, laying out multiple TextBlocks is a breeze:

var blocks:Vector.<TextBlock> = new <TextBlock>[block1, block2];
var y:Number = 0;
for(var i:int = 0; i < blocks.length; ++i)
{
    y = layoutBlock(blocks[i], y);
    y += 5;
}
// Returns the aggregate y after this layout operation
function layoutBlock(block:TextBlock, y:Number):Number
{
    var line:TextLine = block.createTextLine(null, 185);
    line.x = 15;
    while(line)
    {
        addChild(line);
        y += line.ascent;
        line.y = y;
        y += line.descent;
        line = block.createTextLine(line, 200);
    }
    return y;
}

Source

Multi-Container layout

Ah, now we’re getting to the good stuff. Multi-container layout is really cool, because it allows us to “overflow” text from one DisplayObjectContainer to another, which allows us, among other things, to achieve column layouts.

The general idea is to render as many TextLines into a DisplayObjectContainer (DOC) as possible. When we’ve hit his boundaries, switch to the next available DOC. We can accomplish this with a few modifications to the previous methods. The layout method needs to return the last TextLine that fit in the DOC. That way, we can re-enter the layout routine and pick up with the TextBlock where we left off.

var line:TextLine = layoutBlock(block, null, container1);
if(line)
    line = layoutBlock(block, line, container2);
 
// Returns the last line rendered out of the TextBlock
function layoutBlock(block:TextBlock, previousLine:TextLine, 
                             container:DisplayObjectContainer):TextLine
{
    var line:TextLine = block.createTextLine(previousLine, container.width);
    var y:Number = 0;
    while(line)
    {
        container.addChild(line);
        y += line.ascent;
        line.y = y;
        y += line.descent;
        //If we reached the height boundary, return the last line that fit.
        if(y + line.height > container.height)
            return line;
        line = block.createTextLine(line, container.width);
    }
    return line;
}

Source

Multi-TextBlock and Multi-Container layout

Here’s the really good stuff! Now we’re going to render multiple TextBlocks into multiple DisplayObjectContainers by merging the two methods above.

To solve this problem, lets identify our list of knowns:

1. We have a list of TextBlocks.
2. We have a list of DisplayObjectContainers to fit the TextBlocks into.
3. We wish to render as many lines into each DOC as possible.
4. When the DOC is full, switch to the next one and pick up where we left off.
5. We need to keep track of the last TextLine rendered, so we know where we left off.

From our previous experience with rendering multiple TextBlocks, we know that TextBlock will return null when he can render no more lines. And from our previous experience with rendering across DisplayObjectContainers, we know that when a Container is full, we should return the last line that fit. Therefore the logic plays out as such:

• Loop over each TextBlock.
• Render as many TextLines into the DOC as possible, returning the last line rendered.
  1. If the TextLine is null, we know the TextBlock ran out of lines and there’s more space in the DOC. Keep the same DOC, but move to the next TextBlock.
  2. If the TextLine is not null, there are still more lines in the TextBlock, but this DOC ran out of space. Keep the same TextBlock, but move to the next DOC.
• If we reach the end of either list, return.

var blocks:Vector.<TextBlock> = new <TextBlock>[block1, block2, block3, block4];
var containers:Vector.<DisplayObjectContainer> = 
    new <DisplayObjectContainer>[container1, container2, container3];
 
layout(blocks, containers);
 
function layout(blocks:Vector.<TextBlock>, containers:Vector.<DisplayObjectContainer>):void
{
    var blockIndex:int = 0;
    var containerIndex:int = 0;
 
    var block:TextBlock;
    var container:DisplayObjectContainer;
 
    var line:TextLine;
    while(blockIndex < blocks.length)
    {
        block = blocks[blockIndex];
        container = containers[containerIndex];
 
        line = layoutInContainer(container, block, line);
 
        if(line && ++containerIndex < containers.length)
        {
            container = containers[containerIndex];
            containerY = 0;
        }
        else if(++blockIndex < blocks.length)
            block = blocks[blockIndex];
        else
            return;
    }
}
 
var containerY:Number = 0;
 
function layoutInContainer(container:DisplayObjectContainer, 
                                   block:TextBlock, previousLine:TextLine):TextLine
{
    var line:TextLine = createTextLine(block, previousLine);
    while(line)
    {
        container.addChild(line);
        containerY += line.ascent;
        line.y = containerY;
        containerY += line.descent;
 
        if(containerY + line.height > container.height)
            return line;
 
        line = createTextLine(block, line);
    }
 
    //This will be null.
    return line;
}
 
function createTextLine(block:TextBlock, previousLine:TextLine):TextLine
{
    var w:Number = 190;
    var x:Number = 0;
    //Apply indention properties here.
    if(previousLine == null)
    {
        w -= 15;
        x += 15;
    }
    var line:TextLine = block.createTextLine(previousLine, w, 0.0, true);
    if(line)
        line.x = x;
    return line;
}

Source
Text Source

Woah! Take a breather

It’s a lot to digest, I know. But now you can see that TextLayout isn’t black-magic voodoo, and is entirely achievable in the new Flash Text Engine. If you have any questions, feel free to comment or email me. If you have any techniques for text layout, or have any comments on my techniques, I’d love to hear those too. I took some shortcuts with these demos, but I’ve built out more complete and performance-tuned layouts into tinytlf, the small text layout framework I’ve been working on clandestinely for a few months.

Aside: Text Layout vs. Component Layout

In typical component based layout engines (such as Flex’s), child creation is separate from layout. Usually all the children are added to the display list first, then laid out at some other time. Children aren’t created or destroyed based on their positions or sizes on the screen, and layout doesn’t affect the creation of future children (this is assuming we’re not talking about virtualized layout, which is a special case).

Working with the sizing and layout of TextLines, the block-level layout properties (like padding, indentation, etc.) dictate how each TextLine is created and laid out. This in turn affects how the TextBlock renders the next TextLine, and so on and so forth. I haven’t been able to separate block-level layout properties from the TextLine creation process. This isn’t so bad in practice, but sometimes it rubs me the wrong way, I feel like there should be a better way and I just haven’t found it yet.

To clarify, this series isn’t about Adobe’s Text Layout Framework, which is an advanced typography and text layout framework. The Flash Text Engine is the low-level API that TLF is built on. In Flash Player 10, the FTE resides in the flash.text.engine package.

Interaction in the Flash Text Engine

In my previous post on the Flash Text Engine, I ran through the basics of what you need to get the FTE to render TextLines. While rendering lines on the screen is nice, this post is about how to add interaction to the TextLines that are produced.

TextLines are InteractiveObjects. You can add event listeners directly to them and listen for interaction events. The FTE also gives you the option to associate an individual EventDispatcher instance with a single ContentElement, so that when the user interacts with the data of the ContentElement, the events are cloned to the EventDispatcher instance you specified. As I discuss the details, you’ll see that each approach has its own strengths and weaknesses.

Approach 1: TextLines as InteractiveObjects

Since TextLine is an InteractiveObject, you can simply listen for Mouse and Keyboard events on each TextLine instance. With this approach, you know the TextLine that was interacted with. The main drawback here is that TextLine knows almost nothing about the ContentElement which it is rendering. Multiple ContentElements can be rendered into the same TextLine, and multiple TextLines can render the same (really long) ContentElement.

Interact with the lines in this demo:

Source

The fact that you don’t know about the content of the TextLines is ok though, for some problems that isn’t necessary. For example, you don’t really need to know about the contents of the TextLines to draw decorations, such as underline, strikethrough, or selection.

Select this text:

Source

Approach 2: Working with TextLineMirrorRegions (TLMRs)

The preferred method of managing interaction in the Flash Text Engine is with TextLineMirrorRegions.

If you read my previous post, you’ll remember that to render any text, you have to create instances of any of the Flash Text Engine’s model classes: TextElement, GraphicElement, or GroupElement. When you create an instance of these classes, you can specify an EventDispatcher as the eventMirror for the ContentElement. When the user interacts with the visual representation of this ContentElement via TextLines, the events are re-dispatched to the eventMirror you specified. This allows you to know when a user interacts only with a particular ContentElement.

In this code sample, I create an EventDispatcher to pass in as the eventMirror for the TextElement. Then I add a listener for mouseMove on the eventMirror instance. This will trace out every time you mouse over the TextElement.

var dispatcher:EventDispatcher = new EventDispatcher();
new TextElement('Inspiring quote here.', new ElementFormat(
                                         new FontDescription()), 
                                         dispatcher);
var onMouseMove:Function = function(e:MouseEvent):void{
    trace('Mouse move on ' + e.target.toString());
}
dispatcher.addEventListener(MouseEvent.MOUSE_MOVE, onMouseMove);

These two lines are part of the same TextElement:

Source

How is this different from the previous demo? TextLine has a property called mirrorRegions, a Vector of TextLineMirrorRegion instances. Since multiple ContentElements can be rendered by a single TextLine, TextLine creates TLMR instances for each ContentElement with an eventMirror, then associates the TLMRs with the eventMirrors respectively.

TextLine listens on itself for interaction events. When the events overlap with any of the TLMRs, TextLine notifies the appropriate TLMR of the event. After all normal event processing for the TextLine is done, each TLMR re-dispatches the events it was notified of to its eventMirror instance.

In this example, I added a listener for the “mouseDown” event on both the TextLine and the ContentElement’s eventMirror. Notice that the event dispatched on the eventMirror happens second.

Source

Here’s what the TLMRs look like (I’ve drawn boxes for each boundary of a TextLineMirrorRegion).

Source

Caveats

Of course, this wouldn’t be a Flash Player feature if it didn’t come with caveats ;).

TextLineMirrorRegion simulates the events, it doesn’t re-dispatch the exact instance it received from the TextLine. This is because TLMR isn’t an InteractiveObject itself. If you utilize the eventMirror to listen for MouseEvents, just realize they’re all faked — even though TextLine is the target, they didn’t originate from TextLine, and they don’t have feelings like real player-native events do.

rollOver/rollOut events

This event simulation means that we’re at the mercy of what Adobe chooses to simulate. They didn’t feel the need to simulate the roll events (rollOver/rollOut), so if you try to listen for them on the eventMirror, you won’t get them. Presumably this is because the roll events aren’t needed; since ContentElements don’t have display-list children, the roll events would be exactly the same as mouseOver/mouseOut.

Except the roll events are still very relevent.

It’s true, we’ve shifted from a display-list hierarchical structure (DisplayObjectContainers, etc.) to a ContentElement hierarchical structure. And it’s true, ContentElements don’t have display-list children. But they can have other ContentElement children, which means the roll events are still very relevant.

For example, if you had this XML model to render:

<p>
  Outside the group. 
  <group>
    <text color="#44AA00">
      First group child.
    </text>
    <text color="#AA0044">
      Second group child.
    </text>
  </group>
  Outside the group.
</p>

You might want to know only when the entire group node is interacted with (just like when you have a DisplayObjectContainer with children).

Here’s the demo of this model. Mouse between the boundary of the first child and the second child, and notice how you get a “mouseOut” and then another “mouseOver” from the group. If this were the roll events, you would only get the “mouseOut” and “mouseOver” from the children, but hear nothing from the group. FYI, “mouseDown” clears the debug lines.
Source

Comparison

So, how do the two techniques match up? The short answer is that each one accomplishes a different task. If you need the very base of interaction capabilities without the context of what you’re messing with (e.g. text selection), adding listeners straight on your TextLines is the way to go. However, if you need the context of which ContentElement the user interacts with (e.g. to mimic an HTML anchor tag), there’s no way around it, you have to use the event mirroring approach.

P.S. Isn’t it freaky interacting with text that you can’t select? Maybe I’m just OCD, but I feel a strong desire to see an I-Beam mouse cursor every time I hover over FTE text. My favorite demo to write was the second one, because not only did I get to come up with a quick selection-drawing method, I added the freakin’ I-Beam cursor. Anyway, hope you enjoyed this and good luck :).

To clarify, this series isn’t about Adobe’s Text Layout Framework, which is an advanced typography and text layout framework. The Flash Text Engine is the low-level API that TLF is built on. In Flash Player 10, the FTE resides in the flash.text.engine package.

The FTE is designed to render text “document style”. It’s primarily meant to replace the TextField for advanced uses, not provide a whole framework for text layout on the scale of an HTML rendering engine.

The FTE handles what I call flow: formatting that causes text to be pushed to the next line in a paragraph. I don’t know if that’s the official term, but it seems to fit. It does not do layout, which is things like bullet points, indentation, wrapping around images, padding, etc., nor does it handle decoration, things like underline, strikethrough, background color, selection, etc. I believe the FTE leaves these out because 1.) layout is a much more complicated and nuanced problem than flow, one that you wouldn’t necessarily want in the FP core, and 2.) decorations don’t cause reflow, or affect whether and how text is wrapped to the next line.

The FTE conforms to a small MVC architecture, there are about 10 core classes that provide most of the functionality, with the rest of them encapsulating constants. Something to note, every class in the FTE is final :( more on that later.

The FTE Model

The basis of the Flash Text Engine model is something called ContentElement. ContentElement is an abstract base class. You never call new ContentElement() (it’s similar to DisplayObject in this regard), instead you instantiate one of its 3 subclasses: TextElement, GraphicElement, or GroupElement. Collectively these classes describe a Tree hierarchy for text, but I want to talk a bit more about ContentElement before we get too deep into that.

ContentElement

Take a look at the constructor of ContentElement:

ContentElement(elementFormat:ElementFormat = null, eventMirror:EventDispatcher = null, textRotation:String = "rotate0")

It has two important arguments, elementFormat and eventMirror (as well as a third less important argument, unless you’re one of the crazy types who likes to rotate text). I will come back to the eventMirror later, but for now lets just talk about ElementFormat.

The ElementFormat class describes most of the properties that handle text flow. It has a fontDescription member, which is exactly what it sounds like. In FontDescription you’ve got your standard fontFamily, fontWeight, fontPosture (which is traditionally the fontStyle in Flash), along with how the font is supposed to be retrieved from the depths of the Flash Player (as Compact Font Format or a device font).

ElementFormat has properties like alpha, color, baselineShift, kerning, etc. Basically anything that can affect reflow.

Ok, so that describes all you need to know for now about the ElementFormat and FontDescription objects. Now onto the implementation class you’ll use.

TextElement

Out of the three, TextElement is the most straightforward. It simply accepts a string of text to take care of:

TextElement(text:String = null, elementFormat:ElementFormat = null, eventMirror:EventDispatcher = null, textRotation:String = "rotate0")

The ElementFormat you pass in is applied to the entire string of text that this TextElement owns. So if you specify an ElementFormat with a color of red, the entire string of text will render red.

GraphicElement

The next one to worry about is GraphicElement. He accepts any DisplayObject instance (instance!), as well as the width and height that you wish to allocate for the Graphic in the text:

GraphicElement(graphic:DisplayObject = null, elementWidth:Number = 15.0, elementHeight:Number = 15.0, elementFormat:ElementFormat = null, eventMirror:EventDispatcher = null, textRotation:String = "rotate0")

Some of the properties of the ElementFormat will apply to the GraphicElement, such as alpha, baselineShift, etc. Obviously the GraphicElement doesn’t respect font-specific settings from the ElementFormat and FontDescription objects.

GroupElement

Lastly there’s the GroupElement:

GroupElement(elements:Vector.<ContentElement> = null, elementFormat:ElementFormat = null, eventMirror:EventDispatcher = null, textRotation:String = "rotate0")

GroupElement is critical. GroupElement is a collection of any combination of TextElements, GraphicElements, or other GroupElements. GroupElement is the Tree functionality of FTE’s model. TextElement can’t have children, it controls a single String. Likewise, GraphicElement only describes a single DisplayObject instance. GroupElements tie it all together.

GroupElements provide an API for doing standard Tree functions; you can retrieve, split, merge, and group children using various methods. I speak from experience when I say you won’t often mess with this unless you’re writing an editable text field. And if you are writing an editable text field, God help you (just kidding, it is hella fun).

OK, enough Model talk. Onwards to…

The FTE View

There are two (2!) classes that make up the entirety of the Flash Text Engine’s View division: TextLine and TextLineMirrorRegion. Right now you can forget about TextLineMirrorRegion, as that has to do with interaction, which is a complicated topic and one which I will cover in detail later. So for now, only focus on TextLine.

TextLine

TextLine is a DisplayObjectContainer. Yes, that means it has the get/add/removeChild methods (they still work!), and is also an InteractiveObject. You can listen for all the normal interaction events. However, even though it inherits from InteractiveObject, there are a few properties that you can only read, not write. Those are detailed in the documentation for TextLine.

TextLine adds the concept of atoms, which are indivisible characters in a TextLine. Individual characters are atoms, as well as any graphics you have. The important thing to know here is that atoms can never be split between lines. The FTE will measure only to the atom level, no lower.

Atom information can be expensive to keep around… At first the TextLine only renders its text, it doesn’t know anything about the atoms it contains. However calling various methods will cause the TextLine to create its atom data. For example, if you call getAtomIndexAtPoint(), the TextLine must create the info about each atom so it can then calculate which atom occurs at the point you specify. This is all well and good, but be sure to call flushAtomData() once you’re done so the atom data will be GC’d.

TextLine has a reference to the previous and next lines, because TextLine is also a doubly-linked list! How convenient! Of course, if there is no previous or next, you know you’re the first or last lines, respectively.

TextLine also has a validity status, which is whether the ContentElement that the line represents has changed since the line was rendered. Values are described in the TextLineValidity class.

One thing that TextLine definitely is not: a Sprite. No, TextLine is a DisplayObjectContainer. The most important implication from this is that TextLine has no graphics context. This means you can’t call textLine.graphics.draw. :( Oh well.

TextLine is a concrete class, you use it directly, but you cannot instantiate one by calling its constructor. To do that you need…

The FTE Controller

There is arguably one class in the FTE’s Controller division: TextBlock. I say arguably because yeah, TextJustifier and TabStop exist, but they just affect how TextBlock does its rendering, not… hm. Ok, I’ve convinced myself that they count as Controller classes too, but only barely.

But believe me, you will come to think of TextBlock as the only Controller class too.

The TextBlock is a fairly standard Factory pattern implementation: TextBlock’s primary job is to accept a ContentElement as input and output as many TextLines as you want, given a width. ContentElement -> TextBlock -> TextLines. Got it? Me neither.

Ok, so TextBlock has this method called createTextLine():

createTextLine(previousLine:TextLine = null, width:Number = 1000000, lineOffset:Number = 0.0, fitSomething:Boolean = false):TextLine

Ok so what you do is you pass in the previous line that you created, plus the width that you want the current line to be, and TextBlock will measure out a TextLine for you. Are you seeing the doubly-linked list yet?

If you want to create the first line from a TextBlock, you should just pass in null to the createTextLine() method; assuming the TextBlock has content in his content property, and that content has at least one atom (characters or graphics), passing in null will always return a TextLine. If there are no more lines to be created, TextBlock will return null from the call to createTextLine().

So from this it is simple to render the lines for a TextBlock with width 200:

var y:Number = 0;
var line:TextLine = block.createTextLine(null, 200);
while(line)
{
    addChild(line);
    y += line.height;
    line.height = y;
    line = block.createTextLine(line, 200);
}

Ok, I’ve detailed a lot so far, now it’s time to get to at an example.

Flash:

Here’s the code for the above simple line rendering:

package
{
  import flash.display.Sprite;
  import flash.text.engine.ContentElement;
  import flash.text.engine.ElementFormat;
  import flash.text.engine.FontDescription;
  import flash.text.engine.FontPosture;
  import flash.text.engine.FontWeight;
  import flash.text.engine.GroupElement;
  import flash.text.engine.TextBlock;
  import flash.text.engine.TextElement;
  import flash.text.engine.TextLine;
 
  [SWF(width="450", height="32")]
  public class SimpleDemo1 extends Sprite
  {
    public function SimpleDemo1()
    {
      super();
 
      var e1:TextElement = new TextElement('Consider, what makes a text line a ', new ElementFormat(new FontDescription(), 24));
      var e2:TextElement = new TextElement('text line', new ElementFormat(new FontDescription("_serif", FontWeight.NORMAL, FontPosture.ITALIC), 24));
      var e3:TextElement = new TextElement('?', new ElementFormat(new FontDescription(), 24));
 
      var e:Vector. = new Vector.();
      e.push(e1, e2, e3);
 
      var block:TextBlock = new TextBlock(new GroupElement(e));
      var line:TextLine = block.createTextLine(null, stage.stageWidth);
 
      var _y:Number = 0;
      while(line)
      {
        addChild(line);
        _y += line.height;
        line.y = _y;
        line = block.createTextLine(line, stage.stageWidth);
      }
    }
  }
}

Holy crap Batman!
As you can see, it required 3 different TextElements and a GroupElement to render some freakin’ italic text in the middle of a sentence. Yeah. Par for the frickin’ course.

In part 2 I’ll get into more details about interaction, TextBlock manipulation, all of it.
Till then watch this project on github: tinytlf. It’s due for some major updates but it’s what I’m going to start talking about soon.