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.