ActionScript basics for JavaScript developers

ActionScript, like JavaScript, is based on the ECMAScript language specification; therefore, the two languages have a common core syntax. For example, the following code works the same in JavaScript and in ActionScript:

var str1 = "hello"; 
var str2 = " world."; 
var str = reverseString(str1 + str2); 
     
function reverseString(s) { 
    var newString = ""; 
    var i; 
    for (i = s.length - 1; i >= 0; i--) { 
        newString += s.charAt(i); 
    } 
    return newString; 
}

However, there are differences in the syntax and workings of the two languages. For example, the preceding code example can be written as the following in ActionScript 3.0 (in a SWF file):

function reverseString(s:String):String { 
    var newString:String = ""; 
    for (var i:int = s.length - 1; i >= 0; i--) { 
        newString += s.charAt(i); 
    } 
    return newString; 
}

The version of JavaScript supported in HTML content in Adobe AIR is JavaScript 1.7. The differences between JavaScript 1.7 and ActionScript 3.0 are described throughout this topic.

The runtime includes some built-in classes that provide advanced capabilities. At runtime, JavaScript in an HTML page can access those classes. The same runtime classes are available both to ActionScript (in a SWF file) and JavaScript (in an HTML file running in a browser). However, the current API documentation for these classes (which are not included in the Adobe AIR API Reference for HTML Developers ) describes them using ActionScript syntax. In other words, for some of the advanced capabilities of the runtime, refer to The Adobe ActionScript 3.0 Reference for the Adobe Flash Platform . Understanding the basics of ActionScript helps you understand how to use these runtime classes in JavaScript.

For example, the following JavaScript code plays sound from an MP3 file:

var file = air.File.userDirectory.resolve("My Music/test.mp3"); 
var sound = air.Sound(file); 
sound.play();

Each of these lines of code calls runtime functionality from JavaScript.

In a SWF file, ActionScript code can access these runtime capabilities as in the following code:

var file:File = File.userDirectory.resolve("My Music/test.mp3"); 
var sound = new Sound(file); 
sound.play();

ActionScript 3.0 is a strongly typed language. That means that you can assign a data type to a variable. For example, the first line of the previous example could be written as the following:

var str1:String = "hello";

Here, the str1 variable is declared to be of type String. All subsequent assignments to the str1 variable assign String values to the variable.

You can assign types to variables, parameters of functions, and return types of functions. Therefore, the function declaration in the previous example looks like the following in ActionScript:

function reverseString(s:String):String { 
       var newString:String = ""; 
       for (var i:int = s.length - 1; i >= 0; i--) { 
           newString += s.charAt(i); 
       } 
       return newString; 
}

Although assigning types is optional in ActionScript, there are advantages to declaring types for objects:

• Typed objects allow for type checking of data not only at run-time, but also at compile time if you use strict mode. Type checking at compile time helps identify errors. (Strict mode is a compiler option.)

• Using typed objects creates applications that are more efficient.

  For this reason, the examples in the ActionScript documentation use data types. Often, you can convert sample ActionScript code to JavaScript by simply removing the type declarations (such as " :String ").

function exampleFunction(n:*):* { 
       trace("hi, " + n); 
}

ActionScript 3.0 includes capabilities related to classes that are not found in JavaScript 1.7.

public class ExampleClass { 
    public var x:Number; 
    public function ExampleClass(input:Number):void { 
        x = input; 
    } 
    public function greet():void { 
        trace("The value of x is: ", x); 
    } 
}

flash.filesystem.File

var myFile = new air.flash.filesystem.File();

In both ActionScript 3.0 and JavaScript, functions can include parameters. In ActionScript 3.0, parameters can be required or optional; whereas in JavaScript, parameters are always optional.

The following ActionScript 3.0 code defines a function for which the one parameter, n , is required:

function cube(n:Number):Number { 
    return n*n*n; 
}

The following ActionScript 3.0 code defines a function for which the n parameter is required. It also includes the p parameter, which is optional, with a default value of 1:

function root(n:Number, p:Number = 1):Number { 
    return Math.pow(n, 1/p); 
}

An ActionScript 3.0 function can also receive any number of arguments, represented by ...rest syntax at the end of a list of parameters, as in the following:

function average(... args) : Number{ 
    var sum:Number = 0; 
    for (var i:int = 0; i < args.length; i++) { 
        sum += args[i]; 
    } 
    return (sum / args.length); 
}

In ActionScript 3.0 programming, all events are handled using event listeners . An event listener is a function. When an object dispatches an event, the event listener responds to the event. The event, which is an ActionScript object, is passed to the event listener as a parameter of the function. This use of event object differs from the DOM event model used in JavaScript.

For example, when you call the load() method of a Sound object (to load an mp3 file), the Sound object attempts to load the sound. Then the Sound object dispatches any of the following events:

Any class that can dispatch events either extends the EventDispatcher class or implements the IEventDispatcher interface. (An ActionScript 3.0 interface is a data type used to define a set of methods that a class can implement.) In each class listing for these classes in the ActionScript Language Reference, there is a list of events that the class can dispatch.

You can register an event listener function to handle any of these events, using the addEventListener() method of the object that dispatches the event. For example, in the case of a Sound object, you can register for the progress and complete events, as shown in the following ActionScript code:

var sound:Sound = new Sound(); 
var urlReq:URLRequest = new URLRequest("test.mp3"); 
sound.load(urlReq); 
sound.addEventListener(ProgressEvent.PROGRESS, progressHandler); 
sound.addEventListener(Event.COMPLETE, completeHandler); 
 
function progressHandler(progressEvent):void { 
      trace("Progress " + progressEvent.bytesTotal + " bytes out of " + progressEvent.bytesTotal); 
} 
 
function completeHandler(completeEvent):void { 
      trace("Sound loaded."); 
}

In HTML content running in AIR, you can register a JavaScript function as the event listener. The following code illustrates this. (This code assumes that the HTML document includes a TextArea object named progressTextArea .)

var sound = new runtime.flash.media.Sound(); 
var urlReq = new runtime.flash.net.URLRequest("test.mp3"); 
sound.load(urlReq); 
sound.addEventListener(runtime.flash.events.ProgressEvent.PROGRESS, progressHandler); 
sound.addEventListener(runtime.flash.events.Event.COMPLETE, completeHandler); 
 
function progressHandler(progressEvent) { 
      document.progressTextArea.value += "Progress " + progressEvent.bytesTotal + " bytes out of " + progressEvent.bytesTotal; 
} 
 
function completeHandler(completeEvent) { 
      document.progressTextArea.value += "Sound loaded.";