Author Archive: Richard Dermer

TLF 2.0 Changes: SubParagraphGroupElements and typeName applied to TextFieldHTMLImporter and CSSFormatResolver

Changes made to the TLF 2.0 are being used to improve theTextFieldHTML importer. First note that this importer is intended for compatibility with the TextField.htmlText property. It’s not intended to be a general purpose HTML importer.

The SubParagraphGroupElement

In TLF 1.1 and earlier There was no equivalent of HTML’s nested spans. TLF 2.0 adds the SubPargraphGroupElement (in markup <g>). SubParagraphGroupElements can be a child of a ParagraphElement, LinkElement, TCYElement or another SubParagraphGroupElement. These are useful for creating nested text elements that share some formatting.

The FlowElement typeName property

All TLF elements now have a typeName property. This property is initialized to the string used when exporting TLF markup. This table shows the default class names and default typeNames for new instances of that class. Note that typeName is a read/write property and clients may manipulate it.

DivElement div
InlineGraphicElement img
LinkElement a
ListElement list
ListItemElement li
ParagraphElement p
SpanElement span
SubParagraphGroupElement g
TabElement tab
TextFlow TextFlow

Note that TLF always converts TabElement and BreakElement elements into the tab and newline character so normally they disappear from the TextFlow and are left off this table.

HTMLImporter Changes to Support Unknown Tags

The HTML importer now preserves unrecognized element tags, for example <foo>Text</foo>, by creating a TLF element and setting its typeName to be an element of that tag. The goal of this is to allow importing of HTML with custom tags and connecting a stylesheet with typename selectors that match through an IFormatResolver. When the importer encounters an unknown tag the rule it uses is if the unknown tag has one child element that child gets its typeName set to the unknown tag. If two or more elements are created than a <div> or a <g> as the parent of the children with its typeName set.

For example :

Import this HTML:
<foo>Text<foo>
to create TLFMarkup:
<p typeName=”foo”><span>Text</span></p>

Import this HTML:
<foo><p>Hello</p>World</foo>
to create TLFMarkup:
<div typeName=”foo”><p><span>Hello</span></p><p><span>World</span></p></div>

Import this HTML:
<p><foo><b>bold</b>normal</foo></p>
to create TLFMarkup::
<p><g typeName=”foo”><span fontWeight=”bold”>bold</span><span>normal</span></g></p>

Import this HTML:
<p><foo>asdf</foo></p>
to create TLFMarkup::
<p><span typeName=”foo”>asdf</span></p>

Warning: TLF’s HTMLExporter converts all tag names to uppercase. So typeName=”foo” exports to <FOO>. The TLF markup exporter preserves case as shown above.

SubPargraphGroupElement and the HTML Importer

Previously the importer was unable to preserve nested span elements with formatting. For example:
<font size=”18″><span>Normal <font color=”#0000ff”>BLUE</font> Normal</span></font>

In 1.0 this content created 3 spans with different formatting like this:
<p><span fontSize=”18″>Normal </span><span color=”#0000ff” fontSize=”18″>BLUE</span><span fontSize=”18″> Normal</span></p>

In 2.0 this content creates a group with three span elements:
<p><g fontSize=”18″ typeName=”span”><span>Normal </span><span color=”#0000ff”>BLUE</span><span> Normal</span></g></p>

This example becomes even more interesting if the <span> is changed to a <foo> and CSS formatting is connected.

typeName and CSSFormatResolver

This can all be used to improve the connection of CSS stylesheets to a TextFlow using the IFormatResolver interface. This was originally described in an older blog post.

I’ve updated the Flex based CSSFormatResolver example to leverage the typeName property as well as including a demonstration of a styled “foo” tag. It’s attached here. Note: You will have to adjust the library paths.

For those requesting a non-Flex version of CSSFormatResolver I attached a sample here. Note: You will have to adjust the library paths.

TLF FlowElement LinkElement Events and EventMirrors

Examples are posted here:

LinkElements

TLF includes support for LinkElements. A LinkElement similar to an html <a> element can have a URL and respond to hover events and click events. The URL is invoked on click. The rendering of the LinkElement will change if a linkHoverFormat or linkActiveFormat is specified. This markup will turn the link red on hover and green on click:

<TextFlow version="2.0.0" xmlns="http://ns.adobe.com/textLayout/2008">
<p><a href="http://www.google.com">
<linkActiveFormat><TextLayoutFormat color="0xff00"/></linkActiveFormat>
<linkHoverFormat><TextLayoutFormat color="0xff0000"/></linkHoverFormat>
TestLink</a></p>
</TextFlow>

LinkElements and event: syntax

LinkElements can also be used to generate events on the click that a client can intercept. This is done by specifying the LinkElement.href property as "event:eventName". Client code can then attach a listener to the textFlow for eventName.

In the examples zip LinkEventExample.as demonstrates changing the color of the text when a link is clicked.

Note that if an EditManager is attached to the textFlow then LinkElements only respond if the CTRL key (on windows) or Command key (on Mac) is pressed.

EventMirrors

Several TLF elements also support event mirrors. This allows a client to attach listeners directly to FlowElements for various events defined in the FlowElementMouseEvent class. These events events are generated by TLF by observing the MouseEvents that occur over the TextLines and mapped to the FlowElements. The events that can be listened for are defined in FlowElementMouseEvent. These events are: MOUSE_DOWN, MOUSE_UP, ROLL_OVER, ROLL_OUT and CLICK. Listeners are attached by calling getEventMirror on a FlowElement with support. getEventMirror returns an IEventDispatcher on which the listener can be attached. Only the following FlowElements support getEventMirror: LinkElement, TCYElement, SubParagraphGroupElement, SpanElement and InlineGraphicElement.

In the examples zip EventMirrorExample.as file demonstrates the use of event mirrors.

Note that getEventMirror is a tlf_internal function. Event mirror support is still experimental in TLF 2.0 though there are no known bugs with dispatching events. Less well tested is how event mirrors withstand editing operations as well as cut, copy and paste. Copy, for example will not have event mirrors on the new copy. Splitting a FlowElement will only preserve the mirrors on one of the elements. Unlike the event: syntax on LinkElements event mirrors are not imported and exported in XML.

For various reasons TLF does not use FTE eventMirrors. The main one is that an eventual goal of TLF is to permit data binding to a TextFlow so that a single TextFlow can be displayed in multiple views. This event mirror architecture is a necessary step in that direction.

Padding Changes in TLF 2.0

TLF has 4 padding properties: paddingLeft, paddingRight, paddingTop and paddingBottom. In TLF 1.0 the padding properties only applied to TextFlow and ContainerController objects. The effective padding on each side of each container is the sum of the two paddings.

TLF 2.0 adds additional support for padding on DivElements, ParagraphElements, InlineGraphicElements as well as the new list related elements ListElement and ListItemElement. Each element will have a padding specified inset around it.

During import of TLF markup padding properties are ignored on these additional classes unless the attribute version="2.0.0" is specified on the TextFlow tag. The goal is that existing markup won’t render differently if padding properties were specified on elements that didn’t implement padding in 1.0.

The padding properties don’t inherit by default. If not specified they have their default value. In 1.0 and 1.1 the default value was "0". In TLF 2.0 this default value is "auto". For all elements except ListElement "auto" is interpreted as "0".

For ListElements "auto" is "0" except on the start side of the list where the value of the new listAutoPadding property is used. The default value of listAutoPadding is 40. This was done to give lists a default indent.

The following markup creates a list with the marker placed outside the box of the ListItem.

<TextFlow><list><li>First list item</li></list></TextFlow>

Without listAutoPadding the list item would have no padding and the marker would be to the left of the clip and would not be visible. TLF 2.0 applies the listAutoPadding to the start side and indents the list 40 pixels and places the outside marker in the visible area to the left side of the indentation.

TLF 1.1 and 2.0 TextLayoutEditor Demo Source

Quick updates on links to the TextLayoutEditor demo source.

TLF 1.1 was included in Flex 4.1.  The complete source for the TextLayoutEditor is posted here: http://blogs.adobe.com/tlf/files/2010/11/textLayoutBuild604.zip

TLF 2.0 is in development and will be part of Flex 4.5.  The TLF sourceforge site is being updated with changes on a regular basis.

Not quite as frequently a single zip containing all TLF sources and the TextLayoutEditor demo source is posted here: http://sourceforge.net/projects/tlf.adobe/files/current/textLayout_build.zip/download

During development we are trying to minimize changes to the API – that said there are changes in 1.1 and 2.0 and updates to the TextLayoutEditor demo are made as needed.  Check the ReleaseNotes.txt file for more information on specific changes.

TLF At Max 2010

Two members of the TLF team will be at the MAX2010 conference in Los Angeles. We’re not part of any formal sessions but we’re available to meet with TLF clients. We can help with code, discuss futures, listen and help with all issues – anything you want. If you’re in the LA area but not attending MAX we can meet outside the conference as well. Reply to this blog post or send an email to me rdermer (at) adobe.com if you’d like to schedule a time. Otherwise we’ll be there – it should say TLF on my badge – I filled it in as my job title.

TLF 2.0 Lists Markup

TLF 2.0 includes support for lists. Attached are two PDFs. The first describes the new markup and the second gives some examples:

Lists Markup

Lists Examples

The numbering algorithms for the various listStyleType values are defined here:
CSS3 List Style Types

Flex 4 Updates For TLF 2.0

TLF 2.0 is not a drop-in replacement into Flex 4. To even get it running changes are needed to Flex 4.0.T wo files need to be replaced in Flex 4 and spark.swc needs to be rebuilt.  The files, FTETextField.as and CSSTextLayoutFormat.as, are available for download here.

These changes were tested with Flex 4.0 SDK build 14159. I believe the same changes will work with Flex 4.1. To rebuild Flex with these changes:
1) From http://opensource.adobe.com/wiki/display/flexsdk/Download+Flex+4 download the “Open Source Flex SDK” you wish to modify.
2) replace the two files with the above modified versions.
3) run “ant -q main” in the frameworks directory
4) replace spark.swc with the one you just built.

There are other known issues. The biggest one is that TLF changed selection to permit inclusion of the final paragraph terminator in the selection from the selectAll API. This gives more consistent highlighting but caused some problems for Flex code. Fixes for this issue are not available for 4.0/4.1.

UPDATE For Flex 4.1

The changes for Flex 4.1 are to the same two files but the source files have changed in the Flex SDK.  I posted 4.1 versions here:  http://blogs.adobe.com/tlf/files/2010/08/FlexFixes41.zip

I’ve also seen the problem with building datavisualization.  I solved by copying manifest_datavisualization.xml to manifest.xml in the frameworks/projects/datavisualization directory.

TLF Update March 2010

FlashBuilder 4.0 is Released

FlashBuilder 4.0 includes Flex 4.0. TLF 1.0 – the official 1.0 release – is included as textLayout.swc. FlashBuilder is available here.

And of course TLF 1.0 and Flex 4.0 are opensource. The Flex 4 release with Flex 4 and TLF 1.0 source is available here: Flex4 Download

Flex 4.1 Nightly Builds Includes TLF 1.1

Flex 4.1 is not yet released but its opensource tree and nightly builds include TLF 1.1

TLF 1.1 has significant performance improvements for long documents. Scrolling and editing of long documents are both dramatically improved. Try it out! We’re looking for feedback and help in finding issues. You can pull textLayout.swc out of the Flex 4.1 nightly builds.

New And Updated TLF Samples

New and updated samples are posted: TLFSamples-734110.zip

These samples include the complete source to the TextLayout editor that was posted in on Adobe labs over one year ago. The editor and samples are all updated to the latest TLF version.

The samples include instructions for building them.

TLF Markup Overview

Introduction

The goal of this post is to give some information on TLF Markup. There is no DTD or other schema available at this time.

TLF Markup is converted to and from TextFlows using the TextConverter class. See the examples.

The attributes for TLF Markup are documented online and in the TextLayoutFormat class page bundled with the Flex 4 documentation. Get the documentation appropriate to the build you downloaded gumbo from here. Select the download from the “Language Reference Download” column.

Elements

The elements in TLF markup are all in the flashx.textLayout.elements package. This table maps elements to TLF classes and lists their allowed children.

XML Tag AS3 Class Allowed Children Elements/Notes
TextFlow TextFlow div, p, tcy, a, img, span, br, tab, format, linkNormalFormat, linkHoverFormat, linkActiveFormat, and raw text
div DivElement div, p, tcy, a, img, span, br, tab, linkNormalFormat, linkHoverFormat, linkActiveFormat, and raw text
p ParagraphElement tcy, a, img, span, br, tab, linkNormalFormat, linkHoverFormat, linkActiveFormat, and raw text
a LinkElement tcy, img, span, br, tab, linkNormalFormat, linkHoverFormat, linkActiveFormat, and raw text
linkNormalFormat TextLayoutFormat attributes overrides for link in normal state.
linkActiveFormat TextLayoutFormat attributes overrides for link in active state.
linkHoverFormat TextLayoutFormat attributes overrides for link in hover state.
tcy TCYElement a, img, span, br, tab, linkNormalFormat, linkHoverFormat, linkActiveFormat, and raw text
img InlineGraphicElement none allowed. see docs for additional attributes
span SpanElement br, tab and raw text
br BreakElement none allowed. Is normalized into a newline character by importer.
tab TabElement none allowed. Is normalized into a tab character by importer.