Seriously You Can Do Cool Things: Getting Advanced with the Text Layout Framework

SERIOUSLY, YOU CAN DO
COOL THINGS:
Getting Advanced with the Text Layout Framework
by Huyen Tue Dao

ABOUT ME
• Name ≈ “Hwin Tweh Dow”

• Computer/Electrical Engineering @
University of Maryland

• Flex developer since 2006; also worked in
C/C++, Java, Perl, .NET

• numTimesSpeaking = 5

• Favorite race in SC is the Zerg: open with
10 pool speedling

• About to start 3rd play-through of ME2
in anticipation of ME3
“I’m Commander Shepard and this is my favorite store on the Citadel.”

WHAT ARE WE GOING TO
TALK ABOUT?
• Overview of Text Layout Framework and Flash Text Engine
• Using the Text Layout Framework in Manual
• Extending the Text Layout Framework
• Leveraging the Flash Text Engine
• Combining with other Flex components
• Conclusion/questions

Stage

TextLine
TextBlock
TextLine

createTextLine()
TextLine
TextElement

string content ElementFormat

Rendering Text With FTE
Artist (not so much) rendering

My Title
Here’s some text.

Here’s some other text.

Here’s some more text. And
here’s the last bit of text.

TextFlow

p p p p

span span span span span
“My Title” “Here’s some text.” “Here’s some other text.” “Here’s some more text. “ “And here’s the last bit of text.”

TLF’s TextFlow

interactionManager:ISelectionManager

changes to TextFlow passing input and user events

Stage

Container
TextFlow
TextLine

TextLine
ﬂowComposer:IFlowComposer ContainerController
Container
ContainerController

TextLine

TLF’S MVC

OVERVIEW OF TLF AND FTE
• TLF utilizes FTE for advanced text rendering
• Adds in MVC framework, automated/advanced layout,
selection/editing
• FTE = bricklayer, contractor; TLF = architect

USING THE TLF IN MANUAL
• “Manual?”
• Set up text ﬂow, containers, controllers, and interaction
manager by hand
• add/remove/setup containers
• set composition bounds
• setup selection/read/write ability, setup undo/redo

• “Automatic”: family of Spark components utilize TLF
• Base TLF Spark components: RichText, RichEditableText
• Other components build on these: TextInput, Text Area
• Most of TLF functionality encapsulated within components
• Can access parts of TLF (listen for events) but manipulating is
difﬁcult, not great idea.

• “Semi-automatic”
• TextContainerManager, class that handles a single-container TLF
setup
• Provide it container, text/TextFlow, composition bounds,
formatting options, editing mode
• “Consider using TextContainerManager for better performance
in cases where there is a one container per TextFlow, and the
TextFlow is not the main focus, is static text, or is infrequently
selected.”

• Basic classes involved
• TextFlow and classes for importing/exporting a TextFlow:
• TextConverter: static class providing import/export methods
for different formats, types
• Also have TextFlowUtil (simpliﬁed export/import),
PlainTextExporter (provides some customization options)
• Conﬁguration: specify initial formatting options for TextFlow
creation, including selection formats, link formats, scrolling
options, ENTER/TAB key behavior

• IFlowComposer: currently only StandardFlowComposer
implementation and TextFlow automatically initializes one
• Composes layout and updates display
• Adds/removes containers (by adding/removing controllers)
• Normalizes the TextFlow after changes are made
• Provides information about and access to composite
TextFlowLines, wrappers for generated TextLines

Container layout in TextFlowLines Stage
Container
TextFlowLine 0 line height
text height ascent TextLine 0
descent

TextFlowLine 1
TextLine 1

TextFlowLine 2
TextLine 2

…

TextFlowLines + TextLines

• ContainerController: connects TextFlow and a container, tracks
width and height of text area in that container, places TextLines
in container, manages scrolling
• Contains reference to TextFlow to which it belongs
• ISelectionManager: handles selection and TextFlow events
• Includes methods that provide information about selection
including formatting properties of the selection
• IEditManager: extends ISelectionManager adds edit functionality
including undo/redo, cut/copy/paste, keyboard shortcuts

• Basic setup:
• Import/create TextFlow
• Create one or more containers (Sprites)
• Create a ContainerController with each container and call
TextFlow.ﬂowComposer.addController
• (Optional) Setup TextFlow.interactionManager
• Call TextFlow.ﬂowComposer.updateAllControllers/
updateToController

• So what can we do in “manual?”
• Play with containers:
• Use multiple, linked containers: easy, just add new
ContainerController via IFlowComposer.addController
• Remove containers: easy, IFlowComposer.removeController/
removeControllerAt/removeAllControllers
• Take it further: what if we wanted to use just enough containers
to ﬁt text? Like how a word processor paginates content…

• States of a text container in TLF:
• Damaged: when model or layout changes, IFlowComposer
marks relevant lines as “damaged” and needing of
recomposition
• Composition:TextFlowLines/TextLines created and assigned to
container based on current position, dimensions of container;
• IFlowComposer.composing: indicates currently composing
• Display: Old TextLines cleaned up, new TextLines positioned

• Useful/Import TextFlow events:
• DamageEvent.DAMAGE: dispatched whenever changes are
made to the model or to the layout
• CompositionCompleteEvent.COMPOSITION_COMPLETE:
dispatched whenever composition ﬁnishes
• UpdateCompleteEvent.UPDATE_COMPLETE: dispatched
whenever text is ready to display but has not been painted to
screen yet.

• Implementing pagination in TLF: check if the last container added
renders the end of the text:
• ContainerController.verticalScrollPolicy = ScrollPolicy.OFF
• ContainerController.absoluteStart: character position in
TextFlow at which text in container starts
• ContainerController.textLength: total number of characters
displayed in container including whitespace
• TextFlow.textLength: total number of characters in TextFlow
(ContainerController.absoluteStart + ContainerController.textLength) == TextFlow.textLength

• When do we perform this check?
• Need to wait for the last page added to compose and display
completely so check is accurate
• Add handler for UpdateCompleteEvent and perform check
and if needed add/remove a page and then update again
• Will repeat until have enough pages

• Playing with containers: Useful TLF stuff
• addController/removeController
• DamageEvent, CompositionCompleteEvent,
UpdateCompleteEvent
• ContainerController.absoluteStart,
ContainerController.textLength,
ContainerController.verticalScrollPolicy

EXTENDING THE TLF
• Extending the Text Layout Framework
• Can be difﬁcult: some classes are marked ﬁnal (that you wish
were not), many useful methods are private, some are just
complicated
• Likely candidates: FlowOperations, SelectionManager,
EditManager, UndoManager, ContainerController
• Let’s talk about operations…

EXTENDING THE TLF
• FlowOperations: family of objects utilized by IEditManager to
encapsulate changes to TextFlow and provide undo/redo
• If you need undo, you need operations:
• TextFlow.generation: incremented every time it changes
• IEditManager uses generation to track changes and to validate
undos/redos
• Operations are not necessary if do not care about undo, but
making changes through IEditManager also provides some
support for auto-managing selection state with changes

EXTENDING THE TLF
• Creating your own operations:
• FlowTextOperation: subclass of for transforming text
• Create subclass, override doOperation, undo(), redo()
• doOperation():Boolean does the actual work of changing
TextFlow
• Return value indicates whether the operation completed
correctly; if not, return false and IEditManager rolls back
generation

EXTENDING THE TLF
• undo():SelectionState, contains logic for reversing changes,
return value is the selection state desired after undo
• redo():SelectionState, redoes operation, returns SelectionState
originally passed to doOperation; don’t have to implement
• How do you actually call your operation?
• IEditManager.doOperation: does bookkeeping and calls
FlowTextOperation.doOperation
• Extend EditManager and add interface for calling your
operation

EXTENDING THE TLF
• Things to keep in mind
• You can use other operations within your operation
• Take advantage of existing classes
• Makes undo easy to implement (but remember to undo
operations in reverse order)
• Alternatively, can use
IEditManager.beginCompositeOperation/
endCompositeOperation to group operations on the ﬂy

EXTENDING THE TLF
• Stay away from using FlowElement references in your
operation
• When using copy/cut/paste or TextFlow normalizes,
FlowElements are often replaced or removed
• If you need to reference a particular element; use
FlowElement.id and textFlow.getElementById instead
• Make sure you consider any changes to selection state that
your operation induces and set it in doOperation if necessary
• use namespace tlf_internal: many helpful methods are tucked
away in there

LEVERAGING THE FTE
• Understanding underlying FTE parts of TLF can help you:
• Decorate/enhance TLF-rendered text without changing the
model or the layout
• Get more speciﬁc information about layout of text lines within
a container and the TextFlow as a whole
• TextFlowLine: TLF wrapper for TextLines that actually reside on
stage; both provide useful information
• StandardFlowComposer -> TextFlowLine -> TextLine

LEVERAGING THE FTE
• StandardFlowComposer: methods for grabbing TextFlowLines
• findLineAtPosition/findLineIndexAtPosition: gets reference to/
index of TextFlowLine that contains the text at a given position
• ContainerController: couple of tlf_internal methods for getting
specific TextFlowLines
• tlf_internal getFirstVisibleLine():TextFlowLine
• tlf_internal getLastVisibleLine():TextFlowLine
• TextFlowLine.getLine():TextLine

LEVERAGING THE FTE
• TextLine: methods for getting position, index information for
individual characters
• getAtomBounds: get bounds relative to TextLine of a particular
atom (character)
• getAtomIndexAtPoint: get index of atom at given point (relative
to the stage)
• So how can we use all this?
• Draw on top of the TextLine
• Pinpoint a position relative to the stage or another component
from a text position

COMBINING WITH OTHER
FLEX COMPONENTS
• Ideally, we would love to be to create custom FlowElements that
provide new functionality and integrate nicely with TLF but not
always possible or time efficient so what else can we do?
• http://platustalksflex.blogspot.com/2010/07/position-
uicomponents-inside-textflow.html
• Basically, use an InlineGraphicElement as a placeholder, and then
position another component on top of it.

FLEX COMPONENTS
• Need to assign id to differentiate our placeholder
InlineGraphicElements from others
• Keep a mapping of these id’s to the Flex components
• Update all of these components on UpdateCompleteEvent
• Can even utilize this with TLF selection/editing (takes some
work though)

FLEX COMPONENTS
• Can even import/export these components
• Use XML: export as whatever tag required, make sure
assign “id” attribute
• To import: replace XML placeholder tags with <img> tags
• Have to take care of cut/copy/paste: end up with
placeholders with identical id’s:
• Have to extend EditManager and override pasteTextScrap
• Go through TextScrap and replace duplicate id’s with new
ones.

CONCLUSION
• Before even getting into TLF, make sure it’s the right solution.
• Most ﬂexible, powerful way to user TLF is in “manual,” setting up
everything yourself
• Extend TLF classes to add new functionality and encapsulate it
• Go lower-level by accessing and manipulating underlying FTE to
play with interaction and rendering without changing TLF parts
• Integrate Flex UIComponents with TextFlow layout by using
placeholders and custom operations.
• It takes some work (and a bit of code), but seriously, you can do
cool things.

CREDIT WHERE CREDIT IS
DUE
• Drawing highlights on TextLines technique from the
HighlightAdornment example included in “Using TLF with
Flash CS4 examples” for TLF 1.0 Beta: http://
opensource.adobe.com/wiki/display/tlf/Text+Layout
+Framework
• “InlineUIComponents within a TextFlow”: http://
platustalksﬂex.blogspot.com/2010/07/position-uicomponents-
inside-textﬂow.html

QUESTIONS?

Thanks for coming!

Huyen Tue Dao
daotueh@gmail.com
queencodemonkey@twitter.com
www.queencodemonkey.com

Seriously You Can Do Cool Things: Getting Advanced with the Text Layout Framework

More Related Content

What's hot (6)

Recently uploaded (20)

Seriously You Can Do Cool Things: Getting Advanced with the Text Layout Framework

Editor's Notes