TLF API Changes in Build 370

Flex Gumbo beginning with revision 4946 now contains TLF Build 370. This build contains many API changes and enhancements. This blog entry is the first of several detailing the changes.

Note that all these changes are tentative pending further review.

The changes described in this entry are:

  • Merging of Format Classes
  • Changes to Styling
  • Class FlowElement’s TExtLayoutFormat APIs
  • User Styles
  • Non-Inhering Styles
  • FlowElement id and styleName properties
  • API Changes

Merging of Format Classes

To be more CSS-like and to support a richer styling model the CharacterFormat, ParagraphFormat and containerFormat are merged into a single TextLayoutFormat class that holds TLF styles. TLF continues to support user defined styles through setStyle/getStyle API ITextLayoutFormat is a merged readonly interface for accessing values of TLF styles replacing the I*Format interfaces.

Style Changes

The way individual style properties are handled has changed.

  • TLF styles are now untyped – of type *
  • undefined is used to indicate that a style is not set.
  • some styles are now non-inheriting. If undefined their computed value is not from a parent element but is the default value.
  • all TLF styles now support “inherit” as a value. This causes any style including non-inheriting styles to get the parent value.

Non-Inheriting Styles

Several TLF styles no longer inherit. Instead if they are undefined the computedTextLayoutFormat will have the default value. These styles are:

  • marginLeft, marginRight, marginTop, marginBottom
  • paddingLeft, paddingRight, paddingTop, paddingBottom
  • verticalAlign
  • columnCount, columnWidth, columnGap
  • lineBreak
  • backgroundColor, backgroundAlpha (new styles)

FlowElement TextLayoutFormat APIs

A setter function for every TLF style (fontStyle, textAlign, columnCount etc.)A textLayoutFormat property of type ITextLayoutFormat that if non-null returns the value of a format. For example:

var flowElement:FlowElement
var textAlign:* = flowElement.textLayoutFormat ? flowElement.textLayoutFormat.textAlign : undefined;

will return the value of textAlign set on an individual FlowElementA computedTextLayoutFormat propert of type ITextLayoutFormat that returns the cascaded value of a property. This includes settings made in the IFormatResolver. This value is never undefined. It is always type checked. For example:

var flowElement:FlowElement
var textAlign:String = flowElement.computedTextLayoutFormat.textAlign

Note that the computedTextLayoutFormat is the result of the cascade. It shows what the value of a property is at any element. Its not necessarily the resulting value that is actually applied. For example the padding actually applied to a container is the computed padding of the TextFlow plus the computed padding of the Container. Additional padding may be added by elements inside the container.

User Styles

FlowElements and DisplayObjectContainerController continue to support user styles. There are three main APIs

  • setStyle – sets a style on the element
  • getStyle – returns the computed style on the elements
  • userStyles property is an Object whose keys are the names of the user styles and values are the user style values. This property is read/write. On read it returns a copy.

id and styleName properties

All FlowElements now implement the “id” and “styleName” property.

API Changes

IFormatResolver

  • remove resolveCharacterFormat, resolveContainerFormat and resolveParagraphFormat
  • add resolveTextLayoutFormat

Note: further information on how to use this API is forthcoming.

IContainerController

  • containerFormat renamed to textLayoutFormat
  • computedContainerFormat renamed to computedTextLayoutFormat
  • coreStyles property – object containing all of the TLF styles set on an element

ContainerControllerBase

  • containerFormat renamed to textLayoutFormat
  • computedContainerFormat renamed to computedTextLayoutFormat

DisplayObjectContainerController

  • added containerControllerInitialFormat property. This format is set on every newly constructed DisplayObjectContainerController. Default is all props undefined except columnCount, columnGap, columnWidth and verticalAlign which are set to “inherit”. WARNING: This is temporary. I’d like to make this initial format empty.
  • added userStyles property
  • added textLayoutFormat and computedTextLayoutFormat properties
  • coreStyles property – object containing all of the TLF styles set on an element

ISelectionManager

  • getCommonCharacterFormat returns a ITextLayoutFormat
  • getCommonParagraphFormat returns a ITextLayoutFormat
  • getCommonContainerFormat returns a ITextLayoutFormat

note: these three methods continue to exist. They return the common formats for all the leaf elements, the paragraph elements and the containers in a selected range.

IEditManager, EditManager

  • applyFormat still takes three formats. These are the formats applied at the leaf, paragraph and container level
  • applyCharacterFormat renamed to applyLeafFormat. Supplied format is applied to the leaf elements.
  • applyParagraphFormat – parameter is now TextLayoutFormat
  • applContainerFormat – parameter is now TextLayoutFormat
  • applyFormatToElement now takes a single TextLayoutFormat

SelectionState

  • constructor third parameter now ITextLayoutFormat
  • pointFormat property now returns ITextLayoutFormat

ElementRange

  • containerFormat, paragraphFormat, characterFormat now return ITextLayoutFormat

Configuration and IConfiguration

  • link defaults now linkNormalFormatDefault, linkHoverFormatDefault, linkActiveFormatDefault of type ITextLayoutFormat
  • textFlowInitialFormat of type ITextLayoutFormat
  • textFlowInitialFormat now defaults to having the following properties set to “inherit”. lineBreak, paddingLeft, paddingRight, paddingTop, paddingBottom and verticalAlign. WARNING: this is temporary and will be changed to an null format in the future. This only affects users of the hostTextLayoutFormat API.

FlowElement

  • setters for all TLF styles
  • userStyles property – object containing all of the user styles set on an element
  • equalUserStyles function – tells if two elements have equal user styles.(make internal?)
  • textLayoutFormat – ITextLayoutFormat interface with TLF styles set on an element
  • computedTextLayoutFormat – ITextLayoutFormat interface with computed TLF styles for an element
  • setStyle and getStyle API
  • coreStyles property – object containing all of the TLF styles set on an element

ParagraphElement

  • remove computedParagraphFormat

TextLineFactory

  • createTextLineFromString takes three formats as before. These are the formats applied to the text, the paragraph and the TextFlow.
  • a TextLineFactory can now be constructed. It has settable formats and text property. The idea is to format it once and then change the text for improved performance.

ColumnState

  • createColumnState – second parameter changed from containerFormat to IContainerController..

FormatValue

  • add INHERIT.

ApplyFormatOperation

  • constructor now takes three ITextLayoutFormats
  • characterFormat renamed leafFormat, returns ITextLayoutFormat
  • paragraphFormat, containerFormat return ITextLayoutFormat

ApplyFormatToElementOperation

  • constructor now takes a single ITextLayoutFormat

InsertTextOperation

  • characterFormat property still exists returns ITextLayoutFormat

SplitParagraphOperation

  • characterFormat property still exists returns ITextLayoutFormat

Markup Changes

TextLayoutFormat markup now supports user styles. A user style is any attribute that isn’t a TLF core format. For example the following markup will import:

<TextFlow myStyle=”myValue”><p><span>text</span></p></TextFlow>

In code the user can see the value of myStyle with the getStyle API.New styles can be added with setStyle. For example if after importing the above a new setStyle call is made:

textFlow.setStyle(“myOtherStyle”,”myOtherValue”)

the result will export:

<TextFlow myStyle=”myValue” myOtherStyle=”myOtherValue”><p><span>text</span></p></TextFlow>

There is a single TextLayoutFormat object that can be imported. These can be named children of the TextFlow and referenced by any TLF element using “{}” notation. For example:

<TextFlow><TextLayoutFormat id=”bold” fontWeight=”bold”/><p><span textLayoutFormat=”{bold}”>heavy text</span></p></TextFlow>

There are three new elements for link formats. These link formats can be directly specified on any element and inherited. For example

<TextFlow><linkActiveFormat color=”0xff000″/><linkNormalFormat color=”0xff00″/><linkHoverFormat color=”0xff”/><p><a href=”http://www.adobe.com”>ClickMe</a></p></TextFlow>

sets these properties on the TextFlow and they are then inherited by the &lta> element. These properties could be children of any FlowElement including the &ltp> and the &lta> in the above example. Observe that these new elements also support userStyles.

12 Responses to TLF API Changes in Build 370

  1. Michael Jordan says:

    Is there any timeline or plan for adding keyboard support and read/tabIndex order for LinkElements?A user should be able to focus on a LinkElement which should render with the linkHoverFormat and the FlashPlayer should display the yellow focus rectangle if stageFocusRect == true. The user should be able to activate the link by pressing the Space bar or Enter key or by some other means for users of mobile devices.The flashx.textLayout.acc.TextAccImpl class should be updated so that links are revealed in the MSAA object hierarchy as links and so that a link can be progammatically activated by assistive or mobile device technology.

  2. Richard Dermer says:

    Could you post this to the forum so QE could pick it up?Some of this is possible by subclassing DisplayObjectContainer and overriding the process*Event functions to do custom keyboard handling.Are you doing work that requires accessibility? I’d be interested in finding out more about your accessibility requirements.Thanks,Richard

  3. Brent Arndorfer says:

    Any chance you could get them to update the Gumbo language reference to reflect the changes? Current docs at http://livedocs.adobe.com/flex/gumbo/langref/ do not yet reflect any new changes. It would be a huge help! Otherwise, can we get ASDoc’s from another location?Thanks!

  4. Brian Thomas says:

    Hi Brent,In order to get ASDocs for a recent build of TLF, unfortunately you’ll have to download the Gumbo SDK and build the docs yourself. There is an included ant script that will do it for you. This is a limitation we’ve been talking about, and hopefully we’ll have a better solution for you soon.

  5. Brent Arndorfer says:

    Brian–I’ve tried this as suggested in the forums, but have not had any luck. I tried running a few different ANT targets related to generating docs, but they always only include the frameworks classes. Has anyone tested this lately, or could you provide any additional information about what target(s) to run in which build file?Thanks!

  6. Brian Thomas says:

    Brent,You’re right, turns out you can’t actually build the latest TLF documentation from the Gumbo builds. My apologies for the confusion! We’re working on directly providing a place to publicly provide our latest API docs. Till then, the Gumbo livedocs are up to date as of TLF build 370.http://livedocs.adobe.com/flex/gumbo/langref/

  7. Brent Arndorfer says:

    Thanks, Brian. This is a HUGE help!

  8. Brett says:

    Hi thanks for the awesome info. I have been using the TLF on a project I am doing in flash cs4. The next step for me is formatting text. The changes to how formatting works in the TLF seem powerful. Would someone mind showing me an example of how to apply a style(bold) to user selected text. User would select text then click the bold button. Help with this would be appreciated 🙂 I’m working directly in flash on this one… thanks

  9. Jo says:

    Dear Richard,thank you so much for taking care of custom attributes. We are for days and nights without end now trying to figure out a way, of how to add customer entered criteria to text selections. E.g. while changing color of a text range, noting what color the user originally entered – mostly cmyk.I cannot really get how to add a custom style to a range just in changing through e.g. the sample functions changeFontSize and like wise.IEditManager(_textFlow.interactionManager).textFlow.setStyle(“custom_color”,”0,0,20,10″);It works, but it sets the textflow attribute on global level, not only on selected and currently changed range.If you have any suggestion, I would be extremely greateful.

  10. judah says:

    Can you not enter linebreaks? When I do I get this error message:ArgumentError: NewElement not of a type that this can be parent ofat flashx.textLayout.elements::FlowGroupElement/replaceChildren()[C:\Vellum\branches\v1\1.0\dev\output\openSource\textLayout\src\flashx\textLayout\elements\FlowGroupElement.as:772]at flashx.textLayout.elements::FlowGroupElement/set mxmlChildren()[C:\Vellum\branches\v1\1.0\dev\output\openSource\textLayout\src\flashx\textLayout\elements\FlowGroupElement.as:184]It looks like the element that it is choking on is “\n\t\t\t\t”<s:RichEditableText x=”93″ y=”22″ editable=”false”><s:TextFlow blockProgression=”tb” columnCount=”inherit” columnGap=”inherit” columnWidth=”inherit” locale=”en_US” paddingBottom=”inherit” paddingLeft=”inherit” paddingRight=”inherit” paddingTop=”inherit” verticalAlign=”inherit” whiteSpaceCollapse=”collapse” xmlns=”http://ns.adobe.com/textLayout/2008″><s:p direction=”ltr” paragraphEndIndent=”0″ paragraphSpaceAfter=”0″ paragraphSpaceBefore=”0″ paragraphStartIndent=”0″ textAlign=”start” textAlignLast=”start” textIndent=”0″ textJustify=”interWord”><s:a color=”#ae7c4b” fontFamily=”Myriad Pro” fontSize=”17″ fontStyle=”normal” fontWeight=”normal” kerning=”auto” lineHeight=”120%” textAlpha=”1″ textRotation=”auto” trackingRight=”2%” click=”linkelement1_clickHandler(event)” textDecoration=”none”>{data.label}</s:a><s:span color=”#cccccc” fontFamily=”Myriad Pro” fontSize=”17″ fontStyle=”normal” fontWeight=”normal” kerning=”auto” lineHeight=”120%” textAlpha=”1″ textRotation=”auto” trackingRight=”2%”> has posted</s:span><s:span color=”#ae7c4b” fontFamily=”Myriad Pro” fontSize=”17″ fontStyle=”normal” fontWeight=”normal” kerning=”auto” lineHeight=”120%” textAlpha=”1″ textRotation=”auto” trackingRight=”2%”> </s:span><s:span color=”#0099ff” fontFamily=”Myriad Pro” fontSize=”17″ fontStyle=”normal” fontWeight=”normal” kerning=”auto” lineHeight=”120%” textAlpha=”1″ textRotation=”auto” trackingRight=”2%”>2 photos on Design Team</s:span></s:p></s:TextFlow></s:RichEditableText>

  11. judah says:

    In the previous code sample wrapping the TextFlow with a textFlow tag fixed the issue.