ActionScript 2.0 Language Reference

Global Functions

This section contains a set of built-in functions that are available in any part of a SWF file where ActionScript is used. These global functions cover a wide variety of common programming tasks such as working with data types (Boolean(), int(), and so on), producing debugging information (trace()), and communicating with Flash Player or the browser (fscommand()).

Array Function

Array() : Array
Array(numElements:Number) : Array
Array(element0:Object, [element1, element2, ...elementN]) : Array

Use Array() to create one of the following:

• An empty array
• An array with a specific length but whose elements have undefined values
• An array whose elements have specific values

Using this function is similar to creating an array with the Array constructor (see "Constructor for the Array class").

You can pass a number (numElements) or a list of elements containing one or more different types (element0, element1, ... elementN).

Parameters that can accept more than one data type are listed in the signature as type Object.

Returns
     Array — An array.

var myArray:Array = Array();
myArray.push(12);
trace(myArray); //traces 12
myArray[4] = 7;
trace(myArray); //traces 12,undefined,undefined,undefined,7

Usage 2: The following example creates an array of length 4 but with no elements defined:

var myArray:Array = Array(4);
trace(myArray.length);  // traces 4
trace(myArray); // traces undefined,undefined,undefined,undefined

Usage 3: The following example creates an array with three defined elements:

var myArray:Array = Array("firstElement", "secondElement", "thirdElement");
trace (myArray); // traces firstElement,secondElement,thirdElement
Unlike the Array class constructor, the Array() function does not use the keyword new .

See also
    Array class

asfunction Protocol

var myMP3:Sound = new Sound();
function playMP3(mp3:String) {
  myMP3.loadSound(mp3, true);
  myMP3.onLoad = function(success) {
    if (!success) {
      // code to handle errors here
    }
  };
}
this.createTextField("list_txt", this.getNextHighestDepth(), 0, 0, 200, 100);
list_txt.autoSize = true;
list_txt.html = true;
list_txt.multiline = true;
list_txt.htmlText = "<a href=\"asfunction:playMP3, track1.mp3\">Track 1</a><br>";
list_txt.htmlText += "<a href=\"asfunction:playMP3, track2.mp3\">Track 2</a><br>";

See also
    TextField.htmlText

Boolean Function

• If expression is a Boolean value, the return value is expression.
• If expression is a number, the return value is true if the number is not 0; otherwise the return value is false.

• In files published for Flash Player 6 and earlier, the string is first converted to a number. The value is true if the number is not 0, otherwise the return value is false.
• In files published for Flash Player 7 and later, the result is true if the string has a length greater than 0; the value is false for an empty string.

• If expression is undefined or NaN (not a number), the return value is false.
• If expression is a movie clip or an object, the return value is true.

Unlike the Boolean class constructor, the Boolean() function does not use the keyword new. Moreover, the Boolean class constructor initializes a Boolean object to false if no parameter is specified, while the Boolean() function returns undefined if no parameter is specified.

Returns
     Boolean — A Boolean value.

trace(Boolean(-1)); // output: true
trace(Boolean(0)); // output: false
trace(Boolean(1)); // output: true


trace(Boolean(true)); // output: true
trace(Boolean(false)); // output: false


trace(Boolean("true")); // output: true
trace(Boolean("false")); // output: true

trace(Boolean("Craiggers")); // output: true
trace(Boolean("")); // output: false

If files are published for Flash Player 6 and earlier, the results differ for three of the preceding examples:

trace(Boolean("true")); // output: false
trace(Boolean("false")); // output: false
trace(Boolean("Craiggers")); // output: false

This example shows a significant difference between use of the Boolean() function and the Boolean class. The Boolean() function creates a Boolean value, and the Boolean class creates a Boolean object. Boolean values are compared by value, and Boolean objects are compared by reference.

// Variables representing Boolean values are compared by value
var a:Boolean = Boolean("a"); // a is true
var b:Boolean = Boolean(1); // b is true
trace(a==b); // true

// Variables representing Boolean objects are compared by reference
var a:Boolean = new Boolean("a"); // a is true
var b:Boolean = new Boolean(1); // b is true
trace(a == b); // false 

See also
    Boolean class

call Function

Deprecated as of Flash Player 5 — This action was deprecated in favor of the function statement.

• If variables are not declared inside a block ({}) but the action list was executed with a call() action, the variables are local and expire at the end of the current list.
• If variables are not declared inside a block and the current action list was not executed with the call() action, the variables are interpreted as Timeline variables.

See also
    function statement, Function.call()

chr Function

Deprecated as of Flash Player 5 — This function was deprecated in favor of String.fromCharCode().

Returns
     String — The character value of the specified ASCII code.

See also
    String.fromCharCode()

clearInterval Function

function callback() {
    trace("interval called: "+getTimer()+" ms.");
}

var intervalID:Number = setInterval(callback, 1000);

You must clear the interval when you have finished using the function. Create a button called clearInt_btn and use the following ActionScript to clear setInterval():

clearInt_btn.onRelease = function(){
    clearInterval( intervalID );
    trace("cleared interval");
};

See also
    setInterval()

clearTimeout Function

See also
    setTimeout(), setInterval()

duplicateMovieClip Function

duplicateMovieClip(target:String, newname:String, depth:Number) : Void
duplicateMovieClip(target:MovieClip, newname:String, depth:Number) : Void

this.createEmptyMovieClip("img_mc", this.getNextHighestDepth());
img_mc.loadMovie("http://www.helpexamples.com/flash/images/image1.jpg");
duplicateMovieClip(img_mc, "newImg_mc", this.getNextHighestDepth());
newImg_mc._x = 200;
newImg_mc.loadMovie("http://www.helpexamples.com/flash/images/image1.jpg");

this.myButton_btn.onRelease = function(){
    removeMovieClip(newImg_mc);
};

See also
    removeMovieClip(), MovieClip.duplicateMovieClip(), MovieClip.removeMovieClip()

escape Function

Returns
     String — URL-encoded string.

var email:String = "someuser@somedomain.com";
trace(escape(email));

var redirectUrl:String = "http://www.somedomain.com?loggedin=true&username=Gus";
getURL("http://www.myothersite.com?returnurl="+ escape(redirectUrl));

See also
    unescape()

eval Function

eval(expression:Object) : Object
eval(expression:String) : Object

In Flash 4, eval() was used to simulate arrays; in Flash 5 or later, you should use the Array class to simulate arrays.

In Flash 4, you can also use eval() to dynamically set and retrieve the value of a variable or instance name. However, you can also do this with the array access operator ([]).

In Flash 5 or later, you cannot use eval() to dynamically set and retrieve the value of a variable or instance name, because you cannot useeval() on the left side of an equation. For example, replace the code

eval ("var" + i) = "first";

this["var"+i] = "first"

set ("var" + i, "first");

Returns
     Object — A value, reference to an object or movie clip, or undefined .

for (var i = 1; i <= 3; i++) {
    setProperty(eval("square"+i+"_mc"), _rotation, 5);
}

for (var i = 1; i <= 3; i++) {
    this["square"+i+"_mc"]._rotation = -5;
}

See also
    Array class, set variable

fscommand Function

The fscommand() function lets a SWF file communicate with a script in a web page. However, script access is controlled by the web page's allowScriptAccess setting. (You set this attribute in the HTML code that embeds the SWF file—for example, in the PARAM tag for Internet Explorer or the EMBED tag for Netscape. When allowScriptAccess is set to "never", a SWF file cannot access web page scripts. With Flash Player 7 and later, when allowScriptAccess is set to "always", a SWF file can always access web page scripts. When allowScriptAccess is set to "sameDomain", scripting is allowed only from SWF files that are in the same domain as the web page; scripting is always allowed with previous versions of Flash Player. If allowScriptAccess is not specified in an HTML page, the attribute is set by default to "sameDomain" for SWF files of version 8 and later, and to "always" for SWF files of version 7 and earlier.

Usage 1: To use fscommand() to send a message to Flash Player, you must use predefined commands and parameters. The following table shows the values that you can specify for the fscommand() function's command and parameters parameters. These values control SWF files that are playing in Flash Player, including projectors. (A projector is a SWF file saved in a format that can run as a stand-alone application—that is, without Flash Player.)

Availability:

• None of the commands described in the table are available in web players.
• All of the commands are available in stand-alone applications, such as projectors.
• Only allowscale and exec are available in test-movie players.

The exec command can contain only the characters A-Z, a-z, 0-9, period (.), and underscore (_). The exec command runs in the subdirectory fscommand only. In other words, if you use the exec command to call an application, the application must reside in a subdirectory named fscommand. The exec command works only from within a Flash projector file.

Usage 2: To use fscommand() to send a message to a scripting language such as JavaScript in a web browser, you can pass any two parameters in the command and parameters parameters. These parameters can be strings or expressions, and they are used in a JavaScript function that handles, or catches, the fscommand() function.

In a web browser, fscommand() calls the JavaScript function moviename_DoFScommand, which resides in the web page that contains the SWF file. For moviename, supply the name of the Flash object that you used for the NAMEattribute of the EMBED tag or the ID property of the OBJECT tag. If you assign the SWF file the name myMovie, the JavaScript function myMovie_DoFScommand is called.

In the web page that contains the SWF file, set the allowScriptAccess attribute to allow or deny the SWF file's ability to access the web page. (You set this attribute in the HTML code that embeds the SWF file—for example, in the PARAM tag for Internet Explorer or the EMBED tag for Netscape.) When allowScriptAccess is set to "never", outbound scripting always fails. When allowScriptAccess is set to "always", outbound scripting always succeeds. When it is set to "sameDomain", scripting is allowed only from SWF files that are in the same domain as the web page. If allowScriptAccess is not specified in a web page, it defaults to "sameDomain" for Flash Player 8, and to "always" for previous versions of Flash Player.

When using this function, consider the Flash Player security model. For Flash Player 8, the fscommand() function is not allowed if the calling SWF file is in the local-with-file-system or local-with-network sandbox and the containing HTML page is in an untrusted sandbox. For more information, see the following:

• Chapter 17, "Understanding Security," in Learning ActionScript 2.0 in Flash
• The Flash Player 8 Security white paper at http://www.macromedia.com/go/fp8_security
• The Flash Player 8 Security-Related API white paper at http://www.macromedia.com/go/fp8_security_apis

Usage 3: The fscommand() function can send messages to Macromedia Director. These messages are interpreted by Lingo (the Director scripting language) as strings, events, or executable Lingo code. If a message is a string or an event, you must write the Lingo code to receive the message from the fscommand() function and carry out an action in Director. For more information, see the Director Support Center at www.macromedia.com/support/director.

Usage 4: In VisualBasic, Visual C++, and other programs that can host ActiveX controls, fscommand() sends a VB event with two strings that can be handled in the environment's programming language. For more information, use the keywords "Flash method" to search the Flash Support Center at www.macromedia.com/support/flash.

Note: If you are publishing for Flash Player 8 or later, the ExternalInterface class provides better functionality for communication between JavaScript and ActionScript (Usage 2) and between ActionScript and VisualBasic, Visual C++, or other programs that can host ActiveX controls (Usage 4). You should continue to use fscommand() for sending messages to Flash Player (Usage 1) and Macromedia Director (Usage 3).

this.fullscreen_btn.onRelease = function() {
    fscommand("fullscreen", true);
};

this.unfullscreen_btn.onRelease = function() {
    fscommand("fullscreen", false);
};

function myDocument_DoFSCommand(command, args) {
    if (command == "messagebox") {
        alert(args);
    }
}

fscommand("messagebox", "This is a message box called from within Flash.")

fscommand("messagebox", "Hello, " + name + ", welcome to our website!")

See also
    ExternalInterface Class

getProperty Function

Returns
     Object — The value of the specified property.

this.createEmptyMovieClip("someClip_mc", 999);
trace("The alpha of "+getProperty(someClip_mc, _name)+" is: "+getProperty(someClip_mc, _alpha));

getTimer Function

Returns
     Number — The number of milliseconds that have elapsed since the SWF file started playing.

this.createTextField("timer_txt", this.getNextHighestDepth(), 0, 0, 100, 22);
function updateTimer():Void {
    timer_txt.text = getTimer();
}

var intervalID:Number = setInterval(updateTimer, 100);

getURL Function

var listenerObject:Object = new Object();
listenerObject.onLoadInit = function(target_mc:MovieClip) {
    target_mc.onRelease = function() {
        getURL("http://www.macromedia.com/software/flash/flashpro/", "_blank");
    };
};
var logo:MovieClipLoader = new MovieClipLoader();
logo.addListener(listenerObject);
logo.loadClip("http://www.helpexamples.com/flash/images/image1.jpg",
    this.createEmptyMovieClip("macromedia_mc", this.getNextHighestDepth()));

myBtn_btn.onRelease = function(){
    getURL("mailto:you@somedomain.com");
};

myBtn_btn.onRelease = function(){
    getURL("javascript:alert('you clicked me')");
};

var firstName:String = "Gus";
var lastName:String = "Richardson";
var age:Number = 92;
myBtn_btn.onRelease = function() {
    getURL("http://www.macromedia.com", "_blank", "GET");
};

var firstName:String = "Gus";
var lastName:String = "Richardson";
var age:Number = 92;
getURL("http://www.macromedia.com", "_blank", "POST");

See also
    loadVariables(), XML.send(), XML.sendAndLoad()

getVersion Function

Returns
     String — A string containing Flash Player version and platform information.

var flashVersion:String = getVersion();
trace(flashVersion);  // output: WIN 8,0,1,0
trace($version);  // output: WIN 8,0,1,0
trace(System.capabilities.version);  // output: WIN 8,0,1,0

The following string is returned by the getVersion function:

WIN 8,0,1,0

This returned string indicates that the platform is Microsoft Windows, and the version number of Flash Player is major version 8, minor version 1 (8.1).

See also
    System.capabilities.os, System.capabilities.version

gotoAndPlay Function

stop();
myBtn_btn.onRelease = function(){
    gotoAndPlay("newFrame");
};

myOtherBtn_btn.onRelease = function(){
    gotoAndPlay("sceneTwo", 1);
};

See also
    MovieClip.goToAndPlay(), nextFrame(), play(), prevFrame()

gotoAndStop Function

stop();

myBtn_btn.onRelease = function(){
    gotoAndStop("newFrame");
};

myOtherBtn_btn.onRelease = function(){
    gotoAndStop("sceneTwo", 1);
};

See also
    MovieClip.gotoAndStop(), stop(), play(), gotoAndPlay()

ifFrameLoaded Function

ifFrameLoaded([scene:String], frame) { 
    statement(s); 
}

Deprecated as of Flash Player 5 — This function has been deprecated. Macromedia recommends that you use the MovieClip._framesloaded property.

See also
    MovieClip._framesloaded, MovieClipLoader.addListener()

int Function

Deprecated as of Flash Player 5 — This function was deprecated in favor of Math.round().

Returns
     Number — The truncated integer value.

See also
    Math.round(), Math.floor(), Math.ceil()

isFinite Function

Returns
     Boolean — A Boolean value.

isFinite(56)
// returns true

isFinite(Number.POSITIVE_INFINITY)
//returns false

isNaN Function

Returns
     Boolean — A Boolean value.

trace( isNaN("Tree") );
// returns true

trace( isNaN(56) );
// returns false

trace( isNaN(Number.POSITIVE_INFINITY) )
// returns false

var dividend:Number;
var divisor:Number;
divisor = 1;
trace( isNaN(dividend/divisor) );
// output: true 
// The output is true because the variable dividend is undefined. 
// Do not use isNAN() to check for division by 0 because it will return false.
// A positive number divided by 0 equals Infinity (Number.POSITIVE_INFINITY).
// A negative number divided by 0 equals -Infinity (Number.NEGATIVE_INFINITY).

See also
    NaN, Number.Nan

length Function

Deprecated as of Flash Player 5 — This function, along with all the string functions, has been deprecated. Macromedia recommends that you use the methods of the String class and the String.length property to perform the same operations.

Returns
     Number — The length of the specified string or variable.

See also
    " " (string delimiter), String class, String.length

loadMovie Function

loadMovie(url:String, target:Object, [method:String]) : Void
loadMovie(url:String, target:String, [method:String]) : Void

Tip: If you want to monitor the progress of the download, use MovieClipLoader.loadClip() instead of this function.

The loadMovie() function lets you display several SWF files at once and switch among SWF files without loading another HTML document. Without the loadMovie() function, Flash Player displays a single SWF file.

If you want to load a SWF or JPEG file into a specific level, use loadMovieNum() instead of loadMovie().

When a SWF file is loaded into a target movie clip, you can use the target path of that movie clip to target the loaded SWF file. A SWF file or image loaded into a target inherits the position, rotation, and scale properties of the targeted movie clip. The upper left corner of the loaded image or SWF file aligns with the registration point of the targeted movie clip. Alternatively, if the target is the root Timeline, the upper left corner of the image or SWF file aligns with the upper left corner of the Stage.

Use unloadMovie() to remove SWF files that were loaded with loadMovie().

When using this function, consider the Flash Player security model.

For Flash Player 8:

• Loading is not allowed if the calling movie clip is in the local-with-file-system sandbox and the loaded movie clip is from a network sandbox.
• Loading is not allowed if the calling SWF file is in a network sandbox and the movie clip to be loaded is local.
• Network sandbox access from the local-trusted or local-with-networking sandbox requires permission from the website by means of a cross-domain policy file.
• Movie clips in the local-with-file-system sandbox may not script movie clips in the local-with-networking sandbox (and the reverse is also prevented).

For Flash Player 7 and later:

• Websites can permit cross-domain access to a resource by means of a cross-domain policy file.
• Scripting between SWF files is restricted based on the origin domain of the SWF files. Use the System.security.allowDomain() method to adjust these restrictions.

For more information, see the following:

• Chapter 17, "Understanding Security," in Learning ActionScript 2.0 in Flash
• The Flash Player 8 Security white paper at http://www.macromedia.com/go/fp8_security
• The Flash Player 8 Security-Related API white paper at http://www.macromedia.com/go/fp8_security_apis

loadMovie("circle.swf", mySquare);
// equivalent statement (Usage 1): loadMovie("circle.swf", _level0.mySquare);
// equivalent statement (Usage 2): loadMovie("circle.swf", "mySquare");

loadMovie("circle.swf", this);
// Note that using "this" as a string for the target parameter will not work
// equivalent statement (Usage 2): loadMovie("circle.swf", "_level0");

this.createEmptyMovieClip("logo_mc", 999);
loadMovie("sub.swf", logo_mc);

myBtn_btn.onRelease = function(){
    loadMovie("image1.jpg", logo_mc);
};

loadMovie("circle.swf", "mySquare");

See also
    _level, loadMovieNum(), MovieClip.loadMovie(), MovieClipLoader.loadClip(), unloadMovie()

loadMovieNum Function

Tip: If you want to monitor the progress of the download, use MovieClipLoader.loadClip() instead of this function.

Normally, Flash Player displays a single SWF file and then closes. The loadMovieNum() action lets you display several SWF files at once and switch among SWF files without loading another HTML document.

If you want to specify a target instead of a level, use loadMovie() instead of loadMovieNum().

Flash Player has a stacking order of levels starting with level 0. These levels are like layers of acetate; they are transparent except for the objects on each level. When you use loadMovieNum(), you must specify a level in Flash Player into which the SWF file will load. When a SWF file is loaded into a level, you can use the syntax, _levelN, where N is the level number, to target the SWF file.

When you load a SWF file, you can specify any level number and you can load SWF files into a level that already has a SWF file loaded into it. If you do, the new SWF file will replace the existing SWF file. If you load a SWF file into level 0, every level in Flash Player is unloaded, and level 0 is replaced with the new file. The SWF file in level 0 sets the frame rate, background color, and frame size for all other loaded SWF files.

The loadMovieNum() action also lets you load JPEG files into a SWF file while it plays. For images and SWF files, the upper left corner of the image aligns with the upper left corner of the Stage when the file loads. Also in both cases, the loaded file inherits rotation and scaling, and the original content is overwritten in the specified level.

Note: JPEG files saved in progressive format are not supported.

Use unloadMovieNum() to remove SWF files or images that were loaded with loadMovieNum().

When using this method, consider the Flash Player security model.

For Flash Player 8:

• Loading is not allowed if the calling movie clip is in the local-with-file-system sandbox and the loaded movie clip is from a network sandbox.
• Loading is not allowed if the calling SWF file is in a network sandbox and the movie clip to be loaded is local.
• Network sandbox access from the local-trusted or local-with-networking sandbox requires permission from the website by means of a cross-domain policy file.
• Movie clips in the local-with-file-system sandbox may not script movie clips in the local-with-networking sandbox (and the reverse is also prevented).

For Flash Player 7 and later:

• Websites can permit cross-domain access to a resource by means of a cross-domain policy file.
• Scripting between SWF files is restricted based on the origin domain of the SWF files. Use the System.security.allowDomain() method to adjust these restrictions.

For more information, see the following:

• Chapter 17, "Understanding Security," in Learning ActionScript 2.0 in Flash
• The Flash Player 8 Security white paper at http://www.macromedia.com/go/fp8_security
• The Flash Player 8 Security-Related API white paper at http://www.macromedia.com/go/fp8_security_apis

loadMovieNum("http://www.helpexamples.com/flash/images/image1.jpg", 2);

See also
    unloadMovieNum(), loadMovie(), MovieClipLoader.loadClip(), _level

loadVariables Function

The text at the specified URL must be in the standard MIME format application/x-www-form-urlencoded (a standard format used by CGI scripts). Any number of variables can be specified. For example, the following phrase defines several variables:

company=Macromedia&address=600+Townsend&city=San+Francisco&zip=94103

In SWF files running in a version earlier than Flash Player 7, url must be in the same superdomain as the SWF file that is issuing this call. A superdomain is derived by removing the leftmost component of a file's URL. For example, a SWF file at www.someDomain.com can load data from a source at store.someDomain.com because both files are in the same superdomain of someDomain.com.

In SWF files of any version running in Flash Player 7 or later, url must be in exactly the same domain as the SWF file that is issuing this call (see "Flash Player security features" in Using ActionScript in Flash). For example, a SWF file at www.someDomain.com can load data only from sources that are also at www.someDomain.com. If you want to load data from a different domain, you can place a cross-domain policy file on the server hosting the SWF file that is being accessed. For more information, see "About allowing cross-domain data loading" in Using ActionScript in Flash.

If you want to load variables into a specific level, use loadVariablesNum() instead of loadVariables().

this.createEmptyMovieClip("target_mc", this.getNextHighestDepth());
loadVariables("params.txt", target_mc);
function checkParamsLoaded() {
    if (target_mc.done == undefined) {
        trace("not yet.");
    } else {
        trace("finished loading. killing interval.");
        trace("-------------");
        for (i in target_mc) {
            trace(i+": "+target_mc[i]);
        }
        trace("-------------");
        clearInterval(param_interval);
    }
}
var param_interval:Number = setInterval(checkParamsLoaded, 100);

The external file, params.txt, includes the following text:

var1="hello"&var2="goodbye"&done="done"

See also
    loadVariablesNum(), loadMovie(), loadMovieNum(), getURL(), MovieClip.loadMovie(), MovieClip.loadVariables(), LoadVars.load()

loadVariablesNum Function