360|Flex 2011 presentation by Huyen Tue Dao.

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

2. 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.”

3. 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

4. Stage
TextLine
TextBlock
TextLine
createTextLine()
TextLine
TextElement
string content ElementFormat
Rendering Text With FTE
Artist (not so much) rendering

5. 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
Artist (not so much) rendering

6. interactionManager:ISelectionManager
changes to TextFlow passing input and user events
Stage
Container
TextFlow
TextLine
TextLine
flowComposer:IFlowComposer ContainerController
Container
ContainerController
TextLine
TLF’S MVC
Artist (not so much) rendering

7. 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

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

9. USING THE TLF IN MANUAL
• “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
difficult, not great idea.

10. USING THE TLF IN MANUAL
• “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.”

11. USING THE TLF IN MANUAL
• 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 (simplified export/import),
PlainTextExporter (provides some customization options)
• Configuration: specify initial formatting options for TextFlow
creation, including selection formats, link formats, scrolling
options, ENTER/TAB key behavior

12. USING THE TLF IN MANUAL
• 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

13. 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
Artist (not so much) rendering

14. USING THE TLF IN MANUAL
• 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

15. USING THE TLF IN MANUAL
• Basic setup:
• Import/create TextFlow
• Create one or more containers (Sprites)
• Create a ContainerController with each container and call
TextFlow.flowComposer.addController
• (Optional) Setup TextFlow.interactionManager
• Call TextFlow.flowComposer.updateAllControllers/
updateToController

16. USING THE TLF IN MANUAL
• Basic setup:
• Import/create TextFlow
• Create one or more containers (Sprites)
• Create a ContainerController with each container and call
TextFlow.flowComposer.addController
• (Optional) Setup TextFlow.interactionManager
• Call TextFlow.flowComposer.updateAllControllers/
updateToController

17. USING THE TLF IN MANUAL
• 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 fit text? Like how a word processor paginates content…

18. USING THE TLF IN MANUAL
• 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

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

20. USING THE TLF IN MANUAL
• 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

21. USING THE TLF IN MANUAL
• 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

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

23. EXTENDING THE TLF
• Extending the Text Layout Framework
• Can be difficult: some classes are marked final (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…

24. 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

25. 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

26. 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

27. 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 fly

28. 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

29. 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 specific 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

30. 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

31. 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

32. 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.

33. COMBINING WITH OTHER
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)

34. COMBINING WITH OTHER
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.

35. CONCLUSION
• Before even getting into TLF, make sure it’s the right solution.
• Most flexible, 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.

36. 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://
platustalksflex.blogspot.com/2010/07/position-uicomponents-
inside-textflow.html

37. QUESTIONS?
Thanks for coming!
Huyen Tue Dao
daotueh@gmail.com
queencodemonkey@twitter.com
www.queencodemonkey.com