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!

Flash and the City

Before I begin, this was the topic of my Flash and the City talk this year. You can find the slides here if you want.

Auto Mediation

Robotlegs has an interface called IMediatorMap, which maps UIComponent types to Mediator types. Robotlegs watches the display list, and when instances of any mapped components are added to (or removed from) the stage, it will create (or destroy) an instance of the mapped Mediator for it.

mediatorMap.mapView(MyViewType, MyViewMediator);

Each time you create and add a new instance of MyViewType to the stage, a corresponding MyViewMediator instance will be created.

Problems

The problem with MediatorMap is two-fold:

1. It enforces an arbitrary restriction that each View instance can only have one Mediator instance. This is dangerous, because it blurs the line between view logic and business logic. Does this functionality belong in the UIComponent or the Mediator? Developers end up writing Views and Mediators with poor separation of concerns, and inevitably overflow View logic into their Mediators. Mediators aren’t seen as reusable bits of business logic, they’re seen as an extension to the UI component.
2. MediatorMap is a type invariant mapping. The map creates a Mediator only if the view component is an exact instance of a mapped type.

   For example, if you register the MyViewComponentMediator type for MyViewComponent, subclasses of MyViewComponent (say, MyViewComponentSubclass) don’t get an instance of MyViewComponentMediator automatically created for them.

   If MyViewComponent encapsulates enough useful functionality to supplement it with its own Mediator, doesn’t MyViewComponentSubclass still implement (through inheritance) and require the same functionality from the MediatorMap? Sure, the subclass may override certain functions, but that’s just polymorphism at work.

Covariant Auto Mediation

The idea behind covariant mediation is that a Mediator is created if a component extends or implements a mapped view component type.

Here’s the practical difference between an invariant check and a covariant check:

//Invariant check:
if(myViewComponent.constructor == MyViewComponent){
    //Do something
}
 
//Covariant check:
if(myViewComponent is MyViewComponent){
    //Do something else
}

If the instance of myViewComponent is actually a subclass of the MyViewComponent type, the first check will fail, but the second check will pass.

Extends or Implements

Extending classes for functionality is all well and good, but it’s not as flexible or as clean as implementing an interface. For starters, AS3 allows you only one parent class, so you can’t compose much functionality through inheritance before running into the diamond problem.

Before I go any further, yes, this means you can map a Mediator for all instances or subclasses of Sprite or UIComponent.

// An instance of SpriteMediator will be created each time an instance
// or subclass of Sprite is added to the display list. Crazy, huh?
map.mapMediator(Sprite, SpriteMediator);

Naturally this introduces performance problems, so everything from the “flash.*” and “mx.*” packages are filtered out by default.

map.registerPackageFilter('flash.*');
map.registerPackageFilter('mx.*');

And you can add your own package filter definitions (like if you’ve got a particle emitter and want to skip inspection of each particle):

map.registerPackageFilter('com.myApp.particles.*');

Anyway, covariantly auto-mediating base classes is alright I guess, but who wants to maintain a complex inheritance tree? Not me. The real sexy magic happens when you start mapping Interfaces for auto-mediation.

Interfaces are covariantly checked:

trace(myComponent.constructor == IMyInterface); //will always be false
trace(myComponent is IMyInterface); //can evaluate to true

Demo Time

This post has been highly theoretical so far, and if you let me continue extolling the virtues of designing interfaces to apply behaviors to components via covariant mediation it will only devolve into something more abstract and academic.

So instead, I’ll show off some code to do it for me. Here’s the demo app I created for my FATC talk.

This demo has three progressively more impressive examples of common problems solved in very few LOC using covariant mediation:

1. An example of handling system-wide error events.
2. An example of managing selected screen state.
3. An example DataGrid where each cell is representative of a unique and open streaming channel from the server.

Rundown

I’ll run through just the meaty parts of this demo. The source for the whole thing is here.

App.mxml and IoC Mappings

Here’s the important part of the Application MXML file:

override protected function createChildren():void
{
	// Normally these IoC mappings are done inside the Context.
	// Do them here because we have access to our children.
	var context:FATC_Context = new FATC_Context(systemManager as DisplayObjectContainer);
 
	var map:IVariantMediatorMap = context.variantMap;
 
	// Map implementations of ISystemErrorUI to have
	// SystemErrorUIMediators registered for them automatically
	map.mapMediator(ISystemErrorUI, SystemErrorUIMediator);
	// Map implementations of IScreen to have ScreenMediators
	// registered for them automatically
	map.mapMediator(IScreen, ScreenMediator);
	// Map implementations of IStreamingServiceUI to have
	// StreamingServiceUIMediator registered for them automatically
	map.mapMediator(IStreamingServiceUI, StreamingServiceUIMediator);
 
	var injector:IInjector = context.theInjector;
	// Tell the injector to create and inject a new instance of
	// StreamingService each time it sees a dependency on IStreamingService
	injector.mapClass(IStreamingService, StreamingService);
 
	super.createChildren();
 
	// Register the mediators for the Screens class immediately.
	// (normally the registration is deferred to the next frame).
	map.registerMediators(screens);
}

ISystemErrorUI and the SystemErrorUIMediator

public interface ISystemErrorUI
{
	function handleError(error:SystemErrorEvent):void;
 
	function get errorAcknowledged():ISignal;
}

Components that are interested in being notified when errors occur can implement the ISystemErrorUI interface. Whenever an error happens in the Application, it’s the responsibility of the errored operation to dispatch a SystemErrorEvent, either bubbling on the display list, or on robotlegs’ shared eventBus. Each instance of SystemErrorUIMediator will notify its ISystemErrorUI instance.

IScreen and the ScreenMediator

public interface IScreen
{
	function set selectedScreen(screen:IScreen):void;
 
	function get screenChangedSignal():ScreenChangedSignal;
}

Implementations of IScreen will be notified when the selectedScreen changes. Implementations of IScreen can cause the screen to change by dispatching their screenChangedSignal member.

Whether the implementor of IScreen truly wishes to change the selectedScreen, or whether it’s simply interested when the selectedScreen is changed, the ScreenMediator doesn’t care. In the demo, three of the four implementations of IScreen respond uniquely when their selectedScreen setter is called:

1. The Screens class is a ViewStack. When its selectedScreen setter is called, it checks first whether the IScreen instance is a child of itself. If not, Screens adds it as a child. Screens ultimately changes its selectedChild property to the new IScreen.
2. The ErrorNotificationView class is the bar at the top that drops down when an error occurs. If the bar is showing and the selectedScreen setter is called, the bar hides itself.
3. The StreamingServiceItemRenderer class is the item renderer for the DataGrid. When the selectedScreen changes to and from the GridScreen instance, StreamingServiceItemRenderer starts or stops the incoming data stream. In this way, we can shut down any data sources for screens that aren’t currently visible.

IStreamingServiceUI and the StreamingServiceUIMediator

public interface IStreamingServiceUI
{
	function setStreamData(value:StreamData):void;
 
	function get updateStreamInfo():ChangeStreamInfoSignal;
}

There’s only one implementation of IStreamingServiceUI: StreamingServiceItemRenderer. StreamingServiceItemRenderer is the item renderer for each cell in the DataGrid.

StreamingServiceItemRenderer takes advantage of the fact that the DataGrid reuses its itemRenderers. When the user scrolls, the DataGrid sets in a new value for data. When that happens, the itemRenderer dispatches its updateStreamInfo member Signal.

When the UI dispatches its updateStreamInfo Signal, StreamingServiceUIMediator tells the service instance the new channel name. Then, the service closes its current channel, and opens a stream with the new channel name.

Because the DataGrid reuses its itemRenderers, and the itemRenderers dispatch changes in its data values to its Mediator, the Mediator can reuse its service instance, which manages opening and closing streams.

This means we only keep open connections for visible cells.

Pretty cool, huh?

Cunning Line Breaks

BreakOpportunity is relatively straightforward. It directs the Flash Text Engine of when to break new TextLines. It’s different from the standard unicode line breaking control character, the break-if-you-wanna Zero-width space character, and it isn’t the soft hyphen used in auto-hyphenation engines.

BreakOpportunity is subtler. It gives you control over line breaks without inserting control characters into your content.

Documentation

Here’s the documentation of breakOpportunity. I’m pasting it here to illustrate that this doesn’t tell the whole story.

Standard Line Breaking

I’ve posted this before, but here’s a refresher. Breaking lines in the Flash Text Engine couldn’t be easier:

var content:ContentElement = new TextElement("Some example text to be broken into TextLine objects by a TextBlock instance.", new ElementFormat());
var tb:TextBlock = new TextBlock(content);
var line:TextLine = tb.createTextLine(null, 200);
var y:Number = 0;
while(line != null)
{
    addChild(line);
    y += line.ascent;
    line.y = y;
    y += line.descent;
    line = tb.createTextLine(line, 200);
}

Tricks

But what happens if we modify the breakOpportunity of the ElementFormat?

var ef:ElementFormat = new ElementFormat();
ef.breakOpportunity = BreakOpportunity.ALL;
var content:ContentElement = new TextElement("Some example text to be broken into TextLine objects by a TextBlock instance.", ef);
var tb:TextBlock = new TextBlock(content);
var line:TextLine = tb.createTextLine(null, 200);
var y:Number = 0;
while(line != null)
{
    addChild(line);
    y += line.ascent;
    line.y = y;
    y += line.descent;
    line = tb.createTextLine(line, 200);
}

As you can see, when the ElementFormat for a TextElement has its breakOpportunity set to BreakOpportunity.ALL, the TextBlock breaks a new TextLine instance after each character. Crazy right?

When I figured this out about 9 months ago, my next thought was to test how GroupElement responds to BreakOpportunity:

var ef:ElementFormat = new ElementFormat();
ef.breakOpportunity = BreakOpportunity.ALL;
 
var group:GroupElement = new GroupElement(
    new <ContentElement>[
    new TextElement("Some example text ", new ElementFormat()),
    new TextElement("to be broken into ", new ElementFormat()),
    new TextElement("TextLine objects by ", new ElementFormat()),
    new TextElement("a TextBlock instance.", new ElementFormat()),
    ], ef);
 
var tb:TextBlock = new TextBlock(group);
var line:TextLine = tb.createTextLine(null, 200);
var y:Number = 0;
while(line != null)
{
    addChild(line);
    y += line.ascent;
    line.y = y;
    y += line.descent;
    line = tb.createTextLine(line, 200);
}

Sweet. So it does what the documentation says it’ll do, break between adjacent TextElements. But is it only TextElements? What about adjacent GraphicElements?

var ef:ElementFormat = new ElementFormat();
ef.breakOpportunity = BreakOpportunity.ALL;
 
var group:GroupElement = new GroupElement(
    new <ContentElement>[
        new TextElement("Some example text ", new ElementFormat()),
        new GraphicElement(new GraphicRect(), 20, 20, new ElementFormat()),
        new TextElement("with GraphicElements ", new ElementFormat()),
        new GraphicElement(new GraphicRect(), 20, 20, new ElementFormat()),
        new TextElement("to be broken into ", new ElementFormat()),
        new TextElement("TextLine objects by ", new ElementFormat()),
        new TextElement("a TextBlock instance.", new ElementFormat()),
    ], ef);
 
var tb:TextBlock = new TextBlock(group);
var line:TextLine = tb.createTextLine(null, 200);
var y:Number = 0;
while(line != null)
{
    addChild(line);
    y += line.totalHeight;
    line.y = y;
    line = tb.createTextLine(line, 200);
}

Ah ha! So it doesn’t only work for TextElements, it works for any siblings enclosed in a GroupElement. Good to know. Can you imagine the implications of this? (hint, this is important for rendering floats using the FTE!)

package my.project.package.utils
{
    public class Type
    {
        private static const cache:Dictionary = new Dictionary(false);
        public static function describe(value:Object):XML{};
    }
}

The describe function caches the results of a call to describeType() based on the type of Class passed in as the Value. But it’s super ugly! All over the place I’ve had to reference a static class: “Type.describe(myObject);” lame.

Why can’t the results of describeType() just be cached in the player? Maybe it is now and I just don’t know it? If so, please tell me!

So here’s the solution if you’d rather have a global function than a static method call:

package org.tinytlf.utils
{
	import flash.utils.*;
 
	public function reflect(type:Object, refreshCache:Boolean = false):XML
	{
		const typeCache:Dictionary = ReflectionCache.cache;
 
		if(!(type is Class))
		{
			if(type is Proxy)
				type = getDefinitionByName(getQualifiedClassName(type)) as Class;
			else if(type is Number)
				type = Number;
			else
				type = type.constructor as Class;
		}
 
		if(refreshCache || typeCache[type] == null)
			typeCache[type] = flash.utils.describeType(type);
 
		return typeCache[type];
	}
}
 
import flash.utils.Dictionary;
 
internal class ReflectionCache
{
	public static const cache:Dictionary = new Dictionary(false);
}

An internal class! Yipee! Static, but internalized. Until now I didn’t think you could store a static stateful reference for global functions to use.

Now you can go around all over the place calling “reflect(myObject);”, enjoying the convenience of describeType() and the benefits of using a static method.

But programming for it is crazy! Have you seen this language? What is this shit?

Relax

This post is Objective-C syntax for the average Flash developer. It isn’t that scary. The colors are just different than you’re used to. And you’ll have to know or learn C, but don’t worry if you’re unfamiliar, I have faith you’ll pick it up quick enough. Because you’re creative and curious and you like learning new things dammit.

Syntax

So why haven’t you jumped into iOS? For me, it was the syntax. So now I’m going to compare the syntax of the languages from an AS3 dev’s point of view. In the end, I hope you won’t feel as intimidated as I did by this weirdly beautiful language.

Disclaimer

I’m still learning this stuff too. If I’m wrong on anything, please post it in the comments. I’m trying to disseminate useful information, things that took me a bit of studying to figure out, in the hopes that it won’t take you as long.

Primitives

There are a few keyword differences:

AS3		Objective-C
true		YES
false		NO
null		nil
this		self

Variables

Variable declaration and assignment:

// AS3
var myInteger:int = 1;

// Objective-C
int myInteger = 1;

You can see, this isn’t any different from C++, Java, C#, etc. The difference from AS3 is the lack of the required var or const keyword, and the type is specified before the variable.

Memory Allocation

Something we don’t typically think about in AS3: stack vs. heap allocation.

The Stack is a LIFO (last in, first out) pool of memory blocks that are allocated/deallocated very quickly. Each time you call a function, a block of memory is allocated for the function’s scope. When you return from the function, the block of memory is released back to the stack. This means stack-managed memory blocks are reused very frequently, therefore is mostly allocated from RAM or even the CPU’s cache, making it extremely fast.

The Heap is more complex, and allocates and deallocates memory based on usage patterns. I am not remotely familiar with how Objective-C allocates memory from The Heap, but in general, allocating/deallocating memory from the heap takes longer than from the stack.

Here’s a better explanation of the difference between the stack and the heap. This stuff is just generally good to know.

Values

Values are primitive types, allocated on the stack, and passed by value, or copied. That is, if you pass the variable as an argument to a function, the variable’s value is copied then passed in.

Structs

A struct (short for “structure”), is a type that stores multiple values. AS3 doesn’t have structs, but we typically mimic the behavior of structs with Value Objects (VOs). But when structs are passed, they are passed by value, not reference. When you pass a struct (such as CGRect in Objective-C), the struct is essentially copied and fed into the target method.

Pointers

Pointers are a special data type that points to a location in memory allocated from The Heap. When a variable is typed to a pointer, accessing that variable will redirect you to the value stored at the pointer’s memory address. Pointers typically point to object instances, partly because objects have state and it won’t do to pass objects by value.

More about pointers at Wikipedia here.

The Objective-C syntax to designate pointers is to add a star (*) between the type and the variable name:

UIButton *myButton = [[UIButton alloc] init];

This means var myButton is a pointer that points to a UIButton instance somewhere in memory.

Methods

Objective-C has no concept of access modifiers or namespaces. For the purpose of this writeup, I’ll only use public methods. For familiarity’s sake, I’m using the addChild method signature of the DisplayObjectContainer class in my examples. Also, this post isn’t meant to introduce any Objective-C paradigms, obviously Cocoa doesn’t do DisplayObjects and event listeners like Flash does.

Anatomy

In AS3, functions are declared in this pattern:

namespace function name(parameters):Type;
public function addChild(child:DisplayObject):DisplayObject;

In Objective-C, you have the exact same options, just moved around a bit:

-(Type)name: parameters;
-(DisplayObject *)addChild:(DisplayObject *)child;

So in comparison:

public function addChild(child:DisplayObject):DisplayObject;

-(DisplayObject *)addChild:(DisplayObject *)child;

Say you’re writing the addChild method signature of the DisplayObjectContainer class:

public function addChild(child:DisplayObject):DisplayObject;
-(DisplayObject *)add: (DisplayObject *)child

Multiple Parameters

In AS3, you want more parameters, you separate them by commas:

public function addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void

In Objective-C, you name them:

-(void)addEventListener:(NSString *)type listener:(SEL)listener useCapture:(BOOL)useCapture priority:(int)priority useWeakReference:(BOOL)useWeakReference

This is just to show 1-1 parity with AS3. Because the order and name of the parameters is what makes up the method name, you could also write this method something like this:

-(void)addEvent:(NSString *)type withListener:(SEL)callback usingCapture:(BOOL)phase withPriority:(int)priority andWeakReference:(BOOL)weakReference

This way, the method reads almost like a sentence: “add event type String, with listener SEL, using capture phase BOOL, with priority int, and weak reference BOOL.”

Static Functions

In AS3, you declare a static function with the static keyword:

public function instanceFunction():void;
public static function staticFunction():void;

In Objective-C, you put a + in front of the method declaration:

-(void)instanceFunction;
+(void)staticFunction;

Calling Methods

In AS3, if you’re calling a method, it’s straightforward like this:

mySprite.addChild(myChild);

Here’s the same thing in Objective-C:

[mySprite addChild:myChild];

And the two lines side-by-side:

mySprite.addChild(myChild);
[mySprite addChild:myChild];

Here’s calling our pretend addEventListener function from before:

//Calling our fictitious addEventListener method:
[dispatcher addEvent:@"mouseDown" withListener:^{/* do something */} usingCapture:no withPriority:0 andWeakReference:no];

Classes

In Objective-C, each class is composed of two files. One is called the header file (suffix .h), the other is the implementation file (suffix .m). This is a C convention, since C doesn’t have proper classes.

Constructors

ActionScript has one constructor, it’s a function named after the Class it’s constructing. There are language reasons for this, primarily because deep down, AS3 isn’t that different from JavaScript, and each class is really just one big closure. But that’s a topic for another time.

Objective-C has what are called “designated initializers.” A designated initializer is pretty much the same idea as a constructor. A designated initializer is just a function that returns self, the Object’s reference to itself (AS3′s equivalent of this). Since designated initializers don’t have to be named after the class, there can be many, each taking different initialization values. This is essentially constructor overloading.

So where in AS3, you’d write:

public function MyClass(required:Boolean, optional1:int = 0, optional2:int = 3)

You could write the following in Objective-C:

-(id)init; //no required options, can leave this out if you wish
-(id)init:(BOOL)required;
-(id)init:(BOOL):required withOption:(int)option1;
-(id)init:(BOOL):required withOption:(int)option1 andAnother:(int)option2;
-(id)init:(BOOL):required orJust:(int)option2;

By convention, initializers start with some variation of the word “init.”

Headers

A header file is loosely analogous to an Interface in ActionScript 3. The header file declares all the publicly available functions and getters/setters available on the object. The header also declares what our Class inherits from, and the interfaces our Class implements. For this reason, what ActionScript actually calls an Interface, Objective-C calls a Protocol.

In short, all the API is declared in header files.

Implementation

The second part of a Class is the implementation. The implementation is the actual method and property implementation of the header file for the Class.

Examples

ExampleClass.as:

package com.ptaylor.blog {
    public class ExampleClass extends Object implements IMyInterface, IOtherInterface {
        //Constructor
        public function ExampleClass() {
            //do stuff
        }
    }
}

ExampleClass.h:

#import <UIKit/UIKit.h>
@interface ExampleClass : NSObject <IMyInterface, IOtherInterface>
{
}

The @interface declaration tells Objective-C that this is a header file, followed by the header’s name, ExampleClass. The following colon (:) declares what type this Class will extend from. Protocol (AS3 Interfaces) implementation declaration happens after the superclass declaration, inside the < > block.

ExampleClass.m:

#import "ExampleClass.h"
 
@implementation ExampleClass
 
//constructor
-(id)init{
    //do stuff
    return self;
}

The @implementation declaration tells Objective-C what header this file is implementing.

That’s it. That’s all I’ve got. I’ve skimmed over and given you the fifty-thousand foot overview of the Objective-C continent. As always, post some shit in the comments if I’m wrong or you liked this or whatever.

////
// Everything after this point is basically magic. It was written during
// one coffee fueled weekend, and to be honest, I don’t remember much of
// it. That night is just a blur in my memory. Modify at your own peril.
//
// Here be dragons.
// (I’ve always felt that any serious library needs this comment at
// least once).
////

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!

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.

Advanced Text Rendering

The FTE may be low level, but that affords developers like you and me serious control over the presentation of our text fields. The FTE renders glyphs into a series of TextLines, but forces us to handle the sizing and layout of the lines. Today, I’ll cover how to efficiently create and position lines. For simplicity’s sake, I’ll assume the TextLines’ widths extend to the edges of the Container they are rendered into.

In this post I’ll cover:

• text flow across containers
• container resizing
• TextLine positioning, invalidation, and reuse

Caveats

In order to keep this post relatively short, I’ve simplified the algorithms here down to the basic principles. This is a general description of the layout algorithms in tinytlf, though they are getting more complex by the day.

Example

Here’s the final product of what I’m going to walk through. Click on the text to resize the columns:

Defining the Problem

From a layout perspective, we have a number of paragraphs that need to be rendered into a list of DisplayObjectContainers. When we run out of DisplayObjectContainers, we’re going to call it quits. What if we run out of lines before we’re done rendering containers? Good! It’s easy to quit when you don’t have any content left to render.

So what we need is a layout algorithm that will break TextLines from a Vector of TextBlocks across a list of DisplayObjectContainers (DOCs).

Text Layout

In order to coordinate the layout between paragraphs and containers, I’ve defined a controller I call TextLayout. TextLayout’s job is to run through the list of TextBlocks, rendering as many lines as possible into the available DOCs. When the DOC is full, TextLayout moves to the next container. If there is no next container, TextLayout breaks out of the rendering algorithm. Similarly with TextBlocks, if we run out paragraphs to render, TextLayout breaks out of the layout algorithm.

/**
 * Renders as many lines from the list of TextBlocks into the specified
 * conatiners as possible.
 */
public function render(blocks:Vector.<TextBlock>):void
{
	if (!containers || !containers.length || !blocks || !blocks.length)
		return;
 
	containers.forEach(function(c:TextContainer, ...args):void{
		c.preLayout();
	});
 
	var block:TextBlock = blocks[0];
	var i:int = 0;
	var container:TextContainer = containers[0];
 
	while (block && container)
	{
		container = renderBlockAcrossContainers(block, container);
		block = ++i < blocks.length ? blocks[i] : null;
	}
}

TextContainer

TextContainer is a single DOC that renders TextLines. It is a layout controller that determines the positions and sizes of the TextLines inside himself.

TextContainer maintains a very important relationship with TextLayout’s rendering algorithm. TextLayout repeatedly calls the TextContainer.layout() method, passing in a TextBlock to render lines from, and optionally, the previous line that was rendered from the block. It is TextContainer’s responsibility to render as many lines from the TextBlock into itself until either, 1. the TextBlock has no lines left to render, or 2. the TextContainer is full and has no more room for additional TextLines.

TextContainer.layout() should return the last line rendered from the TextBlock. Null is a valid value to return. If a (non-null) TextLine was returned, TextLayout assumes the TextContainer is full, finished rendering lines, and moves to the next TextContainer, keeping the same TextBlock. If TextContainer returns null, TextLayout assumes there’s still room in the TextContainer for lines, and TextLayout passes the next TextBlock to the TextContainer.

public function layout(block:TextBlock, previousLine:TextLine):TextLine
{
	_y = measuredHeight;
 
	var line:TextLine = createTextLine(block, previousLine);
 
	while(line)
	{
		addChild(line);
		lines.push(line);
 
		position(line);
 
		//If there's no room, return the last line broken.
		if(checkConstraints(line))
		{
			return line;
		}
 
		line = createTextLine(block, line);
	}
 
	//This will be null here.
	return line;
}

Line layout is straightforward. I’m sure you know what the position() and checkConstraints() methods do, and if not, the source is available here.

This is good enough to work for the first layout pass, but resizing introduces a bit more complexity.

TextLineValidity

We can take advantage of an FTE TextBlock and TextLine feature to get resizing.

When the ContentElement “model” is updated, the TextLine “views” should updated to reflect the changes. But we as FTE users have no concept of the data behind each individual TextLines, so if we updated the screen, we’d have to start from the first line and re-create each one. This is extremely inefficient, especially if the change only reflected in one actual line update.

Luckily, the TextBlock can track and resolve such changes for you. Whenever anything in the TextBlock’s content member changes, the TextBlock marks relevant lines “invalid” (TextLineValidity.INVALID). The TextBlock exposes a pretty handy property called firstInvalidLine, which points to the first line in the TextBlock that needs updating. Look mom, no searching!

You can check the status of individual lines simply by reading the TextLine.validity property. Luckily, validity is also writeable, and the TextBlock respects our decision if we choose to mark certain lines “invalid” ourselves. I guess we know best!

Resizing

When a TextContainer is resized, we need to know about it and invalidate our TextLine children.

private var explicitWidth:Number = NaN;
override public function get width():Number
{
	return explicitWidth;
}
override public function set width(value:Number):void
{
	if(value == explicitWidth) return;
	explicitWidth = value;
	invalidateLines();
}
 
private function invalidateLines():void
{
	lines.forEach(function(l:TextLine, ...args):void{
		l.validity = TextLineValidity.INVALID;
	});
}

Line Reuse

During the first layout pass, we use the TextBlock.createTextLine method exclusively. But TextLines are expensive to create, so Flash Player 10.1 introduced the TextBlock.recreateTextLine method. Allowing us to recreate TextLines means that the Flash Player can re-jigger the TextLine’s contents internally, without the overhead of creating a new TextLine instance.

During a resize operation, lines will be either created or destroyed. If you set the width smaller, the TextField will be forced to render new TextLines. If you set the width wider, the TextField can remove TextLines at the end. In the first case, we’ll have to make extra calls to TextBlock.createTextLine. In the second case, we can remove the TextLines from the display list and remove all references. In this case, the lines have been orphaned.

But with the introduction of recreateTextLine, it’s optimal to cache orphaned lines, at least for a little while. It’s possible that we will resize the TextField smaller again, which will require the creation of new lines. But if we’ve previously created lines, why not reuse them instead of creating new ones? Good thinking you.

However, this changes the meaning of the line argument in the TextContainer.layout method. Now, the line can either be:

• A valid and successfully broken TextLine, which should be used as the previousLine argument to create or re-create a TextLine.
• An invalid TextLine that needs to be re-created. This should only happen in the case that the line is the TextBlock.firstLine value, because there is no previously broken valid TextLine. Since we don’t want to wipe out our orphan cache looking for a line, we can detect this case and recreate the line.

This introduces just a bit more complexity, but luckily we can encapsulate it in the TextContainer.createTextLine method.

/**
 * Creates or recreates a given TextLine.
 */
private function createTextLine(block:TextBlock, line:TextLine):TextLine
{
	removeOrphanedLines();
 
	if(line)
	{
		if(line.validity === TextLineValidity.INVALID)
		{
			return block.recreateTextLine(line, null, width, 0.0, true);
		}
		else if(orphans.length)
		{
			var orphan:TextLine = getFirstOrphan(line);
 
			if(orphan)
			{
				return block.recreateTextLine(orphan, line, width, 0.0, true);
			}
		}
	}
 
	return block.createTextLine(line, width, 0.0, true);
}
 
private function removeOrphanedLines():void
{
	var line:TextLine;
	var n:int = lines.length;
 
	for(var i:int = 0; i < n; ++i)
	{
		line = lines[i];
 
		if(line.validity === TextLineValidity.VALID)
			continue;
 
		if(contains(line))
			removeChild(line);
 
		lines.splice(i, 1);
		orphans.push(line);
		n = lines.length;
	}
}
 
//Static so it's shared between instances of TextContainer
private static const orphans:Vector.<TextLine> = new <TextLine>[];
/**
 * Returns the first invalid orphan that also isn't the input line.
 */
private static function getFirstOrphan(exceptForMe:TextLine):TextLine
{
	if(orphans.length == 0)
		return null;
 
	var orphan:TextLine = orphans.pop();
 
	while(orphan == exceptForMe)
		orphan = orphans.pop();
 
	while(orphan && orphan.validity == TextLineValidity.VALID)
		orphan = orphans.pop();
 
	return orphan;
}

Because we can possibly recreate TextLines without calling getFirstOrphan, sometimes a TextLine in the orphan list is recreated but not removed from the list of possible orphans. The two checks in this method ensure that we don’t hit this case.

And there you have it! That’s the basic gist of TextLine rendering, resizing, and reuse across multiple DisplayObjectContainers. You can see all the source for the demo here, and be sure to check out tinytlf, the small text layout framework I’m writing. I described the basic line rendering algorithm in tinytlf (with enhancements of course). Though I’m currently working on a more iterative version. If I’m successful, it’ll be the topic of a future blog post. Cheers!

]]> http://guyinthechair.com/2010/10/the-fte-part-4-advanced-layout-techniques/feed/ 3 http://guyinthechair.com/2010/09/tinytlf-at-360flex-dc-and-360max/?utm_source=rss&utm_medium=rss&utm_campaign=tinytlf-at-360flex-dc-and-360max http://guyinthechair.com/2010/09/tinytlf-at-360flex-dc-and-360max/#comments Sun, 12 Sep 2010 03:54:57 +0000 Paul Taylor http://guyinthechair.com/?p=574

I haven’t been blogging as often these last two weeks because I’m spending a lot of time preparing for my 360|Flex and 360|MAX presentations. I’ve been developing some kickass features and demos that I have yet to discuss publicly, so if you’re in the mood to be wowed, show up to my presentations.

360|Flex DC

My presentation is the first morning, right after the keynote address (go ahead, ask me if I’m nervous about following Doug McCune?). The title is “Advanced Text Rendering with the Flash Text Engine and tinytlf.” I’ll present a general overview of the Flash Text Engine and introduce tinytlf. I’ll try and cover the low level FTE APIs as best I can in the time, but I need to move quickly into tinytlf. I only have about 70 minutes, and I hope to leave 5-10 minutes at the end for questions. I’ll be announcing tinytlf 1.0, as well as demoing some yet-to-be-announced features. It’ll be killer, I promise!

360|MAX

The title for my 360|MAX presentation is “Tinytlf and Multi-Everything.” This presentation will begin with an overview of tinytlf, but will primarily focus on the features that enable and promote multi-screen, multi-platform, and multi-touch development. Topics covered will be the performance, interactivity, and configurability for different platforms. If you’re interested in a multi-platform text controls, this will be presentation to see.

These two conferences are the places to be for developers or companies who have invested in the Flash Platform. You’ve done your due diligence by choosing Flash, now keep up with the platform ’cause the times, they are a-changin’. Register for 360|Flex here, and for Adobe MAX here.

I’m very excited to present tinytlf to the world. If you see me at either event, hit me up! I’m more than happy to answer questions, etc. See you there!

]]> http://guyinthechair.com/2010/09/tinytlf-at-360flex-dc-and-360max/feed/ 2