Developing Widgets for Chumby: ActionScript 3

Summary

This page describes the development of widgets for chumby with ActionScipt 3. Widgets for the Chumby are developed for Adobe Flash Lite 4. FL4 has a feature-set based on desktop Flash Player 10.

Older widgets written and compiled as ActionScript 2 for Flash Player 8 or earlier cannot simply be re-compiled as ActionScript 3 or 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);

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 works. '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.

root & stage workarounds

There are two possible implementations to enable root & stage access anywhere in the code.\n

//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" widget is running in a brower's Flash plugin (web preview on chumby.com). "External" on PC's standalone player (while developing & debugging the widget) "StandAlone" on chumby device

Security

Security is stricter in AS3.

XML

In AS3, XML class simplifies XML handling.

XML request

XML.sendAndLoad function is retired in AS3. XML class itself no longer dispatches events upon loading. Events must be handled by the loader class (URLLoader) An example of sending a XML request is presented [Send_email_from_app here] 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 myXML:XML = XML(evt.currentTarget.data);
    trace("RSS feed loaded. Number of articles: " + myXML.channel.item.length());
}

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 use. An example of YouTube player 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);                              //YouTube API function, no casting required
videoContainer.addChild(videoPlayer as DisplayObject);   //because addChild function requires a DisplayObject