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 = "[email protected]";
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:[email protected]");
};

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

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=601+Townsend&city=San+Francisco&zip=94103

In SWF files running in a version of the player 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. For more information, see "About allowing cross-domain data loading" in Using ActionScript in Flash.

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

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

// Params.txt includes the following text
var1="hello"&var2="goodbye"&done="done"

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

mbchr Function

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

See also
    String.fromCharCode()

mblength Function

Deprecated as of Flash Player 5 — This function was deprecated in favor of the methods and properties of the String class.

Returns
     Number — The length of the multibyte character string.

See also
    String class, String.length

mbord Function

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

Returns
     Number — The converted character.

See also
    String.charCodeAt()

mbsubstring Function

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

Returns
     String — The string extracted from the multibyte character string.

See also
    String.substr()

MMExecute Function

The Flash JSAPI provides several objects, methods, and properties to duplicate or emulate commands that a user can enter in the authoring environment. Using the JSAPI, you can write scripts that extend Flash in several ways: adding commands to menus, manipulating objects on the Stage, repeating sequences of commands, and so on.

In general, a user runs a JSAPI script by selecting Commands > Run Command. However, you can use this function in an ActionScript script to call a JSAPI command directly. If you use MMExecute() in a script on Frame 1 of your file, the command executes when the SWF file is loaded.

For more information on the JSAPI, see www.macromedia.com/go/jsapi_info_en.

Returns
     String — A string representation of the result, if any, sent by the JavaScript statement.

• Place the following code into frame 1 of the main Timeline of an empty Flash document:
  var numLibItems = MMExecute("fl.getDocumentDOM().library.items.length");
var message = numLibItems + " items in library";
MMExecute('fl.trace("' + message + '");');

• Save the FLA file in the WindowSWF directory that is located in your Configuration directory, and then select File > Publish (or save it elsewhere and either publish the SWF file directly to that directory, or move the SWF file to that directory).
• Quit and restart the application (you need to do this step the first time you add your file to the WindowSWF directory).

The ActionScript trace function does not work from a Flash panel; this example uses the JavaScript fl.trace version to get the output. It might be easier to copy the results of MMExecute to a text field that is part of your Flash Panel file.

nextFrame Function

stop();

if (init == undefined) {
    someListener = new Object();
    someListener.onKeyDown = function() {
        if (Key.isDown(Key.LEFT) || Key.isDown(Key.UP)) {
            _level0.prevFrame();
        } else if (Key.isDown(Key.RIGHT) || Key.isDown(Key.DOWN)) {
            _level0.nextFrame();
        }
    };
    Key.addListener(someListener);
    init = 1;
}

See also
    prevFrame()

nextScene Function

stop();

if (init == undefined) {
    this.createEmptyMovieClip("nextscene_mc", this.getNextHighestDepth());
    nextscene_mc.createTextField("nextscene_txt", this.getNextHighestDepth(), 200, 0, 100, 22);
    nextscene_mc.nextscene_txt.autoSize = true;
    nextscene_mc.nextscene_txt.border = true;
    nextscene_mc.nextscene_txt.text = "Next Scene";
    this.createEmptyMovieClip("prevscene_mc", this.getNextHighestDepth());
    prevscene_mc.createTextField("prevscene_txt", this.getNextHighestDepth(), 00, 0, 100, 22);
    prevscene_mc.prevscene_txt.autoSize = true;
    prevscene_mc.prevscene_txt.border = true;
    prevscene_mc.prevscene_txt.text = "Prev Scene";
    nextscene_mc.onRelease = function() {
        nextScene();
    };

    prevscene_mc.onRelease = function() {
        prevScene();
    };

    init = true;
}

See also
    prevScene()

Number Function

• If expression is a number, the return value is expression.
• If expression is a Boolean value, the return value is 1 if expression is true, 0 if expression is false.
• If expression is a string, the function attempts to parse expression as a decimal number with an optional trailing exponent (that is, 1.57505e-3).
• If expression is NaN, the return value is NaN.
• If expression is undefined, the return value is as follows:
  - In files published for Flash Player 6 or earlier, the result is 0.
  - In files published for Flash Player 7 or later, the result is NaN.

Returns
     Number — A number or NaN (not a number).

this.createTextField("counter_txt", this.getNextHighestDepth(), 0, 0, 100, 22);
counter_txt.autoSize = true;
counter_txt.text = 0;
function incrementInterval():Void {
    var counter:Number = counter_txt.text;
    // Without the Number() function, Flash would concatenate the value instead 
    // of adding values. You could also use "counter_txt.text++;"
    counter_txt.text = Number(counter) + 1;
}
var intervalID:Number = setInterval(incrementInterval, 1000);

See also
    NaN, Number class, parseInt(), parseFloat()

Object Function

Returns
     Object — An object.

var company:Object = new Object();
company.name = "Macromedia, Inc.";
company.address = "600 Townsend Street";
company.city = "San Francisco";
company.state = "CA";
company.postal = "94103";
for (var i in company) {
    trace("company."+i+" = "+company[i]);
}

See also
    Object Class

on Event Handler

on(mouseEvent:Object) {
    // your statements here
}

on (press) {
    startDrag(this);
}
on (release) {
    trace("X:"+this._x);
    trace("Y:"+this._y);
    stopDrag();
}

See also
    onClipEvent(), Key Class

onClipEvent Event Handler

onClipEvent(movieEvent:Object) {
    // your statements here
}

onClipEvent (keyDown) {
    if (Key.getCode() == Key.RIGHT) {
        this._parent.nextFrame();
    } else if (Key.getCode() == Key.LEFT) {
        this._parent.prevFrame();
    }
}

onClipEvent (load) {
    this.createTextField("coords_txt", this.getNextHighestDepth(), 0, 0, 100, 22);
    coords_txt.autoSize = true;
    coords_txt.selectable = false;
}
onClipEvent (mouseMove) {
    coords_txt.text = "X:"+_root._xmouse+",Y:"+_root._ymouse;
}

See also
    Key class, MovieClip._xmouse, MovieClip._ymouse, on(), updateAfterEvent()

ord Function

Deprecated as of Flash Player 5 — This function was deprecated in favor of the methods and properties of the String class.

Returns
     Number — The ASCII code number of the specified character.

See also
    String Class, String.charCodeAt()

parseFloat Function

Returns
     Number — A number or NaN (not a number).

trace(parseFloat("-2")); // output: -2
trace(parseFloat("2.5")); // output: 2.5
trace(parseFloat(" 2.5")); // output: 2.5
trace(parseFloat("3.5e6")); // output: 3500000
trace(parseFloat("foobar")); // output: NaN
trace(parseFloat("3.75math")); // output: 3.75
trace(parseFloat("0garbage")); // output: 0

See also
    NaN, parseInt()

parseInt Function

Returns
     Number — A number or NaN (not a number).

The following example returns 3:

parseInt("3.5")

The following example returns NaN:

parseInt("bar")

The following example returns 4:

parseInt("4foo")

The following example shows a hexadecimal conversion that returns 1016:

parseInt("0x3F8")

The following example shows a hexadecimal conversion using the optional radix parameter that returns 1000:

parseInt("3E8", 16)

The following example shows a binary conversion and returns 10, which is the decimal representation of the binary 1010:

parseInt("1010", 2)

The following examples show octal number parsing and return 511, which is the decimal representation of the octal 777:

parseInt("0777")
parseInt("777", 8)

See also
    NaN, parseFloat()

play Function

this.stop_mc.onRelease = function() {
    stop();
};
this.play_mc.onRelease = function() {
    play();
};
trace("frame 1");

See also
    gotoAndPlay(), MovieClip.gotoAndPlay()

prevFrame Function

stop();
this.myBtn_btn.onRelease = function(){
    prevFrame();
};

See also
    nextFrame(), MovieClip.prevFrame()

prevScene Function

See also
    nextScene()

print Function

If you use bmovie for the boundingBox parameter but do not assign a #b label to a frame, the print area is determined by the Stage size of the loaded movie clip. (The loaded movie clip does not inherit the main movie clip's Stage size.)

All the printable elements in a movie clip must be fully loaded before printing can begin.

The Flash Player printing feature supports PostScript and non-PostScript printers. Non-PostScript printers convert vectors to bitmaps.

this.createEmptyMovieClip("holder_mc", 999);
holder_mc.loadMovie("http://www.helpexamples.com/flash/images/image1.jpg");

this.myBtn_btn.onRelease = function() {
    print(this._parent.holder_mc, "bframe");
};

See also
    printAsBitmap(), printAsBitmapNum(), PrintJob Class, printNum()

printAsBitmap Function

If your movie clip does not contain alpha transparencies or color effects, Macromedia recommends that you use print() for better quality results.

If you use bmovie for the boundingBox parameter but do not assign a #b label to a frame, the print area is determined by the Stage size of the loaded movie clip. (The loaded movie clip does not inherit the main movie clip's Stage size.)

All the printable elements in a movie clip must be fully loaded before printing can begin.

The Flash Player printing feature supports PostScript and non-PostScript printers. Non-PostScript printers convert vectors to bitmaps.

this.createEmptyMovieClip("holder_mc", 999);
holder_mc.loadMovie("http://www.helpexamples.com/flash/images/image1.jpg");

this.myBtn_btn.onRelease = function() {
    printAsBitmap(this._parent.holder_mc, "bframe");
};

See also
    print(), printAsBitmapNum(), printNum(), PrintJob Class

printAsBitmapNum Function

If your movie clip does not contain alpha transparencies or color effects, using printNum() will give you better quality results.

If you use bmovie for the boundingBox parameter but do not assign a #b label to a frame, the print area is determined by the Stage size of the loaded movie clip. (The loaded movie clip does not inherit the main movie's Stage size.)

All the printable elements in a movie clip must be fully loaded before printing can start.

The Flash Player printing feature supports PostScript and non-PostScript printers. Non-PostScript printers convert vectors to bitmaps.

myBtn_btn.onRelease = function(){
    printAsBitmapNum(0, "bframe")
};

See also
    print(), printAsBitmap(), PrintJob class, printNum()

printNum Function

If you use bmovie for the boundingBox parameter but do not assign a #b label to a frame, the print area is determined by the Stage size of the loaded movie clip. (The loaded movie clip does not inherit the main movie's Stage size.)

All the printable elements in a movie clip must be fully loaded before printing can begin.

The Flash Player printing feature supports PostScript and non-PostScript printers. Non-PostScript printers convert vectors to bitmaps.

See also
    print(), printAsBitmap(), printAsBitmapNum(), PrintJob class

random Function

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

Returns
     Number — A random integer.

See also
    Math.random()

removeMovieClip Function

this.createEmptyMovieClip("myClip_mc", this.getNextHighestDepth());
myClip_mc.loadMovie("http://www.helpexamples.com/flash/images/image1.jpg");
duplicateMovieClip(this.myClip_mc, "newClip_mc", this.getNextHighestDepth());
newClip_mc.loadMovie("http://www.helpexamples.com/flash/images/image1.jpg");
newClip_mc._x = 200;
this.button_mc.onRelease = function() {
    removeMovieClip(this._parent.newClip_mc);
};

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

setInterval Function

setInterval(functionReference:Function, interval:Number, [param1:Object, param2, ..., paramN]) : Number
setInterval(objectReference:Object, methodName:String, interval:Number, [param1:Object, param2, ..., paramN]) : Number

Use the following tips when working with setInterval():

1. Identify the scope of the function being called.
2. Identify the scope where the interval ID (the return value of setInterval()) was set.
3. Clear previously set intervals before starting new ones.

Identify the scope of the function being called. To identify the scope of the function being called, pass the object where the setInterval() method can execute (the object scope) as the first parameter and the method name you want to execute as the second parameter (as shown in the second signature). This ensures that the desired method is executed from the scope of the object reference passed in. When the method is executed in this manner, it can reference member variables on the object using the this keyword.

Identify the scope where the interval identifier was set. To identify the scope where the interval identifier (intervalId) was set, you can assign it to a member variable on the object scope that you pass to setInterval(). In this way, the function being called can locate the interval identifier at this.intervalId.

Clear previously set intervals. To clear previously set intervals before starting new ones, you should usually call clearInterval() before calling setInterval(). This ensures that you do not overwrite or otherwise destroy your intervalId variable, which is the only reference to the currently running interval. To call clearInterval() prior to calling setInterval(), both the initiating script and the script being executed must have access to the intervalId, as shown in the Examples.

Note: Always be sure to call clearInterval() when you want the script to stop looping.

Returns
     Number — An integer that identifies the interval (the interval ID), which you can pass to clearInterval() to cancel the interval.

var intervalId:Number;
var count:Number = 0;
var maxCount:Number = 10;
var duration:Number = 20;

function executeCallback():Void {
    trace("executeCallback intervalId: " + intervalId + " count: " + count);
    if(count >= maxCount) {
        clearInterval(intervalId);
    } 
    count++;
}

intervalId = setInterval(this, "executeCallback", duration);

var intervalId:Number;
var count:Number = 0;
var maxCount:Number = 10;
var duration:Number = 20;

function executeCallback():Void {
    trace("executeCallback intervalId: " + intervalId + " count: " + count);
    if(count >= maxCount) {
        clearInterval(intervalId);
    }
    count++;
}

function beginInterval():Void {
    if(intervalId != null) {
        trace("clearInterval");
        clearInterval(intervalId);
    }
    intervalId = setInterval(this, "executeCallback", duration);
}

beginInterval();
beginInterval();
beginInterval();

var intervalId:Number;
var count:Number = 0;
var maxCount:Number = 10;
var duration:Number = 20;
var colors:Array = new Array("red", 
            "blue", 
            "yellow", 
            "purple", 
            "green", 
            "orange", 
            "salmon", 
            "pink", 
            "lilac", 
            "powder blue", 
            "mint");

function executeCallback(param:String) {
    trace("executeCallback intervalId: " + intervalId + " count: " + count + " param: " + param);
    clearInterval(intervalId);
    if(count < maxCount) {
        count++;
        intervalId = setInterval(this, "executeCallback", duration, colors[count]);
    }
}

if(intervalId != null) {
    clearInterval(intervalId);
}

intervalId = setInterval(this, "executeCallback", duration, colors[count]);

class CustomClass {
    private var intervalId:Number;
    private var count:Number = 0;
    private var maxCount:Number = 10;
    private var duration:Number = 20;

    public function CustomClass():Void {
        beginInterval();
    }
    
    private function beginInterval():Void {
        if(intervalId != null) {
            trace("clearInterval");
            clearInterval(intervalId);
        }
        intervalId = setInterval(this, "executeCallback", duration);
    }
    
    public function executeCallback():Void {
        trace("executeCallback intervalId: " + intervalId + " count: " + count);
        if(count >= maxCount) {
            clearInterval(intervalId);
        }
        count++;
    }
}

var custom:CustomClass = new CustomClass();

See also
    clearInterval(), updateAfterEvent(), class

setProperty Function

this.createEmptyMovieClip("params_mc", 999);
params_mc.loadMovie("http://www.helpexamples.com/flash/images/image1.jpg");
setProperty(this.params_mc, _y, 20);
setProperty(this.params_mc, _x, 20);
this.right_btn.onRelease = function() {
    setProperty(params_mc, _x, getProperty(params_mc, _x)+20);
};

See also
    getProperty()

setTimeout Function

To preserve the ability to use the clearTimeout() method to prevent setTimeout() from calling the function, be sure to assign the return value of the setTimeout() call to a variable.

Returns
     Number — Unique numeric identifier for the timed process.

var my_timedProcess:Number = setTimeout(my_delayedFunction, 2000, "two second delay");

function my_delayedFunction (arg1) {
    trace(arg1);
}
 
var escListener:Object = new Object();
escListener.onKeyDown = function() {
    if (Key.isDown(Key.ESCAPE)) {
        clearTimeout(my_timedProcess);
    }
};
Key.addListener(escListener);

When you use this example, be sure to select Control > Disable Keyboard Shortcuts in the test environment.

See also
    clearTimeout(), setInterval()

showRedrawRegions Function

var w:Number = 100;
var h:Number = 100;

var shape1:MovieClip = createShape("shape1");
shape1.onEnterFrame = function():Void {
    this._x += 5;
    this._y += 5;
}

var shape2:MovieClip = createShape("shape2");
shape2.onEnterFrame = function():Void {
    this._y += 5;
}

_global.showRedrawRegions(true);

function createShape(name:String):MovieClip {
    var mc:MovieClip = this.createEmptyMovieClip(name, this.getNextHighestDepth());
    mc.beginFill(0xFFCC00);
    mc.moveTo(200, 200);
    mc.curveTo(300, 200, 300, 100);
    mc.curveTo(300, 0, 200, 0);
    mc.curveTo(100, 0, 100, 100);
    mc.curveTo(100, 200, 200, 200);
    mc.endFill();
    return mc;
}

startDrag Function

var pic_mcl:MovieClipLoader = new MovieClipLoader();
pic_mcl.loadClip("http://www.helpexamples.com/flash/images/image1.jpg",
    this.createEmptyMovieClip("pic_mc", this.getNextHighestDepth()));
var listenerObject:Object = new Object();
listenerObject.onLoadInit = function(target_mc) {
    target_mc.onPress = function() {
        startDrag(this);
    };
    target_mc.onRelease = function() {
        stopDrag();
    };
};
pic_mcl.addListener(listenerObject);

See also
    stopDrag(), MovieClip._droptarget, MovieClip.startDrag()

stop Function

See also
    gotoAndStop(), MovieClip.gotoAndStop()

stopAllSounds Function

this.createTextField("songinfo_txt", this.getNextHighestDepth, 0, 0, Stage.width, 22);
var bg_sound:Sound = new Sound();
bg_sound.loadSound("yourSong.mp3", true);
bg_sound.onID3 = function() {
    songinfo_txt.text = "(" + this.id3.artist + ") " + this.id3.album + " - " + this.id3.track + " - " 
        + this.id3.songname;
    for (prop in this.id3) {
        trace(prop+" = "+this.id3[prop]);
    }
    trace("ID3 loaded.");
};
this.play_mc.onRelease = function() {
    /* get the current offset. if you stop all sounds and click the play button, the MP3 continues from 
       where it was stopped, instead of restarting from the beginning. */
    var numSecondsOffset:Number = (bg_sound.position/1000);
    bg_sound.start(numSecondsOffset);
};
this.stop_mc.onRelease = function() {
    stopAllSounds();
};

See also
    Sound class

stopDrag Function

my_mc.onPress = function () {
    startDrag(this);
}

my_mc.onRelease = function() {
    stopDrag();
}

See also
    startDrag(), MovieClip._droptarget, MovieClip.startDrag(), MovieClip.stopDrag()

String Function

• If expression is a number, the return string is a text representation of the number.
• If expression is a string, the return string is expression.
• If expression is an object, the return value is a string representation of the object generated by calling the string property for the object, or by calling Object.toString() if no such property exists.
• If expression is a Boolean value, the return string is "true" or "false".
• If expression is a movie clip, the return value is the target path of the movie clip in slash (/) notation.

Note: Slash notation is not supported by ActionScript 2.0.

Note: Slash notation is not supported in Flex applications.

Returns
     String — A string.

var string1:String = String("3");
var string2:String = String("9");
trace(string1+string2);  // output: 39

See also
    Number.toString(), Object.toString(), String Class, " " (string delimiter)

substring Function

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

Returns
     String — The extracted substring.

See also
    String.substr()

targetPath Function

Returns
     String — A string containing the target path of the specified object.

this.createEmptyMovieClip("myClip_mc", this.getNextHighestDepth());
trace(targetPath(myClip_mc));    // _level0.myClip_mc

See also
    eval()

tellTarget Function

tellTarget(target:String) { 
    statement(s); 
}

Deprecated as of Flash Player 5 — Macromedia recommends that you use dot (.) notation and the with statement.

In Flash 5 or later, you can use dot (.) notation instead of the tellTarget action. You can use the with action to issue multiple actions to the same Timeline. You can use the with action to target any object, whereas the tellTarget action can target only movie clips.

    on(release) {
        tellTarget("_parent.ball") {
            gotoAndPlay(2);
        }
    }
    

The following example uses dot (.) notation to achieve the same results:

    on(release) {
        _parent.ball.gotoAndPlay(2);
    }
    

If you need to issue multiple commands to the ball instance, you can use the with action, as shown in the following statement:

    on(release) {
        with(_parent.ball) {
            gotoAndPlay(2);
            _alpha = 15;
            _xscale = 50;
            _yscale = 50;
        }
    }
    

See also
    with

toggleHighQuality Function

Deprecated as of Flash Player 5 — This function was deprecated in favor of _quality.

    on(release) {
        toggleHighQuality();
    }
    

See also
    _highquality, _quality

trace Function

this.createTextField("error_txt", this.getNextHighestDepth(), 0, 0, 100, 22);
for (var i in error_txt) {
trace("error_txt."+i+" = "+error_txt[i]);
}
/* output:
error_txt.styleSheet = undefined
error_txt.mouseWheelEnabled = true
error_txt.condenseWhite = false
...
error_txt.maxscroll = 1
error_txt.scroll = 1
*/

unescape Function

Returns
     String — A string decoded from a URL-encoded parameter.

var email:String = "[email protected]";
trace(email);
var escapedEmail:String = escape(email);
trace(escapedEmail);
var unescapedEmail:String = unescape(escapedEmail);
trace(unescapedEmail);

[email protected]
user%40somedomain%2Ecom
[email protected]

unloadMovie Function

unloadMovie(target:MovieClip) : Void
unloadMovie(target:String) : Void

var pic_mcl:MovieClipLoader = new MovieClipLoader();
pic_mcl.loadClip("http://www.helpexamples.com/flash/images/image1.jpg",
    this.createEmptyMovieClip("pic_mc", this.getNextHighestDepth()));
var listenerObject:Object = new Object();
listenerObject.onLoadInit = function(target_mc) {
    target_mc.onRelease = function() {
        unloadMovie(pic_mc);
        /* or you could use the following, which refers to the movie clip referenced by 'target_mc'. */
        //unloadMovie(this);
    };
};
pic_mcl.addListener(listenerObject);

See also
    MovieClip.loadMovie(), MovieClipLoader.unloadClip()

unloadMovieNum Function

loadMovieNum("yourimage.jpg", 1);
unload_btn.onRelease = function() {
    unloadMovieNum(1);
}

See also
    loadMovieNum(), unloadMovie(), MovieClip.loadMovie()

updateAfterEvent Function

Mouse.hide();
cursor_mc.onMouseMove = function() {
    this._x = this._parent._xmouse;
    this._y = this._parent._ymouse;
    updateAfterEvent();
};

See also
    onClipEvent(), setInterval()