Latest revision as of 21:59, 8 March 2011

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