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

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

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

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 difﬁcult, not great idea.

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

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

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

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

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

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.ﬂowComposer.addController • (Optional) Setup TextFlow.interactionManager • Call TextFlow.ﬂowComposer.updateAllControllers/ updateToController

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 ﬁt text? Like how a word processor paginates content…

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

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 ﬁnishes • UpdateCompleteEvent.UPDATE_COMPLETE: dispatched whenever text is ready to display but has not been painted to screen yet.

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 

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

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

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)

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.

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

by Huyen Tue Dao

Accessibility

Categories

Upload Details

Usage Rights

1 Embed 1

Statistics

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