Developing Widgets for Chumby: ActionScript 3

=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 one class to another 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 quick! //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. Examples: trace(AS3ChumbyGlobal.stage.stageWidth); trace(AS3ChumbyGlobal.root.loaderInfo.parameters["_chumby_chumby_id"]);

//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 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 is retired and can be directly replaced by 'null' in most case. There are a few exceptions. Primitive objects in AS3, such as String and Number, are never 'null' and not comparable to an 'null' value. Instead, compare String objects with "" (empty string) value, and Number object must be compared with a valid numeric 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);    //or myNumber = myString as Number;

=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 Library in Flash document (FLA), the class must extends MovieClip class  directly .

=Sending email= See here Please contact Chumby to enable email permission on your widget.

=Widget parameters / Server parameters= The AppParams.as class allows your app to store/retrieve values from our server. It is ideal for storing app settings, user preferences, high scores, etc. (limited to 32 characters) See here