Marc Leuchner and Matt Wright (of NoBien fame) and I have been burning the midnight oil to deliver an exciting book on Adobe AIR – AIR Create-Reuse-Modify from Wiley Wrox press. Each chapter walks through building applications as you learn about the AIR API. We had a lot of fun architecting and writing about each application that highlights specific facets of the platform and hope it is as much fun to read. Adobe AIR and the API is part of the Flex 3 SDK, which might be coming out soon…

Well, i didn’t stop at discussing one part of the Flex 3 SDK and also was asked by Josh Noble to be a co-author for the Flex 3 Cookbook from the O’Reilly press. We’ve gathered the submissions from the Adobe online cookbook and Josh has been steering the cookbook ship to greatness. If you are unfamiliar with the O’Reilly cookbook format, the book is designed to present hundreds of ‘recipes’ aimed at solving programming problems. I have had the extreme pleasure to write about parts of the Flex API that i love and believe to be essential to RIAs developed using the Flash Platform.

If writing didn’t keep me busy enough, I worked with some amazing people while building applications that stretched the possibilities of what online and desktop applications built in Flex can do. Along the way i learned more about the business, some agile practices (which i hope to write about some) and how to have fun and love what i do. It is an amazing thing.

I also have had the opportunity to join the Infrared5 team and could not be happier. Infrared5 is a consulting company started by Chris Allen, Rebecca Allen and Dominick Accattato focused on architecting applications using the Flash Platform and Red5 Server technologies. Keith summed it up pretty well in this post. I am honored to be in company with some of the brightest minds in the field that keep me laughing throughout the day. Once I stop breaking things around the office, i can settle in and learn something

All in all, 2007 was a great year and i am making out 2008 to be even better. Here’s to posting more!

That said, there is a coupling of features of AIR while leveraging the Flex Framework that i cannot hold inside and think is worth mentioning: Associated filetypes, the invoke event, and BindingUtils.

To view and download the full code, click here.

File Types
First off, you can associate filetypes to your AIR app in the application descriptor file within the fileTypes node:

<filetypes>
    <filetype>
      <name>com.example</name>
      <extension>ftf</extension>
      <description>FileTypeFun file</description>
      <contenttype>text/plain</contenttype>
    </filetype>
</filetypes>

Once the AIR app is installed on your machine, a file with the extension set as the value of the extension node will be associated with your app. Meaning, it will show up first in the list when you choose ‘open with’ and even invoke the app if you double-click on the file – that is if the extension is not associated with another program on your machine (ie. doc) in which case you will have to set your app to always open associated as default to your app.

InvokeEvent
The invoke event of a WindowedApplication will be triggered upon initial instantiation – without having the application previously running – and any subsequent ‘open with file’ calls. The arguments property of the InvokeEvent is an array of arguments passed through invocation of the app. This not only allows command line junkies to open an application with a file like so:

On Mac:
>open MyAirApp.app MyDocuments.ftf

On Windows:
>MyAirApp MyDocument.ftf

.. but as well as double-clicking or choosing ‘open with’ on a file (as describe above). Probably you wouldn’t have any documents lying around in your applications directory – but you get the picture. To handle those arguments your app would look something like as follows:

< ?xml version="1.0" encoding="utf-8"?>
<mx :WindowedApplication 
    xmlns:mx="http://www.adobe.com/2006/mxml"
    layout="vertical" 
    horizontalAlign="center" verticalAlign="middle"
    invoke="onAppInvoke(event);">
 
    </mx><mx :Script>
        < ![CDATA[
            private function onAppInvoke( evt:InvokeEvent ):void
            {
                var items:Array = evt.arguments;
                for( var i:int = 0; i < items.length; i++ )
                {
                    trace( items[i] );
                }
            }
        ]]>
    <mx :Label text="Welcome" />
</mx>

Note:
AARG… i can’t find a decent mxml plugin for Wordpress. There is an errant closing mx tag before the script and the closing tag at the end should read /mx:WindowedApplication . If anyone has any tips on a good plugin, please leave a comment!

This assigns the onAppInvoke() method as the handler to the ‘invoke’ event dispatched from WindowedApplication upon instantiation AND any subsequent invocation calls. The arguments attribute of the InvokeEvent is a list of strings – deliminated by space if you on the command line. From here, just handle them as you want to. In following with this example we are going to handle paths to simple text files.

BindingUtils
All this filetypes and invoke events craziness is enough to warrent me to stop writing… but i got to thinking (always bad news)… what if i’ve got an ‘invoke’ event that may trigger prior to the creation of a client that needs to know about an opened file, or more so, the app needs to switch focus to a client that has yet to be instantiated that knows how to handle that file? This is where BindingUtils and ChangeWatcher come into play and really show off the power of the Flex Framework.

< ?xml version="1.0" encoding="utf-8"?>
<mx :WindowedApplication 
    xmlns:mx="http://www.adobe.com/2006/mxml"
    layout="vertical" 
    horizontalAlign="center" verticalAlign="middle"
    applicationComplete="onAppComplete();"
    invoke="onAppInvoke(event);">
    </mx><mx :Script>
        < ![CDATA[
            import mx.binding.utils.ChangeWatcher;
            import mx.binding.utils.BindingUtils;
            import mx.events.FlexEvent;
 
            private var _invokedFile:File;
            private var _fileWindow:FileDisplayWindow;
            private var _filesBinding:ChangeWatcher;
 
            private function onAppComplete():void
            {
                _filesBinding = BindingUtils.bindSetter( invalidateFiles, this, 'invokedFile', true );
            }
 
            private function onAppInvoke( evt:InvokeEvent ):void
            {
                var items:Array = evt.arguments;
                if( items.length > 0 )
                {
                    invokedFile = new File( evt.arguments[0] );
                }    
            }
 
            private function openFileWindow():void
            {
                _fileWindow = new FileDisplayWindow();
                _fileWindow.addEventListener( FlexEvent.CREATION_COMPLETE, applyFileToWindow );
                _fileWindow.open();
            }
 
            private function applyFileToWindow( evt:FlexEvent = null ):void
            {
                _fileWindow.file = _invokedFile;
            }
 
            private function invalidateFiles( arg:* = null ):void
            {
                if( _invokedFile == null ) return;
                if( _fileWindow == null || _fileWindow.closed ) openFileWindow();
                else applyFileToWindow();
            }
 
            [Bindable]
            public function get invokedFile():File
            {
                return _invokedFile;
            }
            public function set invokedFile( arr:File ):void
            {
                _invokedFile = arr;
            }
 
        ]]>
    <mx :Label text="Welcome" />
</mx>

Note:
Again i apologize for the terrible representation of mxml code. To view the full code, click here

On dispatch of ‘applicationComplete’, a ChangeWatcher instance is created to bind any changes to the invokeFile attribute to the invalidateFiles() method. The invalidateFiles() method will be called upon a change to the invokedFile which is of type File from the AIR API. The client that handles any invoked files in this case is another addition to the AIR API – Window. I threw it in there because i can’t stop wanting to use it

The invalidateFiles() has checks to see if the file is valid as well as to make sure the Window is open and ready to receive data. Basically, with binding a change to the invokedFile attribute to the invalidateFiles() handler, we can be sure that when a file is requested to be open – either through invocation from the command, double-click, or ‘open with’ – the Window client that knows how to handle that file data will be presented.

This just scratches the surface. There are icons you can associate with file types, there’s drag and drop capabilities that can update the invoked file if wanted… i just have to stop typing at some point!

View the full source code here. I didn’t offer up the air app to download because it’s a rather boring app, but it is included in the source if you want to install it and test out the invocation.

If you made it this far and haven’t checked out AIR, go download the bits. And maybe consider buying a book or two…

I’ve been fortunate enough to work alongside Marc and Matt to produce a ‘by example’ book on AIR that we hope people will enjoy reading as much as we have writing it. Matt took the words out of my mouth, but with any new technology there is always the jazz of it’s potential and then the questioning of its practicality. I can say for certain, after having worked with it for the past several months, that AIR is the next generation in desktop software development.

The Wrox Instant Results series walks you through building applications while learning the platform API, and this is no different. We have assembled a dozen examples that you can walk away from and use as well as expand upon. As the book progesses, you build on your knowledge from previous chapters and learn new aspects of the API. With a general knowledge of Flex and basic understanding of OOP, anyone can jump into this book and take off running with their own ideas.

Also available from Wiley Wrox is Professional AIR by the esteemed Chuck Freedman, mister Keith Peters, Clint Modien, Ben Lucyk, and Ryan Manning.

Wrox AIR Instant Results

I don’t pretend to know enough about the architecture (so someone speak up if i am off track), but adding components to NativeWindows – without Daniel’s or the proceeding example- fails due to the reference to your main ApolloApplication’s stage when displaying components within the Flex framework. You can add all the displays existent in the AS3 library (Sprite, TextField, etc.) to the stage of your NativeWindow instance, but any in the Flex framework need a little push. Adding MXML components to your NativeWindows will still have to follow the formula Daniel laid out using the addChild/removeChild methods, yet there is a workaround to this for ActionScript components by adding an ADDED_TO_STAGE event listener within its constructor.

I have a tendency to try and word things right and it comes out all mush, so i’ll just show some code. You can alternatively look at source view.

The CustomLabel (CustomLabel.as) component that will be added to our NativeWindow:

        import flash.events.Event;
	import flash.text.TextField;
 
	import mx.containers.Canvas;
 
	public class CustomLabel extends Canvas
	{
		private var _label:TextField;
 
		public function CustomLabel()
		{
			super();
			addEventListener( Event.ADDED_TO_STAGE, init );
		}
 
		private function init( evt:Event ):void
		{
			createChildren();
		}
 
		override protected function createChildren():void
		{
			super.createChildren();
 
			_label = createField( "HelloWorld" );
			stage.addChild( _label );
		}
 
		override protected function updateDisplayList( unscaledWidth:Number, unscaledHeight:Number ):void
		{
			super.updateDisplayList( unscaledWidth, unscaledHeight );
		}
 
		private function createField( txt:String = "" ):TextField
		{
			var label:TextField = new TextField();
			label.text = txt;
			return label;	
		}
	}

… And the main mxml (NativeWindowExample.mxml):

<mx :ApolloApplication 
	xmlns:mx="http://www.adobe.com/2006/mxml"
	width="200"
	height="100" 
	layout="absolute"
	applicationComplete="onAppInit();">
 
	</mx><mx :Script>
		< ![CDATA[
 
			private var _launchWindow:NativeWindow;
			private var _customWindow:NativeWindow;
 
			private function onAppInit():void
			{
				_launchWindow = this.stage.window;
				_launchWindow.addEventListener( Event.CLOSE, onAppClose );
			}
 
			private function openCustomWindow( evt:MouseEvent ):void
			{
				if( _customWindow != null ) return;
 
				var options:NativeWindowInitOptions = new NativeWindowInitOptions();
				_customWindow = new NativeWindow( true, options );
				_customWindow.stage.align = StageAlign.TOP_LEFT;
				_customWindow.stage.scaleMode = StageScaleMode.NO_SCALE;
				_customWindow.title = "CustomWindow";
				_customWindow.stage.addChild( new CustomLabel() );
				_customWindow.addEventListener( Event.CLOSE, onWindowClose );
			}
 
			private function onWindowClose( evt:Event ):void
			{
				_customWindow = null;
			}
 
			private function onAppClose( evt:Event ):void
			{
				if( _customWindow != null ) _customWindow.close();
			}
 
		]]>
	</mx>
 
	<mx :Button id="windowBtn" 
		top="10" left="10" right="10" bottom="10"
		label="open custom window"
		click="openCustomWindow( event );">
	</mx>

NOTE: the preceding code has some major problems due to mx tags in wordpress, so disregard all affending close tags

— As well, you could extend NativeWindow and add the AS components to its stage to bypass adding them in the main app. –

In the main app file we are just creating a new NativeWindow instance and adding the custom AS component, CustomLabel, to it’s display.

_customWindow.stage.addChild( new CustomLabel() );

What is happening in the constructor of the CustomLabel is of importance in this example, as it listens for its event of being added to a clients stage. From there we can call the override of UIComponent:createChildren, and add whatever we want to the display. When creating AS components NOT to be added to the NativeWindow, that method (createChildren) would be called as long as you call the super constructor. That is not the case when adding components extending the Flex framework in NativeWindow. Again, if i am missing something crucial or if you have more insight, please leave a comment. So that’s it. Once it has been added to the stage, we can go about our business. Of course, when using ActionScript components you lose the inherent layout capabilities within MXML components, but that is why we’ve added the override of #updateDisplayList.
Until Flex came around, i know i spent more than my fair share nailing down layouts for applications- so this is like going back home…

To find out more about extending ActionScript components, visit this post on FlashGen and this doc from the labs.

PS. I’ve been a little lacking in the post area, and though i have the usual excuses- family, work, beer… – i could be more on top of it and you should be seeing more Flex and Apollo thoughts in the near future, but no promises because i love those excuses. I also am working on something that i hope to announce here a little later if all goes well…