Developing Widgets for Chumby: ActionScript 3
Contents
Summary
This page highlights major differences while porting widgets for chumby from ActionScipt 2 to 3.
Older widgets (written and compiled as ActionScript 2 / Flash Player 8 or earlier) cannot simply be re-compiled as ActionScript 3 / Flash 9 or later. There are a few major syntax changes in ActionScript 3 that makes ActionScript 2 invalid.
Event Handling
AS3 employs a totally new event handling mechanism. All events handling in AS2 has to be ported.
AS2: moviecliploader.onLoad = some_function_name;
AS3: moviecliploader.addEventListener(Event.COMPLETE, some_function_name);
Event Dispatching
AS2 has to rely on MX library for dispatching events from child class to higher-order receiving class. AS3 has this mechanism built-in and made easy to use.
//Child class dispatching events import flash.events.Event; import flash.events.EventDispatcher; ... dispatchEvent(new Event("FireInTheHole"));
//Parent class receiving events myChild.addEventListener("FireInTheHole", some_function_name)
Note: child class must extend EventDispatcher class. MovieClip class already extend EventDispatcher.
Widget Environment
In AS2, widgets are passed a set of properties on the '_root' timeline about the Chumby such as its name, the current channel, the user (you), the music source, information about the clock, and so forth. 'root' syntax used to be valid anywhere in the code.
In AS3, it is somewhat replaced by 'root' syntax. However, it doesn't work the same way and the environment variables directly under 'root' no longer exist. 'root' is only valid when the code is written directly on the timeline or the class is inherited directly from MovieClip class.
AS2: _root._chumby_chumby_id
AS3: root.loaderInfo.parameters["_chumby_chumby_id"]
Stage
Similar to '_root' syntax, 'Stage' is replaced by 'stage' object. It is valid only when the code is written directly on the timeline or the class is inherited directly from MovieClip class.
Also, Stage.width & Stage.height are replaced by stage.stageWidth & stage.stageHeight.
workarounds for root & stage
There are two possible implementations to enable root & stage access anywhere in the code.
//Non-OOP implementation, dirty but fast! //Create a class to store static variables package com.chumby { import flash.display.Stage; public class AS3ChumbyGlobal extends Object { public static var stage:Stage; public static var root:Object; } } ... //Put this in the very first frame in the timeline import com.chumby.AS3ChumbyGlobal; AS3ChumbyGlobal.stage = stage; AS3ChumbyGlobal.root = root; ... //From there on, you can access root & stage anywhere with the following AS3ChumbyGlobal.stage = stage; AS3ChumbyGlobal.root = root;
//True OOP implementation //Pass root & stage from the timeline to your class instance's constructor //Your class package { import flash.display.Stage; public class MyCoolClass { private myStage:Stage; private myRoot:Object; public function MyCoolClass(stg:Stage, rt:Object) { myStage = stg; myRoot = rt; } ... function myCoolFunction():void { trace(myStage.stageWidth); trace(myRoot.loaderInfo.parameters["_chumby_chumby_id"]) } } }
Flash player type
In AS3, it is easy to check what is the type of Flash player is being used so that you can handle them differently.
import System.Capabilities; ... trace( System.Capabilities.playerType );
"PlugIn" - on a web browser's Flash plugin (web preview on chumby.com)
"External" - on PC's standalone player (while developing & debugging the widget)
"StandAlone" - on chumby device
XML
In AS3, XML class simplifies XML handling.
An example of constructing & sending a XML request is presented [Send_email_from_app here]
XML request
XML.sendAndLoad function in AS2 was retired in AS3. XML class itself no longer dispatches events upon loading. Events must be handled by the loader class (URLLoader)
//Example: load & receive an RSS Feed (which is in XML format) var myRSSLoader:URLLoader = new URLLoader(); myRSSLoader.addEventListener(Event.COMPLETE, rssLoaderComplete); myRSSLoader.load(new URLRequest( http_path_of_the_rss_feed )); function rssLoaderComplete(evt:Event):void { var myRawXML:XML = XML(evt.currentTarget.data); trace("RSS feed loaded. Number of articles: " + myRawXML.channel.item.length()); }
Note: myRawXML.channel.item - this the way of accessing XML elements in AS3. More information here
NULL/Undefined value
'undefined' syntax in AS2 can be directly replaced by 'null' in most case. There are a few exceptions.
String objects in AS3 is never 'null' and not comparable to an 'null' value. Instead, compare String objects with "" (empty string) value.
Object casting
AS3 uses stricter data type. Generic objects in Object type should be explicitly cast to their type before used as another type.
An example of using YouTube player 'object' is shown here:
var videoPlayer:Object; var videoContainer:MovieClip; var videoLoader:Loader; //load YouTube player here ... //when loading completes videoPlayer = videoLoader.content; //videoLoader.content is of Object type, no casting required videoPlayer.setVolume(100); //'unknown-at-compile-time' YouTube API function, no casting required videoContainer.addChild(videoPlayer as DisplayObject); //because addChild function requires a DisplayObject
String object cannot be assigned directly to a Number object. It must be parsed or cast properly
var myString:String = "123"; var myNumber:Number = 0; //myNumber = myString; //this is invalid myNumber = parseFloat( myString ); myNumber = parseInt( myString ); myNumber = Number(myString);
Double/Multiple inheritance
AS3 does support multiple inheritance.
For instance, MovieClip inherits DisplayObject, EventDispatcher and Sprite among other classes.
However, if a class instance is placed in the Library in Flash document (FLA), the class must extends MovieClip class directly.