The factory is responsible for knowing how to create an instance of the module, and also provides access to certain properties of the module. It can get a little more complicated as the methods exposed by the factory become available at different stages of the load process, so you have to be careful not to try and retrieve information before it is available.

The factory is retrieved used by accessing the factory property of the IModuleInfo object, returned by ModuleManager.getModule (). For more information on this, see the previous post. The factory will be of type IFlexModuleFactory, which behind the scenes is implemented by mx.managers.SystemManager. You don’t really need to worry about this detail though, it’s enough to know about the two public methods exposed by the factory.

They are:

• IFlexModuleFactory.create – This is really the most important method, and provides the mechanism for creating an instance of your loaded module. When enough of the module has been downloaded for this method to be called, the IModuleInfo object will dispatch a ModuleEvent.READY event, and the public property IModuleInfo.ready will return true. The method allows you to optionally pass in one or more parameters, using the “…rest” mechanism. These parameters are passed to your module’s constructor. Calling this method will create a new instance of your module, and the new instace of the method will be returned. The return type is specified as Object, so you will need to manually cast the returned object to the correct type in order to work with it.
• IFlexModuleFactory.info – This module allows you to find out a bit of information about the module which is being loaded. When enough of the module has been downloaded for this method to be called, the IModuleInfo object will dispatch a ModuleEvent.SETUP event, and the public property IModuleInfo.setup will return true. The method returns an Object, containing a variety of name/value pairs providing bits of information about the module. Examples of the kind of information that can be contained in the object includes width, height, a list of mixins used by the module, a list of RSLs used by the modules, a list of fonts embedded within the module, and information about the modules Main class name. The method can be useful for finding out the module’s layout information before you create an instance of it and add it to the display list.

Just to mention a quick ‘gotcha’ that I encountered when first working with Modules… If you find that the call to IModuleData.factory.create for some reason returns null, or at some point in the process you get an Error #1009, most likely your module is using some classes which for some reason are not accessible once the SWFs have been compiled and optimised. A simple fix for this can be to reference the offending classes in some way in the main application to force them to be compiled. Common offenders are the ‘manager’ classes, for example DragManager, PopupManager and SystemManager.

]]> http://lowpitch.com/blog/iflexmodulefactory-create-and-examine-loaded-flex-modules/feed/ 1 http://lowpitch.com/blog/modulemanager-and-imoduleinfo-loading-flex-modules-dynamically/ http://lowpitch.com/blog/modulemanager-and-imoduleinfo-loading-flex-modules-dynamically/#comments Sat, 16 Aug 2008 23:51:12 +0000 lowpitch http://lowpitch.com/blog/?p=19 When you’re working with Flex Modules, most of the time the ModuleLoader component will be enough to get you up and running. It will quickly and easily let you load your Modules and add them to the display list, it’ll even dispatch an event to let you know when the Module is ready. Lovely stuff. It’s very similar to the SWFLoader component with some added Module-related goodness thrown in.

However, there may be times when the ModuleLoader component may not be appropriate for your needs, and you’ll have to get your hands dirty and get involved with the lower-level ModuleManager class. Some examples of when ModuleLoader might not be suitable include:

• Your Module is entirely non-visual, and therefore shouldn’t be added to the display list
• Performance is really important to your application, and the extra overhead of the ModuleLoader container is something you need to remove to try and speed things up. (ModuleLoader essentially wraps your Module’s content in an extra container, incurring a slight performance hit).
• You need greater control over how and when your modules are loaded and unloaded.

How does ModuleManager work?

ModuleManager maintains a map of modules, indexed by each module’s URL. Information about the module is stored as an object implementing IModuleInfo, and is retrieved by calling the ModuleManager.getModule method, passing in the module’s URL as the method’s only parameter. Once you’ve retrieved the IModuleInfo object, you can call its load method to starting loading in the module. While the module is loading, you can monitor the load progress using a variety of different events (of type ModuleEvent). Finally, when the module is loaded and available, you can create an instance of that module using someModuleInfo.factory.create ().

IModuleInfo in more detail

As mentioned above, ModuleManager maintains a mapping of URLs to modules. When you call ModuleManager’s static getModule method, it returns an object of type IModuleInfo. If you dig around within the ModuleManager class, you’ll see that this interface is implemented internally. It’s useful to know a little bit more about how you can interact with the ModuleInfo, what methods it exposes, and what events it dispatches.

There are four read-only public Boolean properties which offer information about the current state of the module. They can briefly be described:

• IModuleInfo.error – This’ll be true if there was an error during loaded. You’re also notified of such an error by the ModuleEvent.ERROR event.
• IModuleInfo.loaded – This will be true if you’ve previously called the IModuleInfo.load method. Note: It does not necessarily signify that the module has been loaded, just that the module load has begun.
• IModuleInfo.setup – When enough of the module has loaded to be able to call the factory.info () method, this flag will be true. When this point in the load has been reached, a ModuleEvent.SETUP event will be dispatched.
• IModuleInfo.ready – When enough of the module has been loaded for you to be able to instantiate an instance of the module using the factory.create () method, this flag will be true. At this stage, a ModuleEvent.READY event will be dispatched. This property will typically become true at some point after the IModuleInfo.setup becomes true.

There are some additional properties which can also be useful:

• IModuleInfo.url fairly obviously returns the URL associated with the IModuleInfo object. This could be useful if you’re using one event handler to listen out for the events from multiple modules – the event.currentTarget.url property could be used to identify which module had sent out the event.
• IModuleInfo.data is an object which you can use to associate data with a particular module. The data will be shared across all instances of a particular module, so this property comes in handy if you want to share state, or user information between multiple instances of the same dynamically loaded module.
• IModuleInfo.factory is pretty important. Once the the module is ‘ready’ (after the ModuleEvent.READY event has been dispatched, or when IModuleInfo.ready returns true), you can create an instance of your module by calling the IFlexModuleFactory.create method. Additionally, once the module has been ’setup’ (after ModuleEvent.SETUP has fired, or when IModuleInfo.setup returns true), you can query the IFlexModuleFactory.info method to find out a little more about the module that has been loaded.

Next we should look at some of the methods exposed by an IModuleInfo:

• IModuleInfo.load – This is the method you’ll call to start loading a module. You can optionally pass in information about the current ApplicationDomain and SecurityDomain if necessary. When the module is loading, events will be dispatched along the way as detailed below. Quite a nice feature here is that if the module has already been loaded, and you attempt to reload it, it’ll still dispatch the “setup” and “ready” events, meaning that you can use one set of event listener methods without needing to worry about whether the module is loading for the first time, or if it already exists in local memory. Snazzy…
• IModuleInfo.release – This method will release the current reference to the module. Internally, when this method is called, a reference counter will be decremented. If no references to the module exist after this method has been called, it will automatically be unloaded.
• IModuleInfo.unload – This triggers the unload of the module. It’s worth noting that if any references to the module exist, it will not be garbage collected. Also, calling this method won’t remove your module from the display list, you’ll have to do that too.

Lastly, let’s look at the events dispatched… All the events listed here are instances of ModuleEvent, and for some of the events you’ll be able to access information about the load progress through the event’s bytesLoaded and bytesTotal properties.

• ModuleEvent.ERROR – Rather obviously, this is dispatched when an error occurs during loading. This will also be indicated by the IModuleInfo.error property returning true.
• ModuleEvent.PROGRESS – This event is dispatched periodically during the load, giving you the chance to display a visual indication of load progress if you want. This is one of the events where the bytesLoaded and bytesTotal properties will be set.
• ModuleEvent.SETUP – This event is dispatched when enough of the module has downloaded for you to call the IModuleInfo.factory.info method. At this point, IModuleInfo.setup will also return true. This event does not allow you to access load progress through the bytesLoaded and bytesTotal properties.
• ModuleEvent.READY – This event is dispatched when enough of the module has downloaded for you to create an instance of the module through the IModuleInfo.factory.create method. From then on, IModuleInfo.ready will also return true. Apparently, this event is one where the bytesLoaded and bytesTotal properties should be set, although I’ve noticed that this isn’t always the case. I reckon it’s safer just to use the ModuleEvent.PROGRESS information for displaying progress information.
• ModuleEvent.UNLOAD – This event is dispatched when the module has been unloaded. No progress information is available through the event object with this event.

A simple example

First, a basic module, SimpleModule, which does nothing more than display a label within a panel.

SimpleModule.mxml
<?xml version="1.0" encoding="utf-8"?>
<mx:Module xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute">
    <mx:TitleWindow x="10" y="10" width="120" height="100" layout="absolute">
        <mx:Text text="SimpleModule!" />
    </mx:TitleWindow>
</mx:Module>

The the main application, which will load in this module and attach instances to a Tile control.

Shell.mxml
<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
    applicationComplete="initApp()">
    <mx:Script>
        <![CDATA[
            import mx.modules.Module;
            import mx.events.ModuleEvent;
            import mx.modules.ModuleManager;
            import mx.modules.IModuleInfo;
 
          protected var _moduleInfo:IModuleInfo;
            
            private function initApp():void {
               addToLog ("Application initialised");
               // create the module - note, we're not loading it yet
                _moduleInfo = ModuleManager.getModule("SimpleModule.swf");
               // add some listeners
               _moduleInfo.addEventListener(ModuleEvent.READY, onModuleReady);
               _moduleInfo.addEventListener(ModuleEvent.SETUP, onModuleSetup);
               _moduleInfo.addEventListener(ModuleEvent.UNLOAD, onModuleUnload);
               _moduleInfo.addEventListener(ModuleEvent.PROGRESS, onModuleProgress);
            }
           
            protected function getModuleInfo () : IModuleInfo {
               // return the module info
               return _moduleInfo;
            }
           
            /**
             * Adds output to the log
             **/
            protected function addToLog (msg:String) : void {
                log.text += msg + "\n";
                // scroll to the bottom on the next frame
                callLater(scrollToBottom);
               
            }
           
            protected function scrollToBottom () : void {
                // scroll to the bottom
                log.verticalScrollPosition = log.maxVerticalScrollPosition;
            }
           
            /**
            * Called when the "load" button is pressed
            *
            * Starts loading the module - when the module has been
            * loaded, an instance of the module will be created
            * and added to the tile control
            *
            **/
            private function loadModule () : void {
                addToLog ("Loading module");
                // load the module
                getModuleInfo().load();
            }
   
            /**
             * Called when the "unload" button is pressed
             *
             * Removes all the instances of the module from the
             * tile control, then unloads the module
             *
             */
            private function unloadModule () : void {
                addToLog ("Unloading module");
                // clear out all the the instances
                // of the module from the tile
                tile.removeAllChildren();
                // unload the module
                getModuleInfo().release();
                //getModuleInfo().un
            }
            
            /**
            * Handler for the ModuleEvent.PROGRESS event
            **/
            protected function onModuleProgress (e:ModuleEvent) : void {
                addToLog ("ModuleEvent.PROGRESS received: " + e.bytesLoaded + " of " + e.bytesTotal + " loaded.");
            }
            
            /**
            * Handler for the ModuleEvent.SETUP event
            **/
            private function onModuleSetup (e:ModuleEvent) : void {
                addToLog ("ModuleEvent.SETUP received");
                // cast the currentTarget
                var moduleInfo:IModuleInfo = e.currentTarget as IModuleInfo;
                addToLog ("Calling IModuleInfo.factory.info ()");
                // grab the info and display information about it
                var info:Object = moduleInfo.factory.info();
                for (var each:String in info) {
                    addToLog ("     " + each + " = " + info[each]);
                }
               
            }
            
            /**
            * Handler for the ModuleEvent.READY event
            **/
            private function onModuleReady (e:ModuleEvent):void {
                addToLog ("ModuleEvent.READY received");
                // cast the currentTarget
                var moduleInfo:IModuleInfo = e.currentTarget as IModuleInfo;
                // Add an instance of the module's class to the
                // display list.
                addToLog ("Calling IModuleInfo.factory.create ()");
                tile.addChild( moduleInfo.factory.create () as SomeModule);
                addToLog ("SomeModule instance created and added to Display List");
            }
            
            /**
            * Handler for the ModuleEvent.UNLOAD event
            **/
            public function onModuleUnload (e:ModuleEvent) : void {
                addToLog ("ModuleEvent.UNLOAD received");
            }
            
        ]]>
    </mx:Script>
   
    <mx:HBox width="100%" height="100%">
        <mx:Tile id="tile" width="100%" height="100%" />
           <mx:TextArea id="log" width="100%" height="100%"/>
    </mx:HBox>
   
   
    <mx:ApplicationControlBar>
        <mx:Button label="Load" click="loadModule ()" />
        <mx:Button label="Unload" click="unloadModule ()"/>
    </mx:ApplicationControlBar>
   
</mx:Application>

What’s going on here? Well… when the app is created, initApp is called and the IModuleInfo object is created, and various event listeners are setup. When the user clicks the load button, the module is loaded. It doesn’t matter whether this is the first time the module is loaded, or if the module is already loaded and ready, the ModuleEvent.READY event will be dispatched to let us know that the module is ready, and that we can now create an instance of it. Within the handler for the ModuleEvent.READY event, we call IModuleInfo.factory.create () and add the instance of the module to our Tile control.

When the user clicks the unload button, all instances of the Module that we’ve added to the Tile control are removed, and we call IModuleInfo.unload to unload the module. A log message from within the handler for ModuleEvent.UNLOAD demonstrates that this is happening.

Additionally, within the event handler for ModuleEvent.SETUP we show an example of the IModuleInfo.factory.info method – this’ll give you an example of the kind of information you can retrieve about the module, and from looking at the log messages you’ll be able to see the order in which these events are dispatched.

Lastly, here’s the finished example:

[kml_flashembed movie="/blog/bin/modulemanager/Shell.swf" height="400" width="600" /]

 

(Update: I’ve explained the IFlexModuleFactory class in a little more detail here.)

]]> http://lowpitch.com/blog/modulemanager-and-imoduleinfo-loading-flex-modules-dynamically/feed/ 8 http://lowpitch.com/blog/nativewindow-using-air-windows-with-actionscript-part-3-of-3/ http://lowpitch.com/blog/nativewindow-using-air-windows-with-actionscript-part-3-of-3/#comments Sun, 10 Aug 2008 14:58:35 +0000 lowpitch http://lowpitch.com/blog/?p=17 In the first part of this post I covered each public property exposed by an instance of NativeWindow, before continuing to look at each public method in part two. In this final part of the series I’ll go through each of the different events dispatched by a NativeWindow during its lifetime.

Event.ACTIVATE

This event is sent out when the window is activated. The event doesn’t go through a capture phase, and it won’t bubble up the Display List. Some examples of when your window may dispatch this event include:

• When the NativeWindow is first created and activated
• When your application contains multiple NativeWindows and the user clicks on a window which previously was not the active window, giving it focus and bringing it to the front, the window will dispatch Event.ACTIVATE
• When you switch to another running application elsewhere on the system (an AIR application, or otherwise) and then switch back to this window, the event will be dispatched

Event.DEACTIVATE

Similarly, this event is sent out when the window is deactivated. Again, the event doesn’t go through a capture phase, and it won’t bubble up the Display List. Some examples of when your window may dispatch this event include:

• When your application contains multiple NativeWindows and the user clicks on a window which previously was not the active window, giving it focus and bringing it to the front, the window which previously was active and had the focus will dispatch Event.DEACTIVATE
• When you switch to another running application elsewhere on the system (an AIR application, or otherwise), the previously active window will dispatch this event

Event.CLOSING
Event.CLOSE

I have grouped these two events as they are rather obviously connected. If the user clicks the exit button in the system chrome, for example, the sequence of events will be:

• An Event.CLOSING event is dispatched.
• If this event is not cancelled (by calling the event’s preventDefault method) then the window will be closed, using NativeWindow.close () which was discussed in the previous part of this post
• Once the window has been closed, an Event.CLOSE event will be dispatched

As mentioned in the previous part of this series, if you want to implement your own “close” functionality, perhaps by creating your own application chrome, you should follow this same logic to give other objects elsewhere in your application a chance to cancel the closing operation if necessary.

NativeWindowDisplayStateEvent.DISPLAY_STATE_CHANGING
NativeWindowDisplayStateEvent.DISPLAY_STATE_CHANGE

Again, these events are related in a similar way to Event.CLOSING and Event.CLOSE. The events are dispatched as part of one of the following operations:

• Maximizing a window which was previously un-maximized
• Minimizing a window which was previously un-minimized
• Restoring a window from a maximized or minimized state

Unlike Event.CLOSING / Event.CLOSE, these events are defined within a subclass of Event, suggesting that there may be some added goodies within the event object that we can examine. As expected, there are a couple of properties available to tell us a little more about what is happening – to be more precise, the event object will tell us the value of the current state, and the value of the state we are moving to.

This is information is available by examining the NativeWindowDisplayStateEvent.beforeDisplayState and NativeWindowDisplayStateEvent.afterDisplayState properties. Both properties will be a string, matching one of the constants defined in the NativeWindowDisplayState class. These are:

• NativeWindowDisplayState.MAXIMIZED
• NativeWindowDisplayState.MINIMIZED
• NativeWindowDisplayState.NORMAL

So, for example, when a user clicks the maximize button in the system chrome, the sequence of events will be:

• A NativeWindowDisplayStateEvent.DISPLAY_STATE_CHANGING event is dispatched.
• If this event is not cancelled (by calling the event’s preventDefault method) then the state change will continue
• Once the display state has updated, a NativeWindowDisplayStateEvent.DISPLAY_STATE_CHANGE event will be dispatched

NativeWindowBoundsEvent.MOVING
NativeWindowBoundsEvent.MOVE

These events are dispatched whenever the position of the window within the system desktop is moved. This could be for one of a number of reasons:

• A system-controlled move operation, for example the user dragging the window around with the system chrome
• If the window is maximized
• If the window is minimized
• If the window is restored from maximized, or minimized state
• If the window is moved programmatically, by setting the x, y, or bounds properties

Again, the events here are defined in a custom subclass of Event, and this time the hidden treasures available to use are the beforeBounds and afterBounds properties, which obviously tell the us the “old” and “new” positions (and sizes, if we’re interested) of the window.

The sequence of events which would happen as part of a move operation would be:

• A NativeWindowBoundsEvent.MOVING event is dispatched.
• If this event is not cancelled (by calling the event’s preventDefault method) then the move operation will continue
• Once the window has been moved, a NativeWindowBoundsEvent.MOVE event will be dispatched

It’s worth noting that when a window is being dragged around by the user, it will repeatedly go through this cycle, moving the window in small steps. If at any stage, one of the NativeWindowBoundsEvent.MOVING events is cancelled, the move operation will terminate. This includes moves triggered by the NativeWindow.startMove () method discussed in the previous part of the post.

NativeWindowBoundsEvent.RESIZING
NativeWindowBoundsEvent.RESIZE

The events listed here work similarly to those dispatched as part of the move operation, although this time they apply to resize operations. Resize operations may occur for one of a number of reasons:

• A system-controlled resize operation, for example the user resizing the window via the system resize handles
• If the window is maximized
• If the window is minimised
• If the window is restored from maximized, or minimized state
• If the window is resized programmatically, by setting the width, height or bounds properties

The event type is the same as with the move operation, giving us access to the “old” and “new” sizes of the window. The sequence of events works in the same way too:

• A NativeWindowBoundsEvent.RESIZING event is dispatched.
• If this event is not cancelled (by calling the event’s preventDefault method) then the resize operation will continue
• Once the window has been resized, a NativeWindowBoundsEvent.RESIZE event will be dispatched

Lastly, as with the move operation, when a window is being resized by the user, it will repeatedly go through this cycle, resizing the window in small steps. If at any stage, one of the NativeWindowBoundsEvent.RESIZING events is cancelled, the resize operation will terminate. This includes resizes triggered by the NativeWindow.startResize () method discussed in the previous part of the post.

That’s all of ‘em

So that’s all of the events covered now. You can see how to handle various different operations that will happen during the lifetime of your window. You can react to (and cancel, if you wish) moves, resizes and the closing of your window. Most importantly, if creating your own application chrome, or implementing your own close/resize/move functionality, you should try and keep these operations cancelable. It’ll make things much easier down the line if, for example, you want to stop the user closing the window before the save their work.

Conclusion

I’ve now gone through all of the properties, methods and events exposed by a NativeWindow. As you can see, the API is fairly thorough, but extremely simple to use. It makes it easy to create, move, resize, hide, and reorder your windows, and to control how your windows will look and behave. I will try and carry this all through into an example at some point, but for now I hope this explanation has been fairly useful. Gimme a shout if there’s anything I’ve missed……

]]> http://lowpitch.com/blog/nativewindow-using-air-windows-with-actionscript-part-3-of-3/feed/ 3 http://lowpitch.com/blog/nativewindow-using-air-windows-with-actionscript-part-2-of-3/ http://lowpitch.com/blog/nativewindow-using-air-windows-with-actionscript-part-2-of-3/#comments Sun, 10 Aug 2008 00:10:13 +0000 lowpitch http://lowpitch.com/blog/?p=16 In the previous post I listed the public properties exposed by an instance of NativeWindow. In this post, I’ll be going through NativeWindow’s public methods. The third and final part of this series will explain the Events dispatched by a NativeWindow during its lifetime.

Once a NativeWindow has been created, you can call methods to move, resize, reposition, activate and close the window. All these methods are fairly simple, with the odd gotcha thrown in for good measure. So, here’s a description of each of these methods…

NativeWindow.activate ()

Calling NativeWindow.activate () firstly sets the visible of the window to true. Next, the window is brought to the front. Lastly, the window is given keyboard and mouse focus. Typically, you’d call the activate method shortly after creating it.

NativeWindow.close ()

This method, rather obviously, closes the window. This has several implications… First of all, once a window has been closed, it cannot be re-opened. References to a window that has been closed will exist, but some methods and properties of that window will no longer be available, and if accessed an exception will be thrown. Any DisplayObjects that were within the window, and not referenced anywhere else, will be available for Garbage Collection.

If you just want to close a window temporarily, consider setting its visible to false.

One other thing to mention here… when you call NativeWindow.close () no event is dispatched to signify the window is about to close. A Close event is sent out after the window has been closed, but if you want the action of closing the window to be preventable, you’ll need to send out a Closing event (take a look at air.Event.CLOSING which is more than suitable) giving interested parties a chance to set preventDefault on that event. If , and only if, the isDefaultPrevented () method of your custom Closing event returns false, then you can proceed to close your window.

NativeWindow.globalToScreen (globalPoint:Point)

This method is kind of like MovieClip.localToGlobal from days gone by, but takes things one step further. The method takes a Point object, representing co-ordinates relative to the origin of the NativeWindow’s stage and converts it to a Point object representing the same position relative to the top-left position of the system’s desktop.

NativeWindow.maximize ()
NativeWindow.minimize ()
NativeWindow.restore ()

This three methods are kind of similar, so I’ve grouped them here. The methods will attempt to maximize, minimize or restore the NativeWindow programmatically.

All three operations happen asynchronously, and you can detect the completion of these operations by listening out for a NativeWindowDisplayStateEvent.DISPLAY_STATE_CHANGE event.

Something important to note here, when the user tries to perform one of these three actions from the system chrome, a NativeWindowDisplayStateEvent.DISPLAY_STATE_CHANGING event is dispatched, giving interested parties a chance to cancel the operation (by calling preventDefault () ). To ensure this behaviour is also preventable when performing these options with code, you’ll need to manually dispatch a suitable DISPLAY_STATE_CHANGING event, and then investigate the event’s isDefaultPrevented () method before continuing the maximize / minimize / restore operation.

NativeWindow.notifyUser (type:String)

Assuming that NativeWindow.supportsNotification is true (see the previous post for more details), calling this method will trigger a visual cue to the user that something has happened. There are currently two different types of cue that you can trigger. NotificationType.INFORMATIONAL will trigger the cue for a short period of time, whereas NotificationType.CRITICAL will ensure the visial cue continues until the user brings focus to the window.

NativeWindow.orderInBackOf (window:NativeWindow)
NativeWindow.orderInFrontOf (window:NativeWindow)

These methods will move the window directly behind, or in front of, the window passed as the parameter. As always, some things to note.

• Attempting to re-order minimized or hidden windows is not possible.
• The methods will return true if the window was moved successfully, and false otherwise.
• If the window that you are moving behind, or in front of, has a different alwaysInFront property than the current window (see the previous post for more information), the window you are moving will have its alwaysInFront property changed to match this other window.
• When a window is reordered, it is not activated, and is not given the focus.

NativeWindow.orderToBack ()
NativeWindow.orderToFront ()

These methods will move the window behind, or in front of, all other visible windows. Things to note here include:

• Attempting to re-order minimized or hidden windows is not possible.
• The methods will return true if the window was moved successfully, and false otherwise.
• If the window’s alwaysInFront property is set to false, then calling orderToFront () will not move the window in front of any windows which have alwaysInFront set to true.
• Likewise, if the window’s alwaysInFront property is set to true then calling orderToBack () will not move the window behind any windows which have alwaysInFront set to false.

NativeWindow.startMove ()

Calling this method will trigger the start of a system-controlled move of the window. What this means is that you can create your own custom drag bar, listen to MouseEvent.MOUSE_DOWN events from that drag bar and then, in the event handler, call myNativeWindow.startMove () to begin the move process.

While the window is being moved, the window dispatches various events. This will be covered in more detail in the next part of this discussion. However, it’s worth mentioning here that a Move sequence can be terminated by handling, and then cancelling, the NativeWindowBoundsEvent.MOVING event.

The method returns true if the move process was successfully initiated, or false otherwise (for example, if the window was already maximized).

NativeWindow.startResize (edgeOrCorner:String)

This method is very similar to NativeWindow.startMove (). It allows you to create your own resize handles, listen to MouseMove.MOUSE_DOWN events from that resize handle, and then call myNativeWindow.startResize () from the event handler to begin the resize.

Again, while the window is being resized, it dispatches various events which will be covered in the next part of this discussion. As with moving a window, you can terminate the resize sequence by handling, then cancelling, the NativeWindowBoundsEvent.RESIZING event.

The method returns true if the resize process was successfully initiated, or false otherwise (for example, if the window was already maximized).

Unlike the startMove method, this method accepts a parameter. This parameter specifies which corner or edge of the window the resize should stem from. The possible values of this parameter are specified as constants in the NativeWindowResize class. The default is NativeWindowResize.BOTTOM_RIGHT.

That’s it!

That’s all of the public methods exposed by the NativeWindow class. You can see how to move, resize and re-order windows within the operating system, how to visually alert the user that the application needs their attention, how to activate the window, and how to close it. In the final part of this topic I’ll describe the various different Events that are dispatched by a NativeWindow during it’s lifetime.

Update: Part 3 of this post can be found here.

]]> http://lowpitch.com/blog/nativewindow-using-air-windows-with-actionscript-part-2-of-3/feed/ 0 http://lowpitch.com/blog/nativewindow-working-with-air-windows-with-actionscript-part-1-of-3/ http://lowpitch.com/blog/nativewindow-working-with-air-windows-with-actionscript-part-1-of-3/#comments Sat, 09 Aug 2008 18:06:56 +0000 lowpitch http://lowpitch.com/blog/?p=12 In a previous post I described how to create and activate an application window when creating an Actionscript AIR project in Flex Builder 3. I then went on to describe in a little more detail the various properties of the NativeWindowInitOptions class, and how setting some or all of these properties can affect the style and behaviour of the window that will be created. I guess the final step is to describe how to work with the window once it has been created, starting with an explanation of the flash.display.NativeWindow class. There’s quite a bit of functionality contained within the class, so I’ll break this post up into three. Part 1 will describe the properties of a NativeWindow, part 2 will list the public methods and finally part 3 will discuss the events dispatched by the Window throughout its lifetime.

As previously mentioned, an application window is created and displayed in Adobe AIR by creating a new instance of the NativeWindow class, and then calling this instance’s activate method. Content is added to the window by adding DisplayObjects to the stage property of the NativeWindow instance.

Here are descriptions of each of the NativeWindow’s public properties…

NativeWindow.active

Indicates whether or not a NativeWindow is the active application window or not. So for example, if your application has opened two windows, depending on which of those windows is currently being interacted with, one window’s active property will return true, and the other will return false. To activate a NativeWindow programmatically, you can call someNativeWindow.activate ().

NativeWindow.alwaysInFront

Rather obviously, this Boolean property will specify whether or not the window will always be on top of other windows (even those from other applications). For most situations, this property should be left as false unless the window needs to stay on top of other applications for a particular reason.

It’s possible to trigger certain behaviours by changing the value of this property. Setting this value from false to true will bring the window in front of all other application windows. Changing the value from true to false will send the window behind any other windows on the system with alwaysInFront set to true, but still on top of all other windows.

NativeWindow.bounds

This property, of type flash.geom.Rectangle, contains information about the position and size of the window including any system chrome. The fact that these dimensions include the system chrome is important. The size of the stage of the window (the area which is used for any content added to the stage), is equal to the size of the window minus the size of the chrome.

Setting the bounds property of a window is the same as setting it’s x, y, width, and height properties all in one step.

If you attempt to set the size of the window to an illegal size (for example, smaller than the minSize property, larger than the maxSize property, or larger or smaller than the limits imposed by the OS) then the window will be sized to the nearest acceptable value. This applies when setting the size of the window through the bounds property, and also when setting the width or height directly.

This property will be revisited in part 3 of this post when Events dispatched by the window will be discussed.

NativeWindow.closed

This Boolean indicates whether or not the window has been closed. Attempting to access certain properties or methods of a window which has been closed will cause an IllegalOperationError to be the thrown.

NativeWindow.displayState

This property is a string, and describes the window’s current display state. The possible values of this property are fairly self explanatory:

• NativeWindowDisplayState.NORMAL
• NativeWindowDisplayState.MINIMIZED
• NativeWindowDisplayState.MAXIMIZED

NativeWindow.height

The height of the window including any system chrome. To access the height of the usable area within the system chrome, use stage.stageHeight.

NativeWindow.maximizable

This Boolean tells us whether or not the window is maximizable. The value is set using the NativeWindowInitOptions instance, passed to the constructor, and cannot be modified once the window has been created.

NativeWindow.maxSize

This property, of type flash.geom.Point (Point.x corresponds to the width, Point.y corresponds to the height), allows us to specify the maximum size of the window. This maximum size is enforced when resizing is triggered both by Actionscript, or by the user clicking the OS maximize button.

NativeWindow.menu

This property allows us to create a flash.display.NativeMenu to be displayed for the Window. Note, for the menu to be displayed, NativeWindow.supportsMenu must be set to true, and NativeWindow.systemChrome must not be set to NativeWindowSystemChrome.NONE.

NativeWindow.minimizable

This Boolean tells us whether or not the window is minimizable. The value is set using the NativeWindowInitOptions instance, passed to the constructor, and cannot be modified once the window has been created.

NativeWindow.minSize

This property, of type flash.geom.Point, allows us to specify the minimum size of the window. This minimum size is enforced when resizing is triggered either by Actionscript, or by the user clicking the OS maximize button.

NativeWindow.resizable

This Boolean tells us whether or not the window is resizable. The value is set using the NativeWindowInitOptions instance, passed to the constructor, and cannot be modified once the window has been created.

NativeWindow.stage

This property gives us read-only access to the flash.display.Stage object at the root of this window’s display list. For content to be displayed in the window, it must be added to the stage (or to a descendant of a DisplayObject already added to the stage).

NativeWindow.supportsMenu

Setting this Boolean to true allows us to display a NativeMenu for this window by setting the menu property (see above). For the menu to be displayed, the systemChrome property must not be set to NativeWindowSystemChrome.NONE.

NativeWindow.supportsNotification

You know how sometimes an application can flash in some way to show you that something has happened? On Windows, the window’s entry in the task bar might flash, or on OS X the icon in the dock might jump around a bit. This property tells you whether or not this functionality is supported on the system on which your application is running. If this property is true, you can trigger this visual cue with the window’s notifyUser method.

NativeWindow.supportsTransparency

This Boolean property tells us whether or not transparency of windows is supported in the current environment. If the transparent property of the window is set to true, and supportsTransparency is also true, then your transparent window will work as expected. If, however, supportsTransparency is false, the your transparent window will not render correctly. Any pixels intended to have an alpha of 0 will be rendered as black. It’s also worth noting that this value may change during the lifetime of your window, for example if a user updates a preference setting.

NativeWindow.systemChrome

This read-only property tells us what system chrome is employed by the window. The property will match one of the constants defined in the NativeWindowSystemChrome class. The systemChrome is originally specified in the NativeWindowInitOptions class which is passed to the NativeWindow constructor and cannot be altered once the window has been created.

NativeWindow.systemMaxSize

This read-only property lets us find out the maximum size of a window allowed by the operating system. It’s a flash.geom.Point object with Point.x representing the width, and Point.y representing the height.

NativeWindow.systemMinSize

Similarly, thisy property lets us find out the minimum size of a window allowed by the operating system. Again, it’s a flash.geom.Point object with Point.x representing the maximum width, and Point.y representing the maximum height.

NativeWindow.title

This property lets us set the window title. Assuming we are using system chrome, the title will be displayed in the title bar, and also in other OS-specific locations such as the Windows taskbar.

NativeWindow.transparent

This Boolean tells us whether or not the window supports transparency. The value is set using the NativeWindowInitOptions instance, passed to the constructor, and cannot be modified once the window has been created. This property also relies upon the supportsTransparency property (see above) being equal to true.

NativeWindow.type

This read-only property tells us what window type setting was chosen when the window was created. The property will match one of the string constants defined in the NativeWindowType class. The type is originally specified in the NativeWindowInitOptions class which is passed to the NativeWindow constructor and cannot be altered once the window has been created.

NativeWindow.visible

This boolean allows us to control whether or not the window is visible. A window which is invisible will still be accessible, and all its methods and properties will still exist, it just will be hidden.

When a window is first created, it’s visible property will default to false. To show a window, you have to either call the activate method or set the visible property to true.

NativeWindow.width

The width of the window including any system chrome. To access the width of the usable area within the system chrome, use stage.stageWidth.

NativeWindow.x

This property is the horizontal co-ordinate of the window’s top left corner relative to the operating system’s desktop.

NativeWindow.y

This property is the vertical co-ordinate of the window’s top left corner relative to the operating system’s desktop. There are two ways to programmatically reposition a NativeWindow. Either set it’s x and y properties to new values, or set the bounds property as described above.

That’s it!

So that’s all the properties of the NativeWindow class – there’s quite a few of them, but there’s nothing too complicated in there. In the second part of this post I’ll list the public methods exposed by NativeWindow.

Update: Part 2 of this post can be found here.

]]> http://lowpitch.com/blog/nativewindow-working-with-air-windows-with-actionscript-part-1-of-3/feed/ 0 http://lowpitch.com/blog/nativewindowinitoptions-configure-your-air-nativewindow/ http://lowpitch.com/blog/nativewindowinitoptions-configure-your-air-nativewindow/#comments Wed, 06 Aug 2008 21:45:35 +0000 lowpitch http://lowpitch.com/blog/?p=13 In a previous post I listed some code to create and activate a NativeWindow in an Actionscript AIR project without really explaining what was going on behind the scenes. In this post, I’ll explain a little more about the NativeWindowInitOptions class, and how you can control the appearance and behaviour of the NativeWindow that you create.

The code I used in the previous post was this:

var windowOptions:NativeWindowInitOptions = new NativeWindowInitOptions();
var mainWindow:NativeWindow = new NativeWindow(windowOptions);

Fairly obviously, the NativeWindow constructor accepts an instance of NativeWindowInitOptions as its first parameter. In the previous example, I’m not doing anything fancy with the NativeWindowInitOptions instance that I create, I just create a new instance of the class and pass it to the NativeWindow constructor. As a result, all the various properties will have their default values, and the NativeWindow will be totally default. How terribly dull. Here’s a list of properties of NativeWindowInitOptions that you can play with to control how the NativeWindow will look and behave when it’s created….

NativeWindowInitOptions.minimizable

This is pretty obvious, but if the minimizable property is set to true then the NativeWindow will be minimizable. Otherwise, it won’t. This can have knock-on consequences on the appearance of the window. For example, when running on Windows, the value of this property can affect the window menu, and the window minimize button. If you don’t manually set this property, it will default to true.

NativeWindowInitOptions.maximizable

Again, if the maximizable property is set to true then the NativeWindow will be maximizable. This property may also affect the appearance of the window on some operating systems. This property also defaults to true.

NativeWindowInitOptions.resizable

The resizable property controls whether or not the window can be resized. When set to false, the little resize handles won’t appear in the corner of the window. Again, this property defaults to true.

(Note: When running on OS X, resizable and maximizable must both be set to false to prevent resizing. If you do one and not the other, it won’t work as expected).

NativeWindowInitOptions.systemChrome

The systemChrome property controls how the chrome of your NativeWindow will look. The default value is NativeWindowSystemChrome.STANDARD, and with this value the AIR application will adopt the look of a typical window in the operating system on which it’s running. So, when your AIR app runs on Windows, the chrome / menu bar / etc. will look like a typical Windows app. When the same app runs on OS X, it’ll look like a Mac app. The other possible value of this property is NativeWindowSystemChrome.NONE, which essentially hides the default system chrome, enabling you to create your own chrome for your NativeWindow.

NativeWindowInitOptions.transparent

This property, which defaults to false, determines whether or not the window supports transparency. If set to true, your window will be blended with the desktop beneath it. In other words, if you have content with an alpha of 0.5, your desktop will be visible through your window.

When this property is set to true, any areas of a window which do not contain a DisplayObject, or that only contain a DisplayObject with an alpha value under a certain threshold, will no longer react to mouse events. If a user clicks one of these “empty” areas, the mouse click will be handled by whatever happens to be sitting beneath your window, even though the click may have occurred within your application’s rectangle. The ‘threshold’ mentioned above varies between different operating systems but tends to fall between 0.05 and 0.01.

For those of you who may wish to create an application shaped like a clown’s face, this property is for you.
(Note: You can only set this property to false if you have also specified a value of NativeWindowSystemChrome.NONE for the systemChrome.)

NativeWindowInitOptions.type

There are currently three possible values for this property:

• NativeWindowType.NORMAL
  This is the default value for this property, and a NativeWindow of this type will use standard-sized chrome, and will also show up in the Windows taskbar or OS X window menu. Here is a screen shot of a very basic AIR window of this type running on OS X
  
  
  
• NativeWindowType.UTILITY
  A NativeWindow of this type still uses the system chrome, but in slimmed down form. Additionally, this type of window does not show up in the Windows taskbar or OS X window menu. Here is a screen shot of an AIR window of this type as a comparison.
  
  
  

  (Note: One thing I have noticed about windows of this type is that, on OS X at least, they are not minimizable by default. They are maximizable and resizable, but the minimize button is disabled)

• NativeWindowType.LIGHTWEIGHT
  A NativeWindow of this type has no system chrome, and in fact the value of the systemChrome mentioned above must be set to NativeWindowSystemChrome.NONE for this to work. An example of this type of window might be a notification message, similar to the one that pops up when you recieve a new IM in MSN Messenger, or a new email in Gmail Notifier.

These properties cannot be altered after the NativeWindow has been created

It is important to mention that each of these properties must be set on the NativeWindowInitOptions object before you attempt to create your NativeWindow. If you create your NativeWindow, passing the NativeWindowInitOptions object in as the parameter, and then subsequently attempt to alter the value of any of these properties, it will have no effect. Once the NativeWindow has been created, the properties mentioned above are set in stone.

Putting it all together

Finally, a code sample. The following snippet will create and activate a NativeWindow that supports transparency, has no chrome, is not maximizable, resizable or minimizable, and is of type NativeWindowType.UTILITY, meaning it will not be displayed in the Windows taskbar or OS X window menu. It then adds itself to the stage of the newly created window.

var windowOptions:NativeWindowInitOptions = new NativeWindowInitOptions ();
windowOptions.minimizable = false;
windowOptions.maximizable = false;
windowOptions.resizable = false;
windowOptions.type = NativeWindowType.UTILITY;
windowOptions.systemChrome = NativeWindowSystemChrome.NONE;
windowOptions.transparent = true;
var nativeWindow:NativeWindow = new NativeWindow (windowOptions);
nativeWindow.activate();
nativeWindow.stage.addChild(this);

At some point soon I will try to write up the NativeWindow class in more detail, including listing the properties it offers, and the events that it dispatches.

]]> http://lowpitch.com/blog/nativewindowinitoptions-configure-your-air-nativewindow/feed/ 0 http://lowpitch.com/blog/creating-air-projects-with-actionscript/ http://lowpitch.com/blog/creating-air-projects-with-actionscript/#comments Mon, 04 Aug 2008 18:54:53 +0000 lowpitch http://lowpitch.com/blog/?p=7 If you’re using Flex Builder 3, and you want to create an Actionscript project which will eventually deploy as an AIR application, you’ll quickly find that this option isn’t available when using the Actionscript Project Wizard. There are plenty of posts out there detailing a workaround (for example, see here).

I followed the workaround steps and it seemed to work OK, but when I first published my application… nothing happened. A little icon appeared in my dock, mysteriously titled adl (which I’ve since discovered stands for the AIR debug launcher), but no windows of Flash-based goodness appeared anywhere. After much digging around, I came across this entry in the Adobe Bug System and found the answer buried away in the comments.

When I’d previously created Flex-based AIR projects, I hadn’t really appreciated that the Flex framework was handling all of the window-creating shenanigans on my behalf. Just by making my root MXML tag a WindowedApplication, instead of a “normal” Application, the main AIR window was being created and activated automatically. When you’re not using the Flex framework, you have to do this stuff yourself.

As it turns out, the two most important classes involved in this process are flash.display.NativeWindow and flash.display.NativeWindowInitOptions. A NativeWindow is essentially the window you see on your desktop when you run an AIR application. This includes the menu bar (if any) and the system chrome (if any).

To successfully create and launch a window in AIR, you’ll need to create and activate a NativeWindow object, and then add your Document class (or some Sprite, at least) to that Window’s stage, accessible through the NativeWindow’s stage property. The code will look something like…

// create an instance of NativeWindowInitOptions to pass to the NativeWindow constructor
var windowOptions:NativeWindowInitOptions = new NativeWindowInitOptions();
// create the window
var mainWindow:NativeWindow = new NativeWindow(windowOptions);
// activate the window
mainWindow.activate();
// adds "this" to the stage of the Window we have created
mainWindow.stage.addChild(this);

This code will create and activate an AIR window with default options, and add someSprite to the stage of that Window. From then on, you can continue with your code just as you would in a traditional Flash application and all will work as expected.

I’ll post more about the NativeWindow and NativeWindowInitOptions classes at some point soon….

(Update: Check out this post for more information about the NativeWindowInitOptions class)

]]> http://lowpitch.com/blog/creating-air-projects-with-actionscript/feed/ 0 http://lowpitch.com/blog/flash-plays-mp3s-back-at-double-speed-why/ http://lowpitch.com/blog/flash-plays-mp3s-back-at-double-speed-why/#comments Sun, 27 Jul 2008 10:06:59 +0000 lowpitch http://lowpitch.com/blog/?p=11 A colleague and I recently found some odd things happening with dynamically loaded audio in an elearning application we have been working on. The external MP3s seemed to be playing back at double speed, and as a result the audio was a hideously high-pitched mess. The weird thing was, this wasn’t happening on every machine. Some computers, including mine, would play the audio back fine but a couple of other people were reporting the same problem so we had to look into it. Bah.

After much fiddling, we reached the following conclusions:

• Flash seems unable to handle MP3s encoded with a variable bit rate (VBR)
• Flash seems unable to reliably handle MP3s which have a sample rate which is not 44,100 Hz, 22,050 Hz or 11,025 Hz.
• Additionally, it seems possible that there are certain bit rates which are also not handled well by Flash. We’ve tested files successfully at 40kbps, 80kps, 120kbps (and many other multiples of 40).

(Note: This was happening in an application built with Actionscript 2.0 for Flash Player 8. I haven’t had a chance as yet to see if the same problem occurs in SWFs running in AVM2)

While the problem of the audio playing at double speed did seem fairly hard to recreate, we did find another way of highlighting the problem. The JW Media Player is a popular, open-source MP3/FLV Player and can see be seen in-use all over the internet. From our tests, ‘incorrectly’ encoded MP3 files can also create a problem when played as part of a playlist in the JW Media Player. If the user is listening to one of these MP3s, and moves the seek bar somewhere between half-way and the end of the file, the Media Player incorrectly decides that the MP3 has finished, and automatically moves to the next item in the playlist. Without looking into the code in more detail, this kind of assumes that the information Flash is broadcasting about the MP3 (for example sample length, or current position.) is incorrect, which is causes the MP3 to finish prematurely. Re-encoding the audio to match the criteria listed above will always fix this problem.

(Note: Current versions of the free Audio editing software Audacity, used in tandem with the LAME MP3 encoder, do not allow you to choose the bitrate of the exported MP3. However, the Beta version of Audacity 1.3 does offer that functionality via the Options button in the Export Dialog. The Beta version of this software can currently be downloaded from http://audacity.sourceforge.net/download/.)

]]> http://lowpitch.com/blog/flash-plays-mp3s-back-at-double-speed-why/feed/ 0 http://lowpitch.com/blog/xml-rpc-in-actionscript-30-couple-of-gotchas/ http://lowpitch.com/blog/xml-rpc-in-actionscript-30-couple-of-gotchas/#comments Fri, 25 Jul 2008 21:09:35 +0000 lowpitch http://lowpitch.com/blog/?p=6 As part a recent project, I’ve needed to integrate a Flex 3 application with an existing XML-RPC webservice. Over the years I’ve not done a huge amount of webservice integration with Flash. In the past I would typically choose to send data back and forth from the server using the built in XML or LoadVars objects available in Actionscript 2.0. On a couple of projects, I ended up using the Flash Remoting API and AMFPHP to achieve what I wanted and everything turned out pretty well, and once I integrated an application with some .NET SOAP webservices. But XML-RPC was a new one on me.

Anyway, after a bit of research, I was a little surprised to discover that XML-RPC hasn’t already been supported by the Flex framework, but after looking around I came across as3-rpclib, an open-source library that not only supports XML-RPC, but also AMF0 and JSON-RPC (I’ve currently only used these classes with XML-RPC, so can’t comment on the other formats implements).

So far, the classes have worked really well for me. However I did hit a couple of stumbling blocks along the way which I’ll attempt to detail here.

Information stored in AsyncToken is lost when onResult is sent out
When a service method is invoked using myXMLObject.call (), an instance of AysncToken is returned. A responder can then added to the token, so that when the result is returned from the webservice, the appropriate result or fault hander is called. AsyncToken is a dynamic class, meaning that new properties can be assigned to the instance at runtime without an Exception being thrown. Because of the dynamic nature of the class, it’s fairly common to set a dynamic property of the token which identifies which particular method call was invoked. Something like:

myToken = xmlrpc.call ("someMethod");
myToken.methodName = "someMethod";

This lets us use one result handler for multiple method calls. Within our result handler we can then examine the token associated with the event, and “switch” based on the methodName property of the token. The code would look something like:

protected function onResult (event: ResultEvent) : void {
    var token:AsyncToken = event.token;
    switch (token.methodName) {
        case "someMethodName":
            doSomething ();
        break;
        default:
            doSomethingElse ();
        break;
    }
}

I’ve since refactored my code not to use this particular way of handling webservice results, but initially I was using something very similar to the above. However, when I tried this with the as3-xmlrpc library, it didn’t work. token.methodName was always null. After much digging around, I discovered it was a bug in the library code. I’ve raised it as an issue on the Google Code site, but until this issue is patched, here’s a fix. The changes need to be made in the file found at com.ak33m.rpc.xmlrpc.XMLRPCObject, in the onResult method, beginning at line #139.

Existing code:


var token:AsyncToken = evt.target.token;
var resultevent:ResultEvent = ResultEvent(evt.data);

A new ResultEvent is created, which is dispatched later on in the method. However, the token is never set on this new ResultEvent, and so when we examine it in our onResult handler elsewhere, it doesn’t contain the data that we expect. We can fix this by changing the code to:


var token:AsyncToken = evt.target.token;
var currentRE:ResultEvent = ResultEvent (evt.data);
var resultevent:ResultEvent = new ResultEvent (currentRE.type,currentRE.bubbles, currentRE.cancelable, currentRE.result, token);

This will create a new ResultEvent, preserving our token, and our code will now work as expected.

How to send parameters using the ’struct’ datatype
Some of the methods exposed by the webservice I was using required a parameter of type ’struct’. Initially, I couldn’t work out how the hell I could force the Value Objects I was passing to my method calls to be serialised as structs, and as a result any calls I made to the webservice were constantly refused. Eventually I came across the interface com.ak33m.rpc.xmlrpc.IXMLRPCStruct.


package com.ak33m.rpc.xmlrpc
{
    public interface IXMLRPCStruct
    {
        function getPropertyData ():*;
    }
}

When I changed my Value Object to implement this Interface, and correctly implemented the getPropertyData method, the calls to my webservice methods began to work.

(Note: I have since discovered that the getting the latest version of the library from SVN renders this particular issue irrelevant. In the SVN version of the code, the XMLRPCSerializer has been updated and will automatically convert Objects to structs. With this change, my webservice calls would have worked from the start. It’s definitely worth checking out the latest version of the code, as there are a couple of other issues which have been fixed too.)

]]> http://lowpitch.com/blog/xml-rpc-in-actionscript-30-couple-of-gotchas/feed/ 2 http://lowpitch.com/blog/puremvc-multicore-vs-standard-singlecore/ http://lowpitch.com/blog/puremvc-multicore-vs-standard-singlecore/#comments Wed, 23 Jul 2008 18:48:57 +0000 lowpitch http://lowpitch.com/blog/?p=5 I’ve recently started using the Actionscript 3.0 Multicore implementation of PureMVC in order to use the framework within a modular Flex application. At the time of writing, most of the PureMVC examples and tutorials online are relevant to the Standard, or Singlecore,  version of the framework.

In general, the methodology and syntax is indentical across both versions of the framework. There are, however, a couple of minor differences which are pretty important, as without understanding these little quirks, many of the sample applications built using the Singlecore implementation will break when ported to Multicore.

The Standard version of PureMVC uses Singletons to provide access to the framework’s core actors. Within the framework, access to the Facade, Model, View and Controller are all provided using a standard getInstance method. To allow multiple instances of the framework to co-exist, the Multicore version of the framework uses Multitons, and then access to the various actors is provided within the framework by passing a unique instance key to the getInstance methods. The idea is simple – each separate instance of the framework has its own unique key, and so multiple instances of the actors may co-exist without interfering with each other.

In both versions of the framework, all instances of subclasses of Notifier (this includes Mediator, Proxy, SimpleCommand and MacroCommand) provide an easy way of accessing the facade using the protected property, facade.

The Standard implementation achieves this by creating an instance variable, defined as follows:

protected var facade:IFacade = Facade.getInstance();

The Multicore implementation achieves this by providing an implicit getter, defined as follows:

protected function get facade():IFacade
{
    if ( multitonKey == null ) throw Error( MULTITON_MSG );
    return Facade.getInstance( multitonKey );
}

Obviously, if you are using the Multicore instance and your code tries to access the facade (for example, to register a new Proxy, or to send a Notification) before the multitonKey has been set, it will not work as expected, and an exception will be thrown. In particular, if you try and access the facade within the constructor of your Mediator or Proxy, it will fail, and you’ll see an Exception with the message “Error: multitonKey for this Notifier not yet initialized!“. How are you supposed to know when the value of the multitonKey has been set?

Digging around in the framework, it becomes clear that when a Mediator is registered with the View, or when a Proxy is registered with the Model, a couple of things happen. Firstly, Notifier’s initializeNotifier method is called, with the multitonKey passed as the only parameter. Secondly, a reference to the Proxy or Mediator is stored in the relevant proxyMap or mediatorMap. Finally, a call to the View or the Model’s onRegister is made.

As a result, it looks like there are a couple of prime candidates when it comes to deciding where to place any interactions with the facade that must occur when the Proxy or Mediator is first created. You can override the initializeNotifier method, using code similar to:

override public function initializeNotifier( key:String ):void
{
    super.initializeNotifier (key);
    // from here on, you can happily interact with the facade
    // your code can be placed here
}

or you can override the onRegister method, using code similar to:

override public function onRegister( ):void
{
    // from here on, you can happily interact with the facade
    // your code can be placed here
}

Personally, I prefer overriding onRegister, because it involves less typing (and therefore I’m less likely to bugger something up…).

So, now when looking at one of the popular PureMVC examples, originally written for the Standard version of the framework, it’s easy to see what would need to change if porting the application to the Multicore version. As an example, the Flex Login example contains a Mediator named LoginPanelMediator. Its constructor looks like:

public function LoginPanelMediator(viewComponent: LoginPanel)
{
    super(NAME, viewComponent);
    //
    // local reference to the LoginProxy
    _loginProxy = facade.retrieveProxy( LoginProxy.NAME ) as LoginProxy;
    //
    // listen to events dispatched by its view component
    loginPanel.addEventListener( LoginPanel.TRY_LOGIN, login );
}

We can see straight away that this would fail when ported to the Multicore version of the framework. During the constructor, the Mediator is trying to retrieve a proxy from the facade, but at this point the multitonKey will not have been set. We could refactor this class, resulting in a change to the constructor, and a newly created override of the onRegister function:

public function LoginPanelMediator(viewComponent: LoginPanel)
{
    super(NAME, viewComponent);

    // listen to events dispatched by its view component
    loginPanel.addEventListener( LoginPanel.TRY_LOGIN, login );

    // constructor no longer contains any references to the facade
}

override public function onRegister () : void
{
    // when this method is called, the multitonKey has been set,
    // so we can safely access the facade
    // local reference to the LoginProxy
    _loginProxy = facade.retrieveProxy( LoginProxy.NAME ) as LoginProxy;
}

The differences between the Multicore and Singlecore/Standard versions of the framework are really very minor, but it’s worth remembering to always move any interaction with the facade out of a Proxy or Mediator’s constructor.

]]> http://lowpitch.com/blog/puremvc-multicore-vs-standard-singlecore/feed/ 2