ActionScript basics for JavaScript developers

Adobe® ActionScript® 3.0 is a programming language like JavaScript—both are based on ECMAScript. ActionScript 3.0 was released with Adobe® Flash® Player 9 and you can therefore develop rich Internet applications with it in Adobe® Flash® CS3 Professional, Adobe® Flash® CS4 Professional, and Adobe® Flex™ 3.

The current version of ActionScript 3.0 was available only when developing SWF content for Flash Player 9 in the browser. It is now also available for developing SWF content running in Adobe® AIR®.

The Adobe AIR API Reference for HTML Developers includes documentation for those classes that are useful in JavaScript code in an HTML-based application. It’s a subset of the entire set of classes in the runtime. Other classes in the runtime are useful in developing SWF-based applications (the DisplayObject class for example, which defines the structure of visual content). If you need to use these classes in JavaScript, refer to the following ActionScript documentation:

Differences between ActionScript and JavaScript: an overview

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 data types

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; 
}
Note: The s parameter and the return value of the function are both assigned the type String.

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 ").

Data types corresponding to custom classes

An ActionScript 3.0 object can have a data type that corresponds to the top-level classes, such as String, Number, or Date.

In ActionScript 3.0, you can define custom classes. Each custom class also defines a data type. This means that an ActionScript variable, function parameter, or function return can have a type annotation defined by that class. For more information, see Custom ActionScript 3.0 classes .

The void data type

The void data type is used as the return value for a function that, in fact, returns no value. (A function that does not include a return statement returns no value.)

The * data type

Use of the asterisk character (*) as a data type is the same as not assigning a data type. For example, the following function includes a parameter, n, and a return value that are both not given a data type:

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

Use of the * as a data type is not defining a data type at all. You use the asterisk in ActionScript 3.0 code to be explicit that no data type is defined.

ActionScript 3.0 classes, packages, and namespaces

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

Runtime classes

The runtime includes built-in classes, many of which are also included in standard JavaScript, such as the Array, Date, Math, and String classes (and others). However, the runtime also includes classes that are not found in standard JavaScript. These additional classes have various uses, from playing rich media (such as sounds) to interacting with sockets.

Most runtime classes are in the flash package, or one of the packages contained by the flash package. Packages are a means to organize ActionScript 3.0 classes (see ActionScript 3.0 packages .

Custom ActionScript 3.0 classes

ActionScript 3.0 allows developers to create their own custom classes. For example, the following code defines a custom class named ExampleClass:

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); 
    } 
}

This class has the following members:

  • A constructor method, ExampleClass() , which lets you instantiate new objects of the ExampleClass type.

  • A public property, x (of type Number), which you can get and set for objects of type ExampleClass.

  • A public method, greet() , which you can call on objects of type ExampleClass.

    In this example, the x property and the greet() method are in the public namespace. The public namespace makes methods and properties accessible from objects and classes outside the class.

ActionScript 3.0 packages

Packages provide the means to arrange ActionScript 3.0 classes. For example, many classes related to working with files and directories on the computer are included in the flash.filesystem package. In this case, flash is one package that contains another package, filesystem. And that package may contain other classes or packages. In fact, the flash.filesystem package contains the following classes: File, FileMode, and FileStream. To reference the File class in ActionScript, you can write the following:

flash.filesystem.File

Both built-in and custom classes can be arranged in packages.

When referencing an ActionScript package from JavaScript, use the special runtime object. For example, the following code instantiates a new ActionScript File object in JavaScript:

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

Here, the File() method is the constructor function corresponding to the class of the same name (File).

ActionScript 3.0 namespaces

In ActionScript 3.0, namespaces define the scope for which properties and functions in classes can be accessed.

Only those properties and methods in the public namespace are available in JavaScript.

For example, the File class (in the flash.filesystem package) includes public properties and methods, such as userDirectory and resolve() . Both are available as properties of a JavaScript variable that instantiates a File object (via the runtime.flash.filesystem.File() constructor method).

There are four predefined namespaces:

Namespace

Description

public

Any code that instantiates an object of a certain type can access the public properties and methods in the class that defines that type. Also, any code can access the public static properties and methods of a public class.

private

Properties and methods designated as private are only available to code within the class. They cannot be accessed as properties or methods of an object defined by that class. Properties and methods in the private namespace are not available in JavaScript.

protected

Properties and methods designated as protected are only available to code in the class definition and to classes that inherit that class. Properties and methods in the protected namespace are not available in JavaScript.

internal

Properties and methods designated as internal are available to any caller within the same package. Classes, properties, and methods belong to the internal namespace by default.

Additionally, custom classes can use other namespaces that are not available to JavaScript code.

Required parameters and default values in ActionScript 3.0 functions

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); 
}

ActionScript 3.0 event listeners

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:

Event

Description

complete

When the data has loaded successfully.

id3

When mp3 ID3 data is available.

ioError

When an input/output error occurs that causes a load operation to fail.

open

When the load operation starts.

progress

When data is received as a load operation progresses.

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.";

// Ethnio survey code removed