ActionScript basics for JavaScript developers
Back to: Apollo Documentation home page
| Contents |
|---|
Overview
ActionScript is a programming language available to both SWF content in the Apollo runtime. Previously, ActionScript 3.0 was only available only when developing SWF content for Flash Player 9 in the browser. It is now also available for developing SWF content running in Apollo.
ActionScript, like JavaScript, is based on the ECMAScript language specification, so the two languages have common core syntax.
For instance, the following code works the same in JavaScript as 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 difference in the syntax and workings of the two languages.
For example, the previous example could be written as the following in ActionScript 3.0 (in a SWF file):
function reverseString(s:String):String {
var newString:String = "";
for (var i:uint = s.length - 1; i >= 0; i--) {
newString += s.charAt(i);
}
return newString;
}
The version of JavaScript supported in HTML content in Apollo is JavaScript 1.7. The differences between JavaScript 1.7 and ActionScript 3.0 are described throughout this section.
The Apollo runtime includes a number of built-in classes that provide advanced capabilities. JavaScript in an HTML page can access these classes when the page is running in the Apollo runtime. The same runtime classes are available both ActionScript (in a SWF file) and JavaScript (in an HTML file running in a browser). However, the current API documentation for these classes describes them using ActionScript syntax, because many of these classes have existed in ActionScript for quite awhile. Understanding the basics of ActionScript will help you understand how to use these Apollo runtime classes in JavaScript.
For example, the following JavaScript code plays sound from an MP3 file:
var file = runtime.flash.filesystem.File.usersDirectory.resolve("My Music/test.mp3");
var sound = new runtime.flash.media.Sound(file);
sound.play();
Each of these lines of code calls Apollo runtime functionality from JavaScript.
var file:File = flash.filesystem.File.usersDirectory.resolve("My Music/test.mp3");
var sound = new flash.media.Sound(file);
sound.play();
In a SWF file, ActionScript code can access these runtime capabilities as in the following code:
For more detailed information on ActionScript 3.0, see the sections that follow, as well as these resources:
- Programming ActionScript 3.0
- The Apollo ActionScript 3.0 Language Reference.
The Common development tasks section of this documentation describes ActionScript APIs for Apollo.
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. So the function declaration in the previous example might look like the following in ActionScript:
function reverseString(s:String):String {
var newString:String = "";
for (var i:uint = s.length - 1; i >= 0; i--) {
newString += s.charAt(i);
}
return newString;
}
Note that 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 at not only at run-time, but also at compile time if you use strict mode, which 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
As we have seen, 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, as described in Custom ActionScript 3.0 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 that is defined by that class.
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).
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 really not defining a data type at all. You use this 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 a number of capabilities related to classes, and these are not found in JavaScript 1.7.
Runtime classes
The Apollo runtime includes a number of built-in classes. Many classes are also included in standard JavaScript, such as the Array, Date, Math, and String classes (and others). However, a number of other classes are not found in standard JavaScript. These have a variety of uses, from playing rich media (such as sounds) to interacting with sockets.
Most Apollo 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, and these are discussed in ActionScript 3.0 packages.
Custom ActionScript 3.0 classes
ActionScript 3.0 allows developers to create their own custom classes. For instance, 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. This makes them accessible from objects and classes outside of the class. For more information, see ActionScript 3.0 namespaces.
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 user's machine 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 apollo.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 a number of public properties and methods, such as userDirectory and resolve(). These are available as properties of a JavaScript variable that instantiates a File object (via the runtime.flash.filesystem.File() constructor method).
There are four pre-defined namespaces:
- 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. Again, these are not available to JavaScript code.
Required parameters and default values in ActionScript 3.0 functions
In both ActionScript 3.0 and JavaScript, functions may 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, and for which the p parameter 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:uint = 0; i < args.length; i++) {
sum += args[i];
}
return (sum / args.length);
}
ActionScript 3.0 event listeners
In ActionScript 3.0 programming, events (which are dispatched by asynchronous processes) 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.
For example, when you call the load() method of a Sound object (to load an MP3 file), the Sound object will attempt to load the sound and then dispatch any of the following events:
- 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 can be implemented by a class.) 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 Apollo, you can register a JavaScript function as the event listener, as shown in the following code (which 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.";
}
Back to: Apollo Documentation home page