Platus Talks Flex

Announcement

2010-12-20T12:50:00.000+02:00

Too many blogs are closed unannounced, so I would like to announce that I will not be updating this blog anytime soon.

In the mean time, check out my new project (especially if you're a female).

Guinea Pig:
My new project requires you to be one

DateChooser with Months Combobox

2010-10-05T18:17:00.009+02:00

Left field is the Flex's default DateField.
On the right is my extended DateField (and extended DateChooser) - both together add the following features:

A combobox for changing the selected month.
A nice gray background to the days-of-week row (S M T W T F S).
The # of typed characters is limited to 10 (the maximum for the default mm/dd/yyyy format)

Source files:

EditableDateField.as
ModifiedDateChooser.as

I'll add some explanations later...

Migrating Flex 3 to Flex 4 pitfalls

2010-09-21T15:05:00.005+02:00

It should be fairly easy to compile a project written in Flex 3 in the new Flash Builder 4. However, there are a few pitfalls that I encountered and you may encounter too.

So here they are, plus the solutions.

Before you begin

Make sure you are using the latest SDK (currently 4.1)
Copy all your old source file, you don't want to ruin them just yet...
Create a new project, you will copy most of your old application mxml code there.
In Project Properties. Select Flex Compiler on the left, and in "additional compiler arguments" add -theme=${flexlib}/themes/Halo/halo.swc.
This will make your application look more or less like it used to when it was under Flex 3 which used the default Halo theme. Of course, if you used a different theme, include that theme instead

<mx:Application> is now <s:Application>
<mx:Style> is now <fx:Style>, <mx:Script> is now <fx:Script>

Copy your main application mxml and change it.
In the application tag these namespace attributes should now be:
   xmlns:fx="http://ns.adobe.com/mxml/2009"
        xmlns:s="library://ns.adobe.com/flex/spark"
        xmlns:mx="library://ns.adobe.com/flex/mx"

Change <mx:Script> to <fx:Script> on that file, too, and <mx:Style> to <fx:Style>.
For now, you don't have to do it in ALL your project files, just in the main application mxml.

If you have global style references, for example you are styling Button in all of your application, you should prefix it with the proper namespace. That is, because Flex 4 has its own button component with the same name.
So, if you wanna style only your Halo buttons, include in your <fx:Style> tag:

@namespace mx "library://ns.adobe.com/flex/halo";

and change button to

mx|Button

{
   color:#ffffff

};

If you are going to add spark buttons later and want to style them globally too, you will add something like:

@namespace s "library://ns.adobe.com/flex/spark";

s|Button

{
   color:#ffffff

};

Application.application is obsolete

In Flex 4, you can no longer use Application.application to reference your application. Instead, you now need to use FlexGlobals.topLevelApplication.

Luckily, in one of the latest Flex SDK 4 builds this is transparent to you as Application.as contains a property called "application" which simply returns FlexGlobals.topLevelApplication.

So you shouldn't need to change your code (especially if you have this reference all over your code, like I do).

Application.addChild() WILL fail

If you try to add an mx container or component to the application itself, it will no longer work with addChild. So use addElement() instead.
I won't explain here why, but addElement will actually create and add a proper spark container for you and add your component to it.
If you want to dig deeper on this check out this post (Update: Actually, this post explains this issue).

backgroundImage for Application is no longer supported

If you used backgroundImage in your old application, you will notice that it's no longer accepted. You will need to use a skin for your application instead Here's how.

"The style '___________' is excluded by type 'mx.containers._________'."

If you get this compiler error message it means you fucked up a style in Flex 3, but the old compiler looked the other way - whereas Flex 4 doesn't.
For example I had this piece of code in my project for some reason:

<mx:Canvas paddingLeft="0"

It took me a few seconds to realize that Canvas doesn't even support padding (it's excluded from the class, as you can see in the class's code).

So just delete these non-existing styles and these errors will be cleared.

Runtime Error in FocusManger:childHideHandler()

Once I got my app up and running, it wasn't the end of it. On certain scenarios I would get this runtime error:

TypeError: Error #1009: Cannot access a property or method of a null object reference.
at mx.managers::FocusManager/childHideHandler()[E:\dev\4.x\frameworks\projects\framework\src\mx\managers\FocusManager.as:1759]
at flash.events::EventDispatcher/dispatchEventFunction()
at flash.events::EventDispatcher/dispatchEvent()
at mx.core::UIComponent/dispatchEvent()[E:\dev\4.x\frameworks\projects\framework\src\mx\core\UIComponent.as:12528]
at mx.core::UIComponent/setVisible()[E:\dev\4.x\frameworks\projects\framework\src\mx\core\UIComponent.as:3088]
at mx.core::UIComponent/set visible()[E:\dev\4.x\frameworks\projects\framework\src\mx\core\UIComponent.as:3047]

Well, this actually turns out to be a known bug introduced in SDK 4.1, and apparently it was only fixed in Flex SDK 4.5!

The bug is caused when the focus is set on a component which goes invisible. There are a few alleged workarounds (I tried one or two, but they didn't work in my case).

One suggestion is to override the event listener for HIDE and invoke event.stopImmediatePropagation().

If that doesn't work, check out this forum thread for a possible solution.

Personally, the course of action I took was simply to download 4.5 and use it (I wasn't happy about it, though. I think Adobe should have fixed this back in 4.1. It's not a minor bug).

mx:GridLines's direction property is obsolete

Property is now named "gridDirection" :@

TabBar buttons with hand cursor (Flex 3)

2010-09-15T11:04:00.003+02:00

It's a small thing really, but I haven't seen it posted anywhere, so I thought I'd share.

PROBLEM:
You have a TabBar and you may want a hand cursor on mouseover of unselected tabs (the currently selected tab should keep showing a regular arrow cursor).

SOLUTION:
Extend TabBar, and -

Override resetNavItems() - adding a loop that also sets a hand cursor on all buttons.
Override hiliteSelectedNavItem() - reset the cursor to a hand cursor on the currently selected tab. Select the new tab (by calling super.hiliteSelectedNavItem) and then clear the hand cursor from that tab.
Override public get dataProvider() just adding a call to hiliteSelectedNavItem(selectedIndex).
The reason for that is that those other two methods are only called as a response to user interaction (clicking on tabs). We want to set the cursors as soon as the tabs are created, assuming the first tab is selected.

I'm pretty sure it's not the most efficient way of doing it, but hey - it works.

Source code here.

Text Layout Framework basics - Part 2

2010-08-26T10:19:00.005+03:00

It's always better to explain stuff by showing a real-life example. The sample application we'll create in this part of the tutorial is actually a continuation of what we already did in Part 1, except:

This time we will use TLF classes for the most part.
When the user resizes the application, we want our textflow to automatically adjust to the new size and redraw, and this includes re-positioning the inline dropdownlist.
(Unfortunately, you can't see this in the app below, you'll need to open it in a new window and resize it to see it in work. A direct link can be found here.)
We will add some interactivity to the text - namely - show tool-tips on some of the words (on mouse roll over).

In the first part we saw how to use the Flash Text Engine classes for basic text rendering. We created a TextBlock from several ContentElements, and then used the TextBlock's createTextLine() method to manually create and position the actual (visual) lines inside a container.

Now, it would be very weary to have to do this for every piece of text that we wanted to display in our application...

This is where the TLF classes come in handy: Instead of having to do these calculations by ourselves, we can simply link a textblock (the term in TLF is now TextFlow) to a container, leaving it up to Flex to handle the positioning (also called "composition"). This means, for example, that if the container is resized for some reason - it is now possible to automatically relayout the text accordingly to still fit inside it the best it can.

As usual, let's get ourselves familiar with the main packages in this framework first:

flashx.textLayout.elements
Contains the core classes used for representing text content in the Text Layout Framework. This are essentially the same "building blocks" we saw in Part 1, only now they have slightly different names, for example you can say that GroupElement is now called ParagraphElement; Instead of TextBlock, we use TextFlow etc..
All of these elements (like SpanElement, ParagraphElement etc) are FlowElements.
If they are grouping elements (meaning that they can contain other elements) they will also inherit from FlowGroupElement.
But if they're simple elements like text and graphic then they're considered a leaf in the textflow tree, so they will be inherited from FlowLeafElement.

flashx.textLayout.compose - contains the classes used for breaking text into lines, and arranging lines in containers.

There aren't many classes in this package. For a basic composition you will most likely use StandardFlowComposer.

flashx.textLayout.container - contains classes for displaying text in the Text Layout Framework.

In this chapter we will use the fundamental ContainerController which defines the relationship between a TextFlow object and a container.

flashx.textLayout.events - contains event classes for the Text Layout Framework.
The main events are: CompositionCompleteEvent, UpdateCompleteEvent, and FlowElementMouseEvent. We will see them in use later on this chapter.

Now let's see how we can use all that in our sample application:

Creating the Text Flow

TextFlow is the most basic class here... It contains all of our text (or "story") in the form of a hierarchical tree of elements. A TextFlow can, for example, look like this:

In this example our story contains two elements: a paragraph and a div element. That div by itself contains two other elements - another div and another paragraph. And That paragraph consists of a SpanElement, some graphics, a linkElement and so on...

The reason that this "tree" form is important is because it allows us to automatically apply any style that we give to a container element - to all of its descendants. For example, if I set my root textflow with a textcolor of green, then all of my text (in all the containing paragraphs, and THEIR children, etc.) will be green too, unless I change the color explicitly on one of the descendants...

One way to create a TextFlow is to import it from an HTML-like text, as this small example shows:

private static const textInput:XML = <TextFlow xmlns="http://ns.adobe.com/textLayout/2008">
 <div>
 <p color="0x336699"><span>The Text Layout Framework is an extensible library, built on the new text engine in Adobe Flash Player 10, which delivers advanced, easy-to-integrate typographic and text layout features for rich, sophisticated and innovative typography on the web.
 </span></p>
 </div>
 </TextFlow>;

private var _textFlow:TextFlow;
var importer:ITextImporter = TextConverter.getImporter(TextConverter.TEXT_LAYOUT_FORMAT);
textFlow = importer.importToFlow(textInput);

In our sample application, however, I don't want to import the text, so for now I'll just create an empty textflow and link it with my container the way TLF allows me to:

_textFlow = new TextFlow();
_textFlow.flowComposer.addController(new ContainerController(container, width - PARA_PADDING, height - PARA_PADDING));

Note that to the FlowComposer of a textflow I only add a single controller, and that's because I only have one container in my application. If I wanted my text to run over multiple containers for some reason, then I would have to add more controllers, so that there will be one for each container.

var p:ParagraphElement = new ParagraphElement();
p.fontSize = 16;
p.linkNormalFormat = [{color:0x0000aa}];

// -- some code to add SpanElements (one for each word) to the Paragraph goes here
//    and some LinkElements as well --

_textFlow.addChild(p);

Here I create a new paragraph, and set some of its styles. Pretty straightforward.
In the sample application I break a string with a space character as a delimiter, and add each word as a separate SpanElement to the paragraph.
For the two words I need tooltips for, however, I must create LinkElements, because they are the only text elements that can interact with the mouse!

The next lines tells my textflow that the the only thing the user can do with it is select text from it:

_textFlow.interactionManager = new SelectionManager();

If I wanted the user to be able to also edit the text, etc, I would replace SelectionManager with EditManager and so on.

Great. now let's listen to roll over and roll out events from our textflow:

_textFlow.addEventListener(FlowElementMouseEvent.ROLL_OVER, onRollOver);
_textFlow.addEventListener(FlowElementMouseEvent.ROLL_OUT, onRollOut);

Remember, they will trigger only for LinkElements.

OK, we're done composing our textflow.

The UPDATE_COMPLETE event

You might remember that in my previous inline uicomponent example application this is the point where we positioned our DropDownList. Now this position is no longer static, it can potentially change if the user resizes the application etc, so we can't do that here anymore. Instead, we'll listen to the UPDATE_COMPLETE event and do it there.

_textFlow.addEventListener(UpdateCompleteEvent.UPDATE_COMPLETE, repositionCombobox, false, 0, true);
_textFlow.flowComposer.updateAllControllers(); // update the display

updateAllControllers() is important, as it composes the content of the root element and updates the display immediately. It also triggers the UPDATE_COMPLETE event for the first time which we need in order to initially position our DropdownList.

The code for positioning the dropdownlist is a bit different with the TLF, it's actually easier because TextFlow now has a nice method called getElementById. Easy to locate our place holder InlineGraphicElement and move our dropdownlist on top of it:

// Whenever display is updated we need to reposition the dropdownList because
// its location in the flow could have changed
private function repositionCombobox(event:UpdateCompleteEvent):void
{
 // get inlinegraphicElement place holder and put combobox in its place
 var pHolder:InlineGraphicElement = _textFlow.getElementByID("b") as InlineGraphicElement;
 cb.width = pHolder.width - 20;
 cb.height = pHolder.height;
 
 // position combobox over the InlineGraphicElement
 cb.move(pHolder.graphic.localToGlobal(new Point(0,0)).x + 10, pHolder.graphic.localToGlobal(new Point(0,0)).y + 3);
 
 // add the combobox to the display list if not already added
 if (cb.parent != this)
  addElement(cb);
}

Handling resize

OK, now we just need to make sure that his method is called whenever the application resizes. This means two things: changing the composition size (it doesn't know to change automatically) and update the textflow display again.
here is the resize handler function:

private function resizeHandler():void
{
if (_textFlow && _textFlow.flowComposer.getControllerAt(0))
{     _textFlow.flowComposer.getControllerAt(0).setCompositionSize(container.width, container.height);
     _textFlow.flowComposer.updateAllControllers();
}
}

Responding to mouse rollover events to create Tooltips

This is the only somewhat complicated code in the application. The tricky part is to figure out the position of the LinkElement that has been rolled over, and create a tooltip just above it.
To find out an element's position we will have to find which actual TextLine currently contains that link. Luckily, you know all about it from Part 1 of this tutorial so you shouldn't be intimidated.

// Handle link roll over
private function onRollOver(event:FlowElementMouseEvent):void
{
if (tt)
{    
 ToolTipManager.destroyToolTip(tt);
 tt = null;
}
 
// Get the LinkElement that triggered the alert
var link:LinkElement = event.flowElement as LinkElement;
 
// Find out the link's position on screen
var linkStart:int = link.getAbsoluteStart();
var textFlowLine:TextFlowLine = link.getTextFlow().flowComposer.findLineAtPosition(linkStart);                
var lineStart:int = textFlowLine.absoluteStart;
var linkStartInLine:int = linkStart - lineStart;
var tl:TextLine = textFlowLine.getTextLine(true)
var rect:Rectangle = tl.getAtomBounds(linkStartInLine);            

var xx:int = rect.x;
var yy:int = rect.y; // y will always be 0
xx = container.localToGlobal(new Point(rect.x, rect.y)).x;
yy = container.localToGlobal(new Point(tl.x, tl.y)).y;
 
var word:String = event.flowElement.getText(); // our link's text

// ...
// code to create and place the tooltip goes here!
// ...
}

In lines 4-8 we just destroy any previously created tooltip, if one exists.
Line 11: It's very easy to get the LinkElement that triggered the event , with the event's flowElement property.
In line 14 we use getAbsoluteStart() to get the absolute index of our link in the textflow.
We then use it in line 15 to get the TextFlowLine that contains that link.
By the end of line 16 we have the absoluteStart of both our link and the line that contains it.
Subtracting one from the other gives us the position of the link RELATIVE to the line.

Line 18: This is the part where we need the FTE to get the actual TextLine that lays under the TextFlowLine.

Line 19: That's it! TextLine has a convenient method for getting for getting the bounds of a single atom (letter) in the line, by its index which we have by now!

From here, converting the coordinates to global ones and creating /positioning the tooltip on these coordinates is a breeze.

Full source will be uploaded as soon as someone leaves a comment below :)
Full source here.

Custom ColumnChart Labels using a Custom Item Renderer

2010-08-04T12:50:00.005+03:00

The Charting components are usually very flexible and fit most of your needs, but sometimes they fail in the simplest of things.

For example, the other day I needed a basic ColumnChart for a business application I was working on. The request was that instead of mouse-over Data-Tips, for each column a small label would appear with its value. Sounds simple enough, right?

At first for the ColumnSeries I set labelPosition to "inside",

and I got this:

OK, so the last column is too short to contain the label, but it would be nice if the ColumnSeries nudged it up a bit. Alas, no such luck.

Oh well, I thought, it wouldn't make much of a difference if the labels were to be outside, so I changed labelPosition again and this time I got:

Two problems: First, I wanted the labels outside, so why is the "0.9" inside the bar?
And second, why are my labels suddenly aligned to the left? I want them centered! And I know that it's possible.

You'd think adding the property labelAlign to "center" would fix that. Wrong again! When labelPosition is set to outside the only alignment possible is left. Why? Makes no sense to me...

Anyway, to make a long story short, after some research I came to the conclusion that the easiest way to fix these issues would be to simply write my own ColumnSeries item renderer, adding the labels to it manually.

Don't worry, no more "buts"; Writing an Item Renderer from scratch in this case is super easy! All you need to do is extend UIComponent making sure that you implement the IDataRenderer interface.

The result we want to achieve is this:

Features:

If a bar is too short to fully contain its label (like Europe in the screenshot), the label should appear above it.
The labels should be horizontally and vertically centered.
If the label is outside a bar, its color should change.

So, how do we do it?
First, we tell the ColumnSeries that we we want to use our own class (Let's call it ColumnBarRenderer) as a renderer. We'd better also remove the labelPosition property because we're going to put our own label.

Now let's create the class. Like I said, it should extend UIComponent and implement IDataRenderer.

Implementing IDataRenderer is actually very simple - all we need to do is include a getter and a setter for the "data" object. In this case, the data object that will be passed to us will be of type ColumnSeriesItem (base class: ChartItem). We need this data in our renderer because it contains all we need to know about the column bar we are drawing.

private var _chartItem:ChartItem;
  
  public function set data(value:Object):void
     {
         if (_chartItem == value) return;
           // setData also is executed if there is a Legend Data 
           // defined for the chart. We validate that only chartItems are 
           // assigned to the chartItem class. 
         if (value is LegendData) 
          return;
         _chartItem = ChartItem(value);         
     } 
  
     public function get data():Object
     {
         return _chartItem;
     }

The second step is to create our custom label. In a UIComponent the creation of child components is usually done in the createChildren() function. So let's override it and create our label there, formatting it as we like:

private var label:Label;

  override protected function createChildren():void
  { 
   super.createChildren();
   if (label == null)
         {
          label = new Label();
          label.truncateToFit = true; 
          label.setStyle("fontSize", 12);       
          label.setStyle("textAlign", "center");
          addChild(label);
         }         
  }

Now, you're probably thinking : "I somehow need to know the dimensions of the column I'm drawing, don't I?" Well, No. Because the ColumnChart already sizes every renderer that it creates, when we update the display list for our renderer, the size of our UIComponent is already the calculated size of the column (according to its current value).

Here's a simplified version of our renderer's updateDisplayList() function (the code that handles the label is omitted):

override protected function updateDisplayList(unscaledWidth:Number,unscaledHeight:Number):void
  {
   super.updateDisplayList(unscaledWidth, unscaledHeight);
   
   var rc:Rectangle = new Rectangle(0, 0, width, height);        
   var g:Graphics = graphics;
   g.clear();        
   g.moveTo(rc.left, rc.top);
   
   //
   // handle label position here
   //
   
   if (_chartItem == null) // _chartItem has no data
    return;
   
   // Draw the column
   g.beginFill(0xff0000, 0.9);
   g.lineTo(rc.right,rc.top);
   g.lineTo(rc.right,rc.bottom);
   g.lineTo(rc.left,rc.bottom);
   g.lineTo(rc.left,rc.top);
   g.endFill();    
  }

Note that we simply draw a box from (0,0) to (width,height) of the component. We don't have to deal with the calculations of how high the column should be depending on its value, or how wide, etc. All of this is already done for us. Pretty neat, huh?

So far so good, but now comes the tricky part, i.e. positioning the label vertically-(and horizontally)-centered inside each column, except when there's no room for it (because the column value is too low), in which case we need to position it slightly above the bar. And let's not forget to set the text of the label, containing its numeric value.

Like I said before, the only way for our renderer to get any information about the chart and its data is through the data property which we stored in the getter (in the _chartItem which is a ColumnSeriesItem).

ColumnSeriesItem contains all the information we need about the box we're currently drawing (including the data row itself), but also the ColumnSeries (through the .element property). Specifically, we get from that the yField of the series, so we can extract the value from the data item and set it as the label's text.

OK, let's cut to the chase. Here's how we set the label:

var cs:ColumnSeries = _chartItem.element as ColumnSeries;
var csi:ColumnSeriesItem = _chartItem as ColumnSeriesItem;
   
// set the label           
label.text = csi.item[cs.yField].toString();          
label.width = label.maxWidth = unscaledWidth;         
label.height = label.textHeight;
var labelHeight:int = label.textHeight + 2;

In lines 1 and 2 we extract the ColumnSeries and the ColumnSeriesItem from the data.
In line 5, we use the series' yField property to get the numeric value of the current column from the item itself.
In line 6 the width of the label is set to match the total width of our column so that the label will be centered (remember that in createChildren we set the textAlign of the label to 'center'). Line 7 sets the height to match the label's actual height (depending on the its set font size). Finally we store that height.

Now let's see how we position the label:

// label's default y is 0. if the bar is too short we need to move it up a bit
         var barYpos:Number = csi.y;
         var minYpos:Number = csi.min;
  var barHeight:Number = minYpos - barYpos;
  var labelColor:uint = 0xFFFFFF; // white
        
         if (barHeight < labelHeight) // if no room for label
         {
    // nudge label up the amount of pixels missing
          label.y = -1 * (labelHeight - barHeight);
          labelColor = 0x222222; // label will appear on white background, so make it dark          
         }
         else
          { 
          // center the label vertically in the bar
                 label.y = barHeight / 2 - labelHeight / 2;
          }
   
  label.setStyle("color", labelColor);

The key to understand this code is to know what the two properties ColumnSeriesItem.y and ColumnSeriesItem.min mean.
If our chart's top y position is 0, then csi.y is where our column box begins (or ends), and csi.min is where it ends (or begins, depends how you look at it).
What I mean is :

Once you know this, checking if our label fits in the column box is a piece of cake, as well as nudging it up a bit if needed, and centering it vertically.

The full source can be found here. (RAR file)
For a ZIP file click here.

Text Layout Framework Basics - Part 1

2010-07-30T11:14:00.009+03:00

In this series I am going to explain the basics of using Adobe's new Text Framework. In this first part you'll learn about the Flash Text Engine.

The Flash Text Engine (FTE) is a set of new classes (found in the flash.text.engine.* package) that support low-level text functionality in Flash Player 10

While you can use the FTE in Flash Builder 4 to render text, you will probably more often use the TLF
(Text Layout Framework), which is a set of classes built on top of the FTE to provide more high-level text functionality, such as scrolling, selection and editing.

But let's not rush things (TLF will be covered in the next part). Right now let's take a quick look at the main classes of the Flash Text Engine and see what we can do with them.

A TextBlock holds a single paragraph of text, built from 3 types of ContentElements:
( ContentElement is the base class for each of the three, but it's an abstract class so you won't be able to create an instance of it by itself) :

TextElement , which is simply a string
GraphicElement which is any graphic or image that you wish to include in your text.
GroupElement which is a just container for the other two classes, but may also contain other (nested) GroupElements.

So I could, for example, create two TextElements, one with the string "hello" and the other with "world", put them inside a GroupElement and then put that group inside a TextBlock, and what I'll have is a nice "helloworld" block of text (with no space between the words, because none of my strings included one).

The only problem with this TextBlock, however, would be that because it's not a DisplayObject,
no user will ever see it. And in fact, all of the aforementioned classes are purely logical classes in the sense that they just hold information about the text composition, but not the text itself.

Luckily, the TextBlock has a nice method called createTextLine() which, unsuprisingly, takes the TextBlock and generates TextLines from it that can easily be added to the display list (we'll see how it's done in a moment).

One additional class that does not show in the nice diagram above, but is just as important, is the ElementFormat class, which defines the text styling (like the color, alpah, font, etc.) for any ContentElement, via the elementFormat property.

But enough talk. Let's see some things in action! The following example application creates a TextBlock containing the first two sentences from the book "Moby Dick", and displays the first two TextLines from it.

Explanations - after the code (and also inside the code, as comments).


<?xml version="1.0" encoding="utf-8"?>
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
               creationComplete="creationCompleteHandler(event)"
               xmlns:s="library://ns.adobe.com/flex/spark" 
               xmlns:mx="library://ns.adobe.com/flex/mx" minWidth="955" minHeight="600">
    <fx:Script>
        <![CDATA[
            import flash.text.engine.ContentElement;
            import flash.text.engine.ElementFormat;
            import flash.text.engine.GroupElement;
            import flash.text.engine.TextBlock;
            import flash.text.engine.TextElement;
            import flash.text.engine.TextLine;
            
            import mx.events.FlexEvent;
            
            protected function creationCompleteHandler(event:FlexEvent):void
            {
                // prepare the text
                var str1:String =  "Call me Ishmael. Some years ago - never mind how long precisely - having little or no money in my purse, ";
                var str2:String = "and nothing particular to interest me on shore, I thought I would sail about a little and see the watery part of the world.";
                
                // prepare text formatting
                var format:ElementFormat = new ElementFormat();                
                format.fontSize = 14;
                
                // create two text elements, one for each string
                var te1:TextElement = new TextElement(str1, format);
                var te2:TextElement = new TextElement(str2, format);
                
                // prepare an array containing the two textElements and include them in a GroupElement
                var groupVector:Vector.<ContentElement> = new Vector.<ContentElement>();
                groupVector.push(te1);
                groupVector.push(te2);                
                var ge:GroupElement = new GroupElement(groupVector, format);                
                
                // Create a textblock holding the composed group
                var tb:TextBlock = new TextBlock();
                tb.content = ge;
                
                // Create two TextLines from the TextBlock
                var tl1:TextLine = tb.createTextLine(null, 550); // first line
                container.addChild(tl1);                
                var tl2:TextLine = tb.createTextLine(tl1, 550); // second line
                container.addChild(tl2);
                tl2.y = tl1.textHeight;
            }
            
        ]]>
    </fx:Script>
    <fx:Declarations>
        <!-- Place non-visual elements (e.g., services, value objects) here -->
    </fx:Declarations>
    
    <s:Group id="group" y="30">
        <s:layout>
            <s:VerticalLayout />
        </s:layout>
        <s:SpriteVisualElement id="container" />            
    </s:Group>
    
</s:Application>

The result :

The first thing you probably notice when you run the application is that the text is not fully shown.
The reason is that when you create a TextLine, you also must specify its desired (max) width. In this case I gave the two TextLines 550 pixels each, and that simply was not enough to hold all of my text.

The second thing to note is that for the first parameter, createTextLine() expects you pass the previously created TextLine (or Null if it's the first). This is required so that the function can calculate the position from which it should continue reading the text.

But what if we wanted to change the code so that ALL of my text will be shown, no matter what?
To do that, we would simply have to keep creating TextLines... until we run out of text :


                var yPos:int = 0;
                var prevTextLine:TextLine = null;
                while (true)
                {
                    yPos += (prevTextLine == null ? 0 : prevTextLine.textHeight);
                    prevTextLine = tb.createTextLine(prevTextLine, 550);
                    if (prevTextLine == null)
                            break;
                    
                    container.addChild(prevTextLine);  
                    prevTextLine.y = yPos;
                }

createTextLine() returns Null when the end of the text is reached, so at that point we exit the loop.

**

In the next part I'll talk about the more useful Text Layout Framework (TLF) that simplifies things and adds some powerful functionality. I'll demonstrate how you can use it to enable mouse interactions on rendered text (i.e. show a tooltip on a word or phrase on mouseover).

Inline UIComponents within a TextFlow

2010-07-24T14:16:00.013+03:00

Lately I've been thinking about how to go about coding a "fill in the gap" exercise. This kind of exercise is very popular in e-learning applications : the user is presented with text in which a few words are missing, and he has to type them in (or select them from a list).

Now, prior to Text Layout Framework, you would probably be forced to break down your text into single words, adding each one as a Label to a container (and of course a TextInput where needed). While this sounds relatively easy, it's actually not once you start realizing that you need to position the labels yourself, taking into consideration things like line breaks, mixed RTL/LTR text, nested text styling, etc. etc., which no programmer should ever have be left to deal with on his own (that is, unless what he's actually coding IS a text framework).

Luckily, now that we do have the TLF available to us in Flex 4, things are much more simple. The example below is pretty straightforward (and very well commented), but the idea is: We add each word or phrase as a SpanElement inside a ParagraphElement. For the blank gaps we add an empty InlineGraphicElement to serve as a placeholder. Once we update the display all we have left to do is calculate where that InlineGraphicElement is (x,y), and add our own flex-UIComponent-based component in its place.

This example is a very basic one. I might post a more extensive one (based on given XML, etc.) if/when I ever get to writing one.


<?xml version="1.0" encoding="utf-8"?>
<s:Application creationComplete="init()" xmlns:fx="http://ns.adobe.com/mxml/2009" 
               xmlns:s="library://ns.adobe.com/flex/spark" 
               xmlns:mx="library://ns.adobe.com/flex/mx" minWidth="955" minHeight="600">
    <fx:Declarations>
        <!-- Place non-visual elements (e.g., services, value objects) here -->
    </fx:Declarations>
    <fx:Script>
        <![CDATA[
            import flashx.textLayout.container.ContainerController;
            import flashx.textLayout.edit.SelectionManager;
            import flashx.textLayout.elements.InlineGraphicElement;
            import flashx.textLayout.elements.ParagraphElement;
            import flashx.textLayout.elements.SpanElement;
            import flashx.textLayout.elements.TextFlow;
            import mx.collections.ArrayList;
            import mx.core.UIComponent;
            import spark.components.DropDownList;
            
            [Bindable]
            private var _textFlow:TextFlow;
            
            [Bindable]
            private var _ac:ArrayList = new ArrayList([{label:'red'},{label:'lazy'}]);
            
            private function init():void
            {    
                // create a new textflow
                _textFlow = new TextFlow();
                
                // create sprite to contain the text
                var sprite:Sprite = new Sprite();
                
                // contain the textflow in that sprite
                _textFlow.flowComposer.addController(new ContainerController(sprite, 500, 100));
                
                // create a paragraph and set font size
                var p:ParagraphElement = new ParagraphElement();
                p.fontSize = 14;
                
                // add some words
                addText(p, "The ");
                addText(p, "quick brown fox jumps over the");
                
                // add an empty InlineGraphicElement as a placeholder
                var pHolder:InlineGraphicElement = new InlineGraphicElement();
                pHolder.width = 120;
                pHolder.height = 20;
                p.addChild(pHolder);
                
                // add another phrase
                addText(p, "dog.");
                
                // add the paragraph to the textflow            
                _textFlow.addChild(p);                
                
                // allow only selection of text
                _textFlow.interactionManager = new SelectionManager();
                
                // update the display
                _textFlow.flowComposer.updateAllControllers();        
                
                // we need to figure out the absolute position of the InlineGraphicElement
                // note that an InlineGraphicElement's graphic position is always 0,0 inside a parent Sprite.
                //         var ph:Sprite = pHolder.graphic.parent as Sprite;            
                //         i.e. var phPoint:Point = new Point(pHolder.graphic.x, pHolder.graphic.y); // phPoint will always equal (0,0) !
                
                // create a new combobox and set its dimensions and data
                var cb:DropDownList = new DropDownList();
                cb.dataProvider = _ac;
                cb.width = pHolder.width - 20;
                cb.height = pHolder.height;
                
                // add the text to the display list
                container.addChild(sprite);
                
                // move the sprite from its (0,0) default just to prove that the position of the combobox is calculated correctly
                sprite.x = 50;
                sprite.y = 30;
            
                // position combobox over the InlineGraphicElement
                cb.move(pHolder.graphic.localToGlobal(new Point(0,0)).x + 10, pHolder.graphic.localToGlobal(new Point(0,0)).y);    
                
                // add the combobox. note that this is done AFTER adding the sprite so that it will be on top and interactive
                addElement(cb);
            }

            // creates a span with some text and adds it to the given paragraph
            private function addText(p:ParagraphElement, phraseText:String):void
            {
                var span:SpanElement = new SpanElement();
                span.text = phraseText;
                p.addChild(span);
            }
            
        ]]>
    </fx:Script>
    
    <s:SpriteVisualElement id="container" />    
    
</s:Application>

Flex Text Layout Framework - "How To" post

2010-07-24T11:30:00.012+03:00

Since this is my first post to the blog, let me introduce myself (but only briefly, since I find it kind of boring): I have been a UI programmer for about 10 years now, beginning with the ancient Visual Basic, continuing to web development (mostly with XSL and JS), and for the last 2 years I've been using Flex 3 for the UI interface of a Transaction Management application in the company I work for.

I have found Flex 3 to be an overall solid (and fun to work with) framework (espcially compared to JS), but also somewhat frustrating at times (especially when extending the framework's native classes becomes a must)., so I'm quite excited about learning and switching to Flex 4, hoping for things to be more smooth

Anyway,

I've been especially interested in Adobe's new TLF (Text Layout Framework) for some time now, having in mind an idea for a project that requires some heavy text rendering capabilities. Now that it's finally out and included in Flash Builder 4, I am trying to find the time to research it again.

As I do so, I figured it could be helpful for programmers new to the TLF (such as I, at least currently) to maintain a "How To" post with links to useful articles in other blogs, forums, etc. that I may stumble across.

I will be adding more links as I find them....

Introduction to the Text Layout Framework in Flex 4
If you know nothing (programmatic-wise) about the TLF, this is the place to start. You need to know the relationship between the following classes/interfaces: TextFlow, ContainerController, IFlowComposer, and TextLayoutFormat.

Utilizing Flash Text Layout Framework using MXML tags
Elad Elrom's article gives you a nice summary about the connection between the TLF and Flex 4's new text-based components.
Note: Since this article is based on the Beta version of flex 4, some things are no longer true (for example, SimpleText is now called Label. Why? See here).

UPDATE: I've decided to abandon this post thread, replacing it with with a series of tutorials about the Text Layout Framework. So watch out for future posts!

test