UPDATE 28 April 2010 : This subject is revisited in relation to Flex 4 spark components, here.

The problem: In Flex, how to overlay the video with something (e.g. a logo or caption) and keep the overlay relative to a corner of the actual video rectangle. Sounds like it should be a simple matter of creating a container and layering in the VideoDisplay instance and the over lay instance ? But…

In each of the following samples:

• We have an <mx:Panel> which has been extended to be reposition-able (drag the title bar) and resizable (drag the lower-right corner).
• The panel contains an <mx:VideoDisplay> with 100% width and height
• The panel also contains an overlay graphic – in this case using <mx:Image>
• To view the samples you need to have Flash Player 10.0.32. or higher installed. You can get the latest Flash Player from here: http://get.adobe.com/flashplayer/
• The source-code for these samples can be downloaded
• View source with a right-click on each of the samples

Video Display overlay Sample 1

In our first sample we simply place our overlay image using attributes ‘top’ and ‘right’ to keep the overlay’s top-right corner to 10px in from the VideoDisplay top-right corner.

It basically looks fine until you hit the play button and start resizing the panel.

As you can see the actual video within the VideoDisplay is constrained by its rectangle and depending on the differing aspect ratios, there will either be black space at the sides or the top, and our overlay is faithfully anchored to top right corner of the VideoDisplay and looks odd unless the aspect ratios are equal.

So how to solve this?

Looking at the documentation for VideoDisplay, there are many width and height properties to play with, however none of these relate to the current width and height or position of the contained video rectangle. You might think while looking at the documentation that the videoWidth and videoHeight properties might give the values we are after, but not so. They only return the ‘original’ width and height of the loaded video.

Fortunately the OpenSource nature of the Flex SDK and the magic of, holding the command key on a Mac (control key on a PC) with the cursor over  the <mx:VideoDisplay> opening tag, then clicking it as it underlines,  (using in Flash Builder  or Flex Builder) will open the source for the VideoDisplay component within a new editor. Browsing through the code you will see at line 198:
mx_internal var videoPlayer:VideoPlayer = null;

It is this videoPlayer instance who’s properties we need to monitor to calculate our overlay’s position. The instance is not generally exposed through the VideoDisplay component’s api. Nor is it documented. However since it has been placed in the mx_internal name space, we can actually access it with namespace notation…

videoDisplay.mx_internal::videoPlayer.attribute

Where we replace ‘attribute’ with the property name we are after, so the following would be of use to us…

videoDisplay.mx_internal::videoPlayer.x
videoDisplay.mx_internal::videoPlayer.y
videoDisplay.mx_internal::videoPlayer.width
videoDisplay.mx_internal::videoPlayer.height

Video Display overlay Sample 2

In this second sample, we create a positionOverlay method and call it from the resize event of the VideoDisplay component. Within positionOverlay we use the name space notation to get the videoPlayer properties and use some basic maths to reposition our overlay based on the top-right corner of the videoPlayer instance rather than the videoDisplay instance.

Additionally we call positionOverlay from our applicationComplete handler to set the initial position.

This basically seems ok, but play with it for a while and it is clear that something is wrong…

• Resizing slowly, seems ok
• Resizing quickly, and there seems to be some lag in the position of the overlay
• Release the resize handle while resizing quickly and the overlay can be left behind in completely the wrong place

Having traced the videoPlayer instance properties from within the positionOverlay handler, it is apparent that while the videoDisplay properties are correct, the videoPlayer properties are as they were previously. i.e. as they were rather than as they shall be.

Video Display overlay Sample 3 – This one works properly!

This is where Player version 10 comes in. It added Event.EXIT_FRAME. (If your project targets a player older than 10, you will not see this event in your code assist.) If we use the exit frame event to defer the call to overlayPosition, we can then get measured values from videoPlayer and correctly position the overlay.

To do this I have created a new method positionOverlayOnExitFrame who’s job is to add an EXIT_FRAME listener who’s handler will be overlayPosition. The first job of which is to remove the listener, so that it only gets called once. By using a listener we need to change the interface of overlayPosition to accept an Event argument. But we are not interested in the event information and we still wish to call positionOverlay directly, so we have allowed the argument to have a null default.

Playing with the resize handle now, no-matter how quickly it is moved, shows no lag, and always drops in the correct place.

Finally, just to re-iterate, source code zip for these examples is here.

Note: These samples were built against Flex SDK version 3.4.

Note: I haven’t found any official documentation relating to when Event.EXIT_FRAME arrived in the player runtime. The Flash CS4 documentation for Event.EXIT_FRAME indicates player 9. However unless you target player 10 in Flex/Flash Builder, you will get compile errors. If anyone has accurate references, please post to the comments – thanks.

Note: When you look at the source view, it appears ragged. This is because in creating the HTML, Flash builder simply converts tab characters to four space characters. Clearly not every tab in my code actually represents 4 characters and therefore what should look like neat columns becomes ragged. I have filed a bug/enhancement request. If you too would like this fixed, feel free to add your vote to FB-23060.

The Flex documentation attempts to describe the lifecycle, but can leave the developer with lots of unanswered questions. When I got more involved in developing components I found chapter 19 of Programming Flex 3 good for filling in the gaps.

This week a new and free paper has been published by DevelopmentArc that also explores the component life-cycle and the application life-cycle. A very well worth while read….

Understanding the Adobe Flex® 3 Component and Framework Lifecycle

Feel free to post links to other compent lifecycle resrouces in the comments.

public function BitmapData(width:int, height:int, transparent:Boolean = true, fillColor:uint = 0xFFFFFFFF)

I needed a transparent bitmap. Reading the default “transparent:Boolean = true”, I assumed by simply supplying width and height, a transparent bitmap is what I would get. Not so! I got a white rectangle. The reason being, that the default fill colour is 100% white. (The first pair of FFs representing the alpha in ARGB).

At first it would seem slightly unintuitive for the second default to conflict with the first, until one realises that the ‘transparent’ flag is there to indicate whether the object will support transparency or not. Not to state that it should be initially created transparent. Supporting transparency increases data size from 24 bits per pixel to 32 bits per pixel.

So what i should have done :

bmd = new BitmapData( width, height, true, 0 );

Having been chastised for using these ‘unknown acronyms’ in my comment on jd’s weblog, I thought it worth writing a brief entry describing what these acronyms stand for and how they may be of interest for those purchasing or upgrading Adobe software.

• AOO : Adobe Open Options

• TLP : Transaction Licensing Program

Essentially this is all to do with volume licensing as an alternative to purchasing products through the Adobe store or other 3rd party suppliers. Volume licensing sounds like it is aimed at large organisations purchasing site-license. However the Transaction Licensing Programme facilitates as little as a single product license. The way the scheme works is to provide a transaction discount should you purchase multiple products in a single transaction based upon a point value for each product. TLP purchases may be made through 3rd party suppliers, but also through Adobe directly as in my case. There is no published price list so you need to request a quote.

The key point of interest to me was the Upgrade Plan which allows licenses to be purchased over 24 month subscriptions. Essentially this means I effectively have already paid to cover my CS4 upgrade. This is the point I was trying to make on jd’s weblog. He acknowledges that trial versions of CS3 products not being available until mid November is a ‘Pain point’ and he provides some explanation including the phrase “The big shipping versions get released first.”. Well I’m a AOO TLP upgrade licensee who’s just been told I may have to wait until the ‘end of November’ for it to physically ship to me. If it is painful for ‘users’ who haven’t paid for the software yet, imagine the pain for those who have paid for the software, but may have to wait until the end of November.

So while the Upgrade Plan offers some value, fulfilment seems less than ideal especially given this Key benefit documented on the Adobe site: “Get timely notifications of new upgrades, so you can stay on top of new product releases.”.

This is now my latest bug-bear. For Adobe to see how the customer experience could be improved in this regard, they need only look back to the now discontinued Macromedia DEVNET Pro subscription, where serial numbers and downloadable installers were immediately available to subscribers from day one of a new product shipping.

If this was fixed, I could now be blogging about cool new stuff in CS4 rather than  fuming over this and wondering if I would actually be better-off purchasing through conventional means.

UPDATE : 28/10/2008

Received my Adobe License Fulfilment email on 26th. Logged in and was able to request media for the upgrades, but at the time couldn’t see serial numbers or any way of downloading. However just checked again today, and the serials are there and I now have downloads in progress – and at a good bit-rate. So I’m feeling a lot happier now than when this post was originally published. While the process has not been entirely seamless, this time is far better than my previous experience with CS3 where I had to wait for physical media.

Always good to hear how others work with their clients too in the “ActionScript in Commercial Environment”session.

Full details: London Flash Platform User Group 25th Sept 2008

Point the configurationFile property to the location of that file: as in the following ActionScript:
appUpdater.configurationFile = new File("cfg/updateConfig.xml");

If you are familiar with the File class, you will see that this is likely to generate a run-time-error, especially when testing in adl…

ArgumentError: Error #2004: One of the parameters is invalid.
at Error$/throwError()
at flash.filesystem::File/set nativePath()
at flash.filesystem::File()

If you are like me, you’ll probably want to place the updateConfig.xml file within the application directory next to the *-app.xml file. If so, the line of code you need can be written:

appUpdater.configurationFile = new File( File.applicationDirectory.resolvePath( "updateConfig.xml" ).nativePath );

or more compactly, using the “app:/” url scheme:

appUpdater.configurationFile = new File( "app:/updateConfig.xml" );

Typically AIR developers will all want to take advantage of the Update capability, but in it’s original form requires some work. Rich Tretola’s UpdateManager did the job, but I wanted more programmatic control, interception of events and a slightly different UI work-flow, and set about creating my own.  Just as that phase of the work is completed, I find Adobe’s Update Framework on labs which although beta, does a much better job. I wish it was there a week ago.

Also, I just took the opportunity to update to AIR 1.1. Unfortunately updating Flex to use the new AIR is a little messy (in that it requires manually copying some files rather than running an installer) and means moving to the 3.0.2 stable build of the Flex SDK. However it is not difficult and the instructions to follow are here.

TypeError: Error #1010: A term is undefined and has no properties.

.. with a traceback indicating the error occurred within DataGrid.as. At which point you will stare at your own code for a while and wonder why.

In my circumstance I pinned this down to clearing the contents of the data provider and repopulating when there is an item renderer active on the DataGrid. A use-case that probably doesn’t come up that often in web-based Flex apps, since if the user clicks another control to trigger an update, the item renderer is exited at that point and the edit committed prior to the dataprovider changing.

In an AIR app, we have native menus available to us. When the user employs native menu selection, the item editor remains active. If that menu option triggers a repolpulation of the data provider (use-case example File>Open), we then get the error.

The workaround is pretty simple. A call needs to be made to destroyItemEditor() on the DataGrid instance before repopulating it’s data. In a simple application this is no great problem. But if you’ve gone to the effort of using something like the PureMVC framework to separate Data Object from View Components, the data object isn’t supposed to have any knowledge of the view. So in my case thefix is quite crude – when issuing the open command, a notification to destory item editors will be issued so any view component that uses them may destroy their editor prior to the repopulation.

My contention is that it should be the responsibilty of the DataGrid to destroy the item editor if the dataprovider updates.

I have this logged as a bug with Adobe (SDK-15280), along with sample code demonstrating the issue. Feel free to review and vote for the bug if you are in agreement with my point and comment further therein if you disagree or have better suggestions to offer.

If you are thinking there must be a way to do this using a component. You’d be right, but it is documented in the “Using the Flex AIR components” “About the FlexNativeMenu control“section not the “Windows, menus and taskbars” section.