Adobe Logo

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


Functions
       Array([numElements:Number], [elementN:Object]) : Array
Creates a new, empty array or converts specified elements to an array.
       asfunction
A special protocol for URLs in HTML text fields that allows an HREF link to call an ActionScript function.
       Boolean(expression:Object) : Boolean
Converts the parameter expression to a Boolean value and returns true or false.
       call(frame:Object) : Void
Deprecated as of Flash Player 5 — This action was deprecated in favor of the function statement.
       chr(number:Number) : String
Deprecated as of Flash Player 5 — This function was deprecated in favor of String.fromCharCode().
       clearInterval(intervalID:Number) : Void
Stops the setInterval() call.
       clearTimeout(id:Number) : Void
Cancels a specified setTimeout() call.
       duplicateMovieClip(target:Object, newname:String, depth:Number) : Void
Creates an instance of a movie clip while the SWF file is playing.
       escape(expression:String) : String
Converts the parameter to a string and encodes it in a URL-encoded format, where all nonalphanumeric characters are replaced with % hexadecimal sequences.
       eval(expression:Object) : Object
Accesses variables, properties, objects, or movie clips by name.
       fscommand(command:String, parameters:String) : Void
Lets the SWF file communicate with either Flash Player or the program hosting Flash Player, such as a web browser.
       getProperty(my_mc:Object, property) : Object
Returns the value of the specified property for the movie clip my_mc.
       getTimer() : Number
Returns the number of milliseconds that have elapsed since the SWF file started playing.
       getURL(url:String, [window:String], [method:String]) : Void
Loads a document from a specific URL into a window or passes variables to another application at a defined URL.
       getVersion() : String
Returns a string containing Flash Player version and platform information.
       gotoAndPlay([scene:String], frame:Object) : Void
Sends the playhead to the specified frame in a scene and plays from that frame.
       gotoAndStop([scene:String], frame:Object) : Void
Sends the playhead to the specified frame in a scene and stops it.
       ifFrameLoaded([scene:String], frame:Object) : Void
Deprecated as of Flash Player 5 — This function has been deprecated. Adobe recommends that you use the MovieClip._framesloaded property.
       int(value:Number) : Number
Deprecated as of Flash Player 5 — This function was deprecated in favor of Math.floor() for positive values and Math.ceil for negative values.
       isFinite(expression:Object) : Boolean
Evaluates expression and returns true if it is a finite number or false if it is infinity or negative infinity.
       isNaN(expression:Object) : Boolean
Evaluates the parameter and returns true if the value is NaN (not a number).
       length(expression:String, variable:Object) : Number
Deprecated as of Flash Player 5 — This function, along with all the string functions, has been deprecated. Adobe recommends that you use the methods of the String class and the String.length property to perform the same operations.
       loadMovie(url:String, target:Object, [method:String]) : Void
Loads a SWF or JPEG file into Flash Player while the original SWF file plays.
       loadMovieNum(url:String, level:Number, [method:String]) : Void
Loads a SWF or JPEG file into a level in Flash Player while the originally loaded SWF file plays.
       loadVariables(url:String, target:Object, [method:String]) : Void
Reads data from an external file, such as a text file or text generated by ColdFusion, a CGI script, Active Server Pages (ASP), PHP, or Perl script, and sets the values for variables in a target movie clip.
       loadVariablesNum(url:String, level:Number, [method:String]) : Void
Reads data from an external file, such as a text file or text generated by a ColdFusion, CGI script, ASP, PHP, or Perl script, and sets the values for variables in a Flash Player level.
       mbchr(number:Number) : Void
Deprecated as of Flash Player 5 — This function was deprecated in favor of the String.fromCharCode() method.
       mblength(string:String) : Number
Deprecated as of Flash Player 5 — This function was deprecated in favor of the methods and properties of the String class.
       mbord(character:String) : Number
Deprecated as of Flash Player 5 — This function was deprecated in favor of String.charCodeAt().
       mbsubstring(value:String, index:Number, count:Number) : String
Deprecated as of Flash Player 5 — This function was deprecated in favor of String.substr().
       MMExecute(command:String) : String
Lets you issue Flash JavaScript API (JSAPI) commands from ActionScript.
       nextFrame() : Void
Sends the playhead to the next frame.
       nextScene() : Void
Sends the playhead to Frame 1 of the next scene.
       Number(expression:Object) : Number
Converts the parameter expression to a number.
       Object([value:Object]) : Object
Creates a new empty object or converts the specified number, string, or Boolean value to an object.
       on(mouseEvent:Object) : Void
Specifies the mouse event or keypress that triggers an action.
       onClipEvent(movieEvent:Object) : Void
Triggers actions defined for a specific instance of a movie clip.
       ord(character:String) : Number
Deprecated as of Flash Player 5 — This function was deprecated in favor of the methods and properties of the String class.
       parseFloat(string:String) : Number
Converts a string to a floating-point number.
       parseInt(expression:String, [radix:Number]) : Number
Converts a string to an integer.
       play() : Void
Moves the playhead forward in the Timeline.
       prevFrame() : Void
Sends the playhead to the previous frame.
       prevScene() : Void
Sends the playhead to Frame 1 of the previous scene.
       print(target:Object, boundingBox:String) : Void
Prints the target movie clip according to the boundaries specified in the parameter (bmovie, bmax, or bframe).
       printAsBitmap(target:Object, boundingBox:String) : Void
Prints the target movie clip as a bitmap according to the boundaries specified in the parameter (bmovie, bmax, or bframe).
       printAsBitmapNum(level:Number, boundingBox:String) : Void
Prints a level in Flash Player as a bitmap according to the boundaries specified in the parameter (bmovie, bmax, or bframe).
       printNum(level:Number, boundingBox:String) : Void
Prints the level in Flash Player according to the boundaries specified in the boundingBox parameter (bmovie, bmax, bframe).
       random(value:Number) : Number
Deprecated as of Flash Player 5 — This function was deprecated in favor of Math.random().
       removeMovieClip(target:Object) : Void
Deletes the specified movie clip.
       setInterval(functionReference:Function, interval:Number, [param:Object], objectReference:Object, methodName:String) : Number
Calls a function or a method of an object at periodic intervals while a SWF file plays.
       setProperty(target:Object, property:Object, expression:Object) : Void
Changes a property value of a movie clip as the movie clip plays.
       setTimeout(functionReference:Object, delay:Number, args:Object) : Number
Runs a specified function after a specified delay (in milliseconds).
       showRedrawRegions(enable:Boolean, [color:Number]) : Void
Provides the ability for the debugger player to outline the regions of the screen that are being redrawn.
       startDrag(target:Object, [lock:Boolean], [left,top,right,bottom:Number]) : Void
Makes the target movie clip draggable while the movie plays.
       stop() : Void
Stops the SWF file that is currently playing.
       stopAllSounds() : Void
Stops all sounds currently playing in a SWF file without stopping the playhead.
       stopDrag() : Void
Stops the current drag operation.
       String(expression:Object) : String
Returns a string representation of the specified parameter.
       substring(string:String, index:Number, count:Number) : String
Deprecated as of Flash Player 5 — This function was deprecated in favor of String.substr().
       targetPath(targetObject:Object) : String
Returns a string containing the target path of movieClipObject.
       tellTarget(target:String, statement(s)) : Void
Deprecated as of Flash Player 5 — Adobe recommends that you use dot (.) notation and the with statement.
       toggleHighQuality() : Void
Deprecated as of Flash Player 5 — This function was deprecated in favor of _quality.
       trace(expression:Object) : Void
Evaluates the expression and outputs the result.
       unescape(string:String) : String
Evaluates the parameter x as a string, decodes the string from URL-encoded format (converting all hexadecimal sequences to ASCII characters), and returns the string.
       unloadMovie(target:Object) : Void
Removes a movie clip that was loaded by means of loadMovie() from Flash Player.
       unloadMovieNum(level:Number) : Void
Removes a SWF or image that was loaded by means of loadMovieNum() from Flash Player.
       updateAfterEvent() : Void
Updates the display when you call it within an handler or using setInterval().


Function detail

Array Function

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

Player version:  Flash Player 6

Creates a new array of length 0 or more, or an array populated by a list of specified elements, possibly of different data types.

Use Array() to create one of the following:

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.

Parameters
numElements:Number [optional] — A positive integer that specifies the number of elements in the array. You can specify either numElements or the list of elements, but not both.
elementN:Object [optional] — One or more parameters, element0, element1, ... , elementN, the values of which can be of any type. Parameters that can accept more than one data type are listed as type Object. You can specify either numElements or the list of elements, but not both.

Returns
     Array — An array.

Example
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);  // 4
trace(myArray); // 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); // firstElement,secondElement,thirdElement
Unlike the Array class constructor, the Array() function does not use the keyword new .

See also
    Array class


asfunction Protocol

asfunction:function:Function, parameter:String

Player version:  Flash Player 5

A special protocol for URLs in HTML text fields that allows an HREF link to call an ActionScript function. In HTML text fields, you can create links using the HTML A tag. The HREF attribute of the A tag contains a URL that uses a standard protocol such as HTTP, HTTPS, or FTP. The asfunction protocol is an additional protocol that is specific to Flash, which causes the link to invoke an ActionScript function.

Parameters
function:String — An identifier for a function.
parameter:String — A string that is passed to the function named in the function parameter.

Example
In the following example, the playMP3() function is defined. The TextField object list_txt is created and set so HTML text can be rendered. The text Track 1 and Track 2 are links inside the text field. The playMP3() function is called when the user clicks either link and plays the MP3 that is passed as a parameter of the asfunction call.
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>";
When you click a link, the MP3 sound file streams in Flash Player.

See also
    TextField.htmlText


Boolean Function

Boolean(expression:Object) : Boolean

Player version:  Flash Player 5 — Behavior changed in Flash Player 7.

Converts the expression parameter to a Boolean value and returns a value as described in the following list: If expression is a string, the return value is as follows: If expression is a string, the result is true if the string has a length greater than 0; the value is false for an empty string.

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.

Parameters
expression:Object — An expression to convert to a Boolean value.

Returns
     Boolean — A Boolean value.

Example
trace(Boolean(-1)); // true
trace(Boolean(0)); // false
trace(Boolean(1)); // true


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


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

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

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

trace(Boolean("true")); // false
trace(Boolean("false")); // false
trace(Boolean("Craiggers")); // 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

call(frame)

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

Player version:  Flash Player 4

Executes the script in the called frame without moving the playhead to that frame. Local variables do not exist after the script executes.

Parameters
frame:Object — The label or number of a frame in the Timeline.

See also
    function statement, Function.call()


chr Function

chr(number:Number) : String

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

Player version:  Flash Player 4

Converts ASCII code numbers to characters.

Parameters
number:Number — An ASCII code number.

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

Example
The following example converts the number 65 to the letter A and assigns it to the variable myVar:
myVar = chr(65);

See also
    String.fromCharCode()


clearInterval Function

clearInterval(intervalID:Number) : Void

Player version:  Flash Player 6

Stops the setInterval() call.

Parameters
intervalID:Number — A numeric (integer) identifier returned from a call to setInterval().

Example
The following example first sets and then clears an interval call:

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

clearTimeout(id:Number) : Void

Player version:  Flash Player 8

Cancels a specified setTimeout() call.

Parameters
id:Number — The identification number of the setTimeout() call to cancel.

Example
Also, see the example for the setTimeout() function.

See also
    setTimeout(), setInterval()


duplicateMovieClip Function

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

Player version:  Flash Player 4

Creates an instance of a movie clip while the SWF file is playing. The playhead in duplicate movie clips always starts at Frame 1, regardless of where the playhead is in the original movie clip. Variables in the original movie clip are not copied into the duplicate movie clip. Use the removeMovieClip() function or method to delete a movie clip instance created with duplicateMovieClip().

Parameters
target:Object — The target path of the movie clip to duplicate. This parameter can be either a String (e.g. "my_mc") or a direct reference to the movie clip instance (e.g. my_mc). Parameters that can accept more than one data type are listed as type Object.
newname:String — A unique identifier for the duplicated movie clip.
depth:Number — A unique depth level for the duplicated movie clip. The depth level is a stacking order for duplicated movie clips. This stacking order is similar to the stacking order of layers in the Timeline; movie clips with a lower depth level are hidden under clips with a higher stacking order. You must assign each duplicated movie clip a unique depth level to prevent it from replacing SWF files on occupied depths.

Example
In the following example, a new movie clip instance is created called img_mc. An image is loaded into the movie clip, and then the img_mc clip is duplicated. The duplicated clip is called newImg_mc, and this new clip is moved on the Stage so it does not overlap the original clip, and the same image is loaded into the second clip.
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");
To remove the duplicate movie clip, you could add this code for a button called myButton_btn.
this.myButton_btn.onRelease = function(){
    removeMovieClip(newImg_mc);
};

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


escape Function

escape(expression:String) : String

Player version:  Flash Player 5

Converts the parameter to a string and encodes it in a URL-encoded format, where all nonalphanumeric characters are replaced with % hexadecimal sequences. When used in a URL-encoded string, the percentage symbol (%) is used to introduce escape characters, and is not equivalent to the modulo operator (%).

Parameters
expression:String — The expression to convert into a string and encode in a URL-encoded format.

Returns
     String — URL-encoded string.

Example
The following code produces the result someuser%40somedomain%2Ecom:
var email:String = "someuser@somedomain.com";
trace(escape(email));
In this example, the at symbol (@) was replaced with %40 and the dot symbol (.) was replaced with %2E. This is useful if you're trying to pass information to a remote server and the data has special characters in it (for example, & or ?), as shown in the following code:
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

Player version:  Flash Player 5 — Flash Player 5 or later for full functionality. You can use the eval() function when exporting to Flash Player 4, but you must use slash notation and can access only variables, not properties or objects.

Accesses variables, properties, objects, or movie clips by name. If expression is a variable or a property, the value of the variable or property is returned. If expression is an object or movie clip, a reference to the object or movie clip is returned. If the element named in expression cannot be found, undefined is returned.

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

with this:

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

or this:

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

Parameters
expression:Object — The name of a variable, property, object, or movie clip to retrieve. This parameter can be either a String or a direct reference to the object instance (i.e use of quotation marks (" ") is optional.)

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

Example
The following example uses eval() to set properties for dynamically named movie clips. This ActionScript sets the _rotation property for three movie clips, called square1_mc, square2_mc, and square3_mc.
for (var i = 1; i <= 3; i++) {
    setProperty(eval("square"+i+"_mc"), _rotation, 5);
}
You can also use the following ActionScript:
for (var i = 1; i <= 3; i++) {
    this["square"+i+"_mc"]._rotation = -5;
}

See also
    Array class, set variable


fscommand Function

fscommand(command:String, parameters:String) : Void

Player version:  Flash Player 3

Lets the SWF file communicate with either Flash Player or the program that is hosting Flash Player, such as a web browser. You can also use the fscommand() function to pass messages to Macromedia Director, or to Visual Basic (VB), Visual C++, and other programs that can host ActiveX controls.

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 or the EMBED tag.)

For more information related to security, see the following:

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

Command Parameter Purpose
quit None Closes the projector.
fullscreen true or false Specifying true sets Flash Player to full-screen mode. Specifying false returns the player to normal menu view.
allowscale true or false Specifying false sets the player so that the SWF file is always drawn at its original size and never scaled. Specifying true forces the SWF file to scale to 100% of the player.
showmenu true or false Specifying true enables the full set of context menu items. Specifying false hides all of the context menu items except About Flash Player and Settings.
exec Path to application Executes an application from within the projector.
trapallkeys true or false Specifying true sends all key events, including accelerator keys, to the onClipEvent(keyDown/keyUp) handler in Flash Player.

Availability:

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.

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.

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

Parameters
command:String — A string passed to the host application for any use, or a command passed to Flash Player.
parameters:String — A string passed to the host application for any use, or a value passed to Flash Player.

Example
In the following example, fscommand() sets Flash Player to scale the SWF file to the full monitor screen size when the fullscreen_btn or unfullscreen_btn button is released:
this.fullscreen_btn.onRelease = function() {
    fscommand("fullscreen", true);
};

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

The following example applies fscommand() to a button in Flash for the purpose of opening a JavaScript message box in an HTML page. The message itself is sent to JavaScript as the fscommand parameter.

You must add a function to the web page that contains the SWF file. This function, myDocument_DoFSCommand(), waits for an fscommand() call. When fscommand() is triggered in Flash (for example, when a user clicks the button), the command and parameter strings are passed to the myDocument_DoFSCommand()function. You can use the passed strings in your JavaScript or VBScript code in any way you like. In this example, the function contains a conditional if statement that checks to see if the command string is "messagebox". If it is, a JavaScript alert box displays the contents of the fscommand() function's parameters string.

function myDocument_DoFSCommand(command, args) {
    if (command == "messagebox") {
        alert(args);
    }
}
In the Flash document, add fscommand() to a button:
fscommand("messagebox", "This is a message box called from within Flash.")

You can use expressions for the parameters of the fscommand() function, as shown in the following example:

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

To test the SWF file, select File > Publish Preview > HTML. If you publish your SWF file using the Flash with FSCommand template (in the Publish Settings dialog box, select the HTML tag), Flash inserts the myDocument_DoFSCommand() function automatically. The SWF file's NAME and ID attributes will be the filename. For example, for the file myDocument.fla, the attributes would be set to myDocument.

See also
    ExternalInterface Class


getProperty Function

getProperty(my_mc:Object, property:Object) : Object

Player version:  Flash Player 4

Returns the value of the specified property for the movie clip my_mc.

Parameters
my_mc:Object — Can be either a String object, the instance name of a movie clip for which the property is being retrieved, or a MovieClip object, the reference to a movie clip for which the property is being retrieved.
property — A property of a movie clip.

Returns
     Object — The value of the specified property.

Example
The following example creates a new movie clip someClip_mc and shows the alpha value (_alpha) for the movie clip someClip_mc in the Output panel:
this.createEmptyMovieClip("someClip_mc", 999);
trace("The alpha of "+getProperty(someClip_mc, _name)+" is: "+getProperty(someClip_mc, _alpha));


getTimer Function

getTimer() : Number

Player version:  Flash Player 4

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

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

Example
In the following example, the getTimer() and setInterval() functions are used to create a simple timer:
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

getURL(url:String, [window:String, [method:String]]) : Void

Player version:  Flash Player 2 — The GET and POST options are available only in Flash Player 4 and later versions.

Loads a document from a specific URL into a window or passes variables to another application at a defined URL. To test this function, make sure the file to be loaded is at the specified location. To use an absolute URL (for example, http://www.myserver.com), you need a network connection.

Important Security Note

Developers often pass URL values to the navigateToURL() function that were obtained from external sources such as FlashVars. Attackers may try to manipulate these external sources to perform attacks such as cross-site scripting. Therefore, developers should validate all URLs before passing them to this function.

Good data validation for URLs can mean different things depending on the usage of the URL within the overall application. The most common data validation techniques include validating that the URL is of the appropriate scheme. For instance, unintentionally allowing javascript: URLs may result in cross-site scripting. Validating that the URL is a within your domain can ensure that the SWF file can't be used as an open-redirector by people who conduct phishing attacks. For additional security, you may also choose to validate the path of the URL and to validate that the URL conforms to the RFC guidelines

For example, the following code shows a simple example of performing data validation by denying any URL that does not begin with http:// or https:// and validating that the URL is within your domain name. This example may not be appropriate for all web applications and you should consider whether additional checks against the URL are necessary.

// The comparison can be adjusted to include both the protocol and your // domain name for added security. // checkProtocol returns true if the protocol is allowed function checkProtocol(url:String):Boolean { var my_lc:LocalConnection = new LocalConnection(); var domainName:String = my_lc.domain(); // Is the URL the correct length? if (url.length < 7 + domainName.length || url.length > 4096) { return false; } // Reject any URL that uses a protocol other than http: or https // Also verify the URL is for my domain if (url.substr(0,8 + domainName.length) == "http://" + domainName + "/" || url.substr(0,9 + domainName.length) == "https://" + domainName + "/") { return (true); } else { return (false); } }

Additional security notes:

For more information related to security, see the following:

Parameters
url:String — The URL from which to obtain the document.
window:String [optional] — Specifies the window or HTML frame into which the document should load. You can enter the name of a specific window or select from the following reserved target names:
  • _self specifies the current frame in the current window.
  • _blank specifies a new window.
  • _parent specifies the parent of the current frame.
  • _top specifies the top-level frame in the current window.
method:String [optional] — A GET or POST method for sending variables. If there are no variables, omit this parameter. The GET method appends the variables to the end of the URL, and is used for small numbers of variables. The POST method sends the variables in a separate HTTP header and is used for sending long strings of variables.

Example
This example loads an image into a movie clip. When the image is clicked, a new URL is loaded in a new browser window.
var listenerObject:Object = new Object();
listenerObject.onLoadInit = function(target_mc:MovieClip) {
    target_mc.onRelease = function() {
        getURL("http://www.adobe.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("adobe_mc", this.getNextHighestDepth()));
In the following example, getURL() is used to send an e-mail message:
myBtn_btn.onRelease = function(){
    getURL("mailto:you@somedomain.com");
};
In the following ActionScript, JavaScript is used to open an alert window when the SWF file is embedded in a browser window (please note that when calling JavaScript with getURL(), the url parameter is limited to 508 characters):
myBtn_btn.onRelease = function(){
    getURL("javascript:alert('you clicked me')");
};
You can also use GET or POST for sending variables. The following example uses GET to append variables to a URL:
var firstName:String = "Gus";
var lastName:String = "Richardson";
var age:Number = 92;
myBtn_btn.onRelease = function() {
    getURL("http://www.adobe.com", "_blank", "GET");
};
The following ActionScript uses POST to send variables in the HTTP header. Make sure you test your documents in a browser window, because otherwise your variables are sent using GET:
var firstName:String = "Gus";
var lastName:String = "Richardson";
var age:Number = 92;
getURL("http://www.adobe.com", "_blank", "POST");

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


getVersion Function

getVersion() : String

Player version:  Flash Player 5

Returns a string containing Flash Player version and platform information. The getVersion function returns information only for Flash Player 5 or later versions of Flash Player.

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

Example
The following examples trace the version number of the Flash Player playing the SWF file:
var flashVersion:String = getVersion();
trace(flashVersion);  // WIN 8,0,1,0
trace($version);  // WIN 8,0,1,0
trace(System.capabilities.version);  // 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

gotoAndPlay([scene:String], frame:Object) : Void

Player version:  Flash Player 2

Sends the playhead to the specified frame in a scene and plays from that frame. If no scene is specified, the playhead goes to the specified frame in the current scene. You can use the scene parameter only on the root Timeline, not within Timelines for movie clips or other objects in the document.

Parameters
scene:String [optional] — A string specifying the name of the scene to which the playhead is sent.
frame:Object — A number representing the frame number, or a string representing the label of the frame, to which the playhead is sent.

Example
In the following example, a document has two scenes: sceneOne and sceneTwo. Scene one contains a frame label on Frame 10 called newFrame and two buttons, myBtn_btn and myOtherBtn_btn. This ActionScript is placed on Frame 1, Scene 1 of the main Timeline.
stop();
myBtn_btn.onRelease = function(){
    gotoAndPlay("newFrame");
};

myOtherBtn_btn.onRelease = function(){
    gotoAndPlay("sceneTwo", 1);
};
When the user clicks the buttons, the playhead moves to the specified location and continues playing.

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


gotoAndStop Function

gotoAndStop([scene:String], frame:Object) : Void

Player version:  Flash Player 2

Sends the playhead to the specified frame in a scene and stops it. If no scene is specified, the playhead is sent to the frame in the current scene. You can use the scene parameter only on the root Timeline, not within Timelines for movie clips or other objects in the document.

Parameters
scene:String [optional] — A string specifying the name of the scene to which the playhead is sent.
frame:Object — A number representing the frame number, or a string representing the label of the frame, to which the playhead is sent.

Example
In the following example, a document has two scenes: sceneOne and sceneTwo. Scene one contains a frame label on Frame 10 called newFrame, and two buttons, myBtn_btn and myOtherBtn_btn. This ActionScript is placed on Frame 1, Scene 1 of the main Timeline:

stop();

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

myOtherBtn_btn.onRelease = function(){
    gotoAndStop("sceneTwo", 1);
};
When the user clicks the buttons, the playhead moves to the specified location and stops.

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. Adobe recommends that you use the MovieClip._framesloaded property.

Player version:  Flash Player 4

Checks whether the contents of a specific frame are available locally. Use ifFrameLoaded to start playing a simple animation while the rest of the SWF file downloads to the local computer. The difference between using _framesloaded and ifFrameLoaded is that _framesloaded lets you add custom if or else statements.

Parameters
scene:String [optional] — A string that specifies the name of the scene that must be loaded.
frame:Object — The frame number or frame label that must be loaded before the next statement is executed.

See also
    MovieClip._framesloaded, MovieClipLoader.addListener()


int Function

int(value:Number) : Number

Deprecated as of Flash Player 5 — This function was deprecated in favor of Math.floor() for positive values and Math.ceil for negative values.

Player version:  Flash Player 4

Converts a decimal number to an integer value by truncating the decimal value. This function is equivalent to Math.floor() if the value parameter is positive and Math.ceil() if the value parameter is negative.

Parameters
value:Number — A number to be rounded to an integer.

Returns
     Number — The truncated integer value.

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


isFinite Function

isFinite(expression:Object) : Boolean

Player version:  Flash Player 5

Evaluates expression and returns true if it is a finite number or false if it is infinity or negative infinity. The presence of infinity or negative infinity indicates a mathematical error condition such as division by 0.

Parameters
expression:Object — A Boolean value, variable, or other expression to be evaluated.

Returns
     Boolean — A Boolean value.

Example
The following example shows return values for isFinite:
isFinite(56)
// returns true

isFinite(Number.POSITIVE_INFINITY)
//returns false


isNaN Function

isNaN(expression:Object) : Boolean

Player version:  Flash Player 5

Evaluates the parameter and returns true if the value is NaN(not a number). This function is useful for checking whether a mathematical expression evaluates successfully to a number.

Parameters
expression:Object — A Boolean, variable, or other expression to be evaluated.

Returns
     Boolean — A Boolean value.

Example
The following code illustrates return values for the isNaN() function:
trace( isNaN("Tree") );
// returns true

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

trace( isNaN(Number.POSITIVE_INFINITY) )
// returns false
The following example shows how you can use isNAN() to check whether a mathematical expression contains an error:
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

length(expression:String)
length(variable)

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

Player version:  Flash Player 4

Returns the length of the specified string or variable.

Parameters
expression:String — A string.
variable:Object — The name of a variable.

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

Example
The following example returns the length of the string "Hello":
length("Hello");
The result is 5.

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

Player version:  Flash Player 3 — The ability to load JPEG files is available as of Flash Player 6. The ability to load unanimated GIF files, PNG files, or progressive JPEG files is available as of Flash Player 8.

Loads a SWF, JPEG, GIF, or PNG file into a movie clip in Flash Player while the original SWF file is playing. Support for unanimated GIF files, PNG files, and progressive JPEG files is added in Flash Player 8. If you load an animated GIF, only the first frame is displayed.

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 more information related to security, see the following:

Parameters
url:String — The absolute or relative URL of the SWF or JPEG file to be loaded. A relative path must be relative to the SWF file at level 0. Absolute URLs must include the protocol reference, such as http:// or file:///.
target:Object — A reference to a movie clip object or a string representing the path to a target movie clip. The target movie clip is replaced by the loaded SWF file or image.
method:String [optional] — Specifies an HTTP method for sending variables. The parameter must be the string GET or POST . If there are no variables to be sent, omit this parameter. The GET method appends the variables to the end of the URL and is used for small numbers of variables. The POST method sends the variables in a separate HTTP header and is used for long strings of variables.

Example
Usage 1: The following example loads the SWF file circle.swf from the same directory and replaces a movie clip called mySquare that already exists on the Stage:
loadMovie("circle.swf", mySquare);
// equivalent statement (Usage 1): loadMovie("circle.swf", _level0.mySquare);
// equivalent statement (Usage 2): loadMovie("circle.swf", "mySquare");
The following example loads the SWF file circle.swf from the same directory, but replaces the main movie clip instead of the mySquare movie clip:
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");
The following loadMovie() statement loads the SWF file sub.swf from the same directory into a new movie clip called logo_mc that's created using createEmptyMovieClip():
this.createEmptyMovieClip("logo_mc", 999);
loadMovie("sub.swf", logo_mc);
You could add the following code to load a JPEG image called image1.jpg from the same directory as the SWF file loading sub.swf. The JPEG is loaded when you click a button called myBtn_btn. This code loads the JPEG into logo_mc. Therefore, it will replace sub.swf with the JPEG image.
myBtn_btn.onRelease = function(){
    loadMovie("image1.jpg", logo_mc);
};
Usage 2: The following example loads the SWF file circle.swf from the same directory and replaces a movie clip called mySquare that already exists on the Stage:
loadMovie("circle.swf", "mySquare");

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


loadMovieNum Function

loadMovieNum(url:String, level:Number, [method:String]) : Void

Player version:  Flash Player 4 — Flash 4 files opened in Flash 5 or later are converted to use the correct syntax. The ability to load JPEG files is available as of Flash Player 6. The ability to load unanimated GIF files, PNG files, or progressive JPEG files is available as of Flash Player 8.

Loads a SWF, JPEG, GIF, or PNG file into a level while the original SWF file is playing. Support for unanimated GIF files, PNG files, and progressive JPEG files is added in Flash Player 8. If you load an animated GIF, only the first frame is displayed.

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 more information related to security, see the following:

Parameters
url:String — The absolute or relative URL of the SWF or JPEG file to be loaded. A relative path must be relative to the SWF file at level 0. For use in the stand-alone Flash Player or for testing in test mode in the Flash authoring application, all SWF files must be stored in the same folder and the filenames cannot include folder or disk drive specifications.
level:Number — An integer specifying the level in Flash Player into which the SWF file will load.
method:String [optional] — Specifies an HTTP method for sending variables. The parameter must be the string GET or POST . If there are no variables to be sent, omit this parameter. The GET method appends the variables to the end of the URL and is used for small numbers of variables. The POST method sends the variables in a separate HTTP header and is used for long strings of variables.

Example
The following example loads the JPEG image tim.jpg into level 2 of Flash Player:

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

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


loadVariables Function

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

Player version:  Flash Player 4 — Behavior changed in Flash Player 7.

Reads data from an external file, such as a text file or text generated by ColdFusion, a CGI script, Active Server Pages (ASP), PHP, or Perl script, and sets the values for variables in a target movie clip. This action can also be used to update variables in the active SWF file with new values.

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=Adobe&address=601+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 "Understanding Security" in Learning ActionScript 2.0 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 Learning ActionScript 2.0 in Flash.

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

Parameters
url:String — An absolute or relative URL where the variables are located. If the SWF file issuing this call is running in a web browser, url must be in the same domain as the SWF file; for details, see the Description section.
target:Object — The target path to a movie clip that receives the loaded variables.
method:String [optional] — Specifies an HTTP method for sending variables. The parameter must be the string GET or POST . If there are no variables to be sent, omit this parameter. The GET method appends the variables to the end of the URL and is used for small numbers of variables. The POST method sends the variables in a separate HTTP header and is used for long strings of variables.

Example
The following example loads information from a text file called params.txt into the target_mc movie clip that is created using createEmptyMovieClip(). The setInterval() function is used to check the loading progress. The script checks for a variable in the params.txt file named done.
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

loadVariablesNum(url:String, level:Number, [method:String]) : Void

Player version:  Flash Player 4 — Behavior changed in Flash Player 7. Flash 4 files opened in Flash 5 or later are converted to use the correct syntax.

Reads data from an external file, such as a text file or text generated by ColdFusion, a CGI script, ASP, PHP, or a Perl script, and sets the values for variables in a Flash Player level. You can also use this function to update variables in the active SWF file with new values.

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

url must be in exactly the same domain as the SWF file that is issuing this call (see "Understanding Security" in Learning ActionScript 2.0 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 .

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

Parameters
url:String — An absolute or relative URL where the variables are located. If the SWF file issuing this call is running in a web browser, url must be in the same domain as the SWF file; for details, see the Description section.
level:Number — An integer specifying the level in Flash Player to receive the variables.
method:String [optional] — Specifies an HTTP method for sending variables. The parameter must be the string GET or POST . If there are no variables to be sent, omit this parameter. The GET method appends the variables to the end of the URL and is used for small numbers of variables. The POST method sends the variables in a separate HTTP header and is used for long strings of variables.

Example
The following example loads information from a text file called params.txt into the main Timeline of the SWF at level 2 in Flash Player. The variable names of the text fields must match the variable names in the params.txt file. The setInterval() function is used to check the progress of the data being loaded into the SWF. The script checks for a variable in the params.txt file named done.
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

mbchr(number:Number)

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

Player version:  Flash Player 4

Converts an ASCII code number to a multibyte character.

Parameters
number:Number — The number to convert to a multibyte character.

See also
    String.fromCharCode()


mblength Function

mblength(string:String) : Number

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

Player version:  Flash Player 4

Returns the length of the multibyte character string.

Parameters
string:String — The string to measure.

Returns
     Number — The length of the multibyte character string.

See also
    String class, String.length


mbord Function

mbord(character:String) : Number

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

Player version:  Flash Player 4

Converts the specified character to a multibyte number.

Parameters
character:String — The character to convert to a multibyte number.

Returns
     Number — The converted character.

See also
    String.charCodeAt()


mbsubstring Function

mbsubstring(value:String, index:Number, count:Number) : String

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

Player version:  Flash Player 4

Extracts a new multibyte character string from a multibyte character string.

Parameters
value:String — The multibyte string from which to extract a new multibyte string.
index:Number — The number of the first character to extract.
count:Number — The number of characters to include in the extracted string, not including the index character.

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

See also
    String.substr()


MMExecute Function

MMExecute("Flash JavaScript API command;":String) : String

Player version:  Flash Player 7

Lets you issue Flash JavaScript API (JSAPI) commands from ActionScript. In Flash MX2004 the MMExecute function can be called only by a movie that is used as a Flash Panel (file is stored in WindowSWF directory), by an XMLtoUI dialog box, or by the Custom UI of a component. JSAPI commands have no effect in the player, in test movie mode, or outside the authoring environment.

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 http://www.adobe.com/support/documentation/en/flash/, scroll down to Browse Flash 8 Documentation and then select the Extending tab.

Parameters
command:String — Any command that you can use in a Flash JavaScript (JSFL) file.

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

Example
The following command will output the number of items in the library of the current document to the trace window. You must run this example as a Flash panel because Flash files can't call MMExecute if they are run in either test movie or the browser. Now you can select your file from the bottom of the Window > Other Panels menu.

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

nextFrame() : Void

Player version:  Flash Player 2

Sends the playhead to the next frame.

Example
In the following example, when the user presses the Right or Down arrow key, the playhead goes to the next frame and stops. If the user presses the Left or Up arrow key, the playhead goes to the previous frame and stops. The listener is initialized to wait for the arrow key to be pressed, and the init variable is used to prevent the listener from being redefined if the playhead returns to Frame 1.
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

nextScene() : Void

Player version:  Flash Player 2

Sends the playhead to Frame 1 of the next scene.

Example
In the following example, when a user clicks the button that is created at runtime, the playhead is sent to Frame 1 of the next scene. Create two scenes, and enter the following ActionScript on Frame 1 of Scene 1.

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;
}
Make sure you place a stop() action on Frame 1 of Scene 2.

See also
    prevScene()


Number Function

Number(expression) : Number

Player version:  Flash Player 4 — Behavior changed in Flash Player 7.

Converts the parameter expression to a number and returns a value as described in the following list:

Parameters
expression:Object — An expression to convert to a number. Numbers or strings that begin with 0x are interpreted as hexadecimal values. Numbers or strings that begin with 0 are interpreted as octal values.

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

Example
In the following example, a text field is created on the Stage at runtime:
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

Object([value:Object]) : Object

Player version:  Flash Player 5

Creates a new empty object or converts the specified number, string, or Boolean value to an object. This command is equivalent to creating an object using the Object constructor (see "Constructor for the Object class").

Parameters
value:Object [optional] — A number, string, or Boolean value.

Returns
     Object — An object.

Example
In the following example, a new empty object is created, and then the object is populated with values:
var company:Object = new Object();
company.name = "Adobe";
company.address = "601 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
}

Player version:  Flash Player 2 — Flash 2. Not all events are supported in Flash 2.

Specifies the mouse event or keypress that triggers an action.

Parameters
mouseEvent:Object — A mouseEvent is a trigger called an event . When the event occurs, the statements following it within curly braces ({ }) execute. Any of the following values can be specified for the mouseEvent parameter:
  • press The mouse button is pressed while the pointer is over the button.
  • release The mouse button is released while the pointer is over the button.
  • releaseOutside While the pointer is over the button, the mouse button is pressed and then rolls outside the button area just before it is released. Both the press and the dragOut events always precede a releaseOutside event.
  • rollOut The pointer rolls outside the button area.
  • rollOver The mouse pointer rolls over the button.
  • dragOut While the pointer is over the button, the mouse button is pressed and then rolls outside the button area.
  • dragOver While the pointer is over the button, the mouse button has been pressed, then rolled outside the button, and then rolled back over the button.
  • keyPress "< key > " The specified keyboard key is pressed. For the key portion of the parameter, specify a key constant, as shown in the code hinting in the Actions Panel. You can use this parameter to intercept a key press, that is, to override any built-in behavior for the specified key. The button can be anywhere in your application, on or off the Stage. One limitation of this technique is that you can't apply the on() handler at runtime; you must do it at authoring time. Make sure that you select Control > Disable Keyboard Shortcuts, or certain keys with built-in behavior won't be overridden when you test the application using Control > Test Movie.
For a list of key constants, see the Key class.

Example
In the following script, the startDrag() function executes when the mouse is pressed, and the conditional script is executed when the mouse is released and the object is dropped:
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
}

Player version:  Flash Player 5

Triggers actions defined for a specific instance of a movie clip.

Parameters
movieEvent:Object — The movieEvent is a trigger called an event . When the event occurs, the statements following it within curly braces ({}) are executed. Any of the following values can be specified for the movieEvent parameter:
  • load The action is initiated as soon as the movie clip is instantiated and appears in the Timeline.
  • unload The action is initiated in the first frame after the movie clip is removed from the Timeline. The actions associated with the Unload movie clip event are processed before any actions are attached to the affected frame.
  • enterFrame The action is triggered continually at the frame rate of the movie clip. The actions associated with the enterFrame clip event are processed before any frame actions that are attached to the affected frames.
  • mouseMove The action is initiated every time the mouse is moved. Use the _xmouse and _ymouse properties to determine the current mouse position.
  • mouseDown The action is initiated when the left mouse button is pressed.
  • mouseUpThe action is initiated when the left mouse button is released.
  • keyDown The action is initiated when a key is pressed. Use Key.getCode() to retrieve information about the last key pressed.
  • keyUp The action is initiated when a key is released. Use the Key.getCode() method to retrieve information about the last key pressed.
  • data The action is initiated when data is received in a loadVariables() or loadMovie() action. When specified with a loadVariables() action, the data event occurs only once, when the last variable is loaded. When specified with a loadMovie() action, the data event occurs repeatedly, as each section of data is retrieved.

Example
The following example uses onClipEvent() with the keyDown movie event and is designed to be attached to a movie clip or button. The keyDown movie event is usually used with one or more methods and properties of the Key object. The following script uses Key.getCode() to find out which key the user has pressed; if the pressed key matches the Key.RIGHT property, the playhead is sent to the next frame; if the pressed key matches the Key.LEFT property, the playhead is sent to the previous frame.
onClipEvent (keyDown) {
    if (Key.getCode() == Key.RIGHT) {
        this._parent.nextFrame();
    } else if (Key.getCode() == Key.LEFT) {
        this._parent.prevFrame();
    }
}
The following example uses onClipEvent() with the load and mouseMove movie events. The _xmouse and _ymouse properties track the position of the mouse each time the mouse moves, which appears in the text field that's created at runtime.
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

ord(character:String) : Number

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

Player version:  Flash Player 4

Converts characters to ASCII code numbers.

Parameters
character:String — The character to convert to an ASCII code number.

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

See also
    String Class, String.charCodeAt()


parseFloat Function

parseFloat(string:String) : Number

Player version:  Flash Player 5

Converts a string to a floating-point number. The function reads, or parses, and returns the numbers in a string until it reaches a character that is not a part of the initial number. If the string does not begin with a number that can be parsed, parseFloat() returns NaN. White space preceding valid integers is ignored, as are trailing nonnumeric characters.

Parameters
string:String — The string to read and convert to a floating-point number.

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

Example
The following examples use the parseFloat() function to evaluate various types of numbers:
trace(parseFloat("-2")); // -2
trace(parseFloat("2.5")); // 2.5
trace(parseFloat(" 2.5")); // 2.5
trace(parseFloat("3.5e6")); // 3500000
trace(parseFloat("foobar")); // NaN
trace(parseFloat("3.75math")); // 3.75
trace(parseFloat("0garbage")); // 0

See also
    NaN, parseInt()


parseInt Function

parseInt(expression:String, [radix:Number]) : Number

Player version:  Flash Player 5

Converts a string to an integer. If the specified string in the parameters cannot be converted to a number, the function returns NaN. Strings beginning with 0x are interpreted as hexadecimal numbers. Integers beginning with 0 or specifying a radix of 8 are interpreted as octal numbers. White space preceding valid integers is ignored, as are trailing nonnumeric characters.

Parameters
expression:String — A string to convert to an integer.
radix:Number [optional] — An integer representing the radix (base) of the number to parse. Legal values are from 2 to 36.

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

Example
The examples in this section use the parseInt() function to evaluate various types of numbers.

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

play() : Void

Player version:  Flash Player 2

Moves the playhead forward in the Timeline.

Example
In the following example, there are two movie clip instances on the Stage with the instance names stop_mc and play_mc. The ActionScript stops the SWF file's playback when the stop_mc movie clip instance is clicked. Playback resumes when the play_mc instance is clicked.
this.stop_mc.onRelease = function() {
    stop();
};
this.play_mc.onRelease = function() {
    play();
};
trace("frame 1");

See also
    gotoAndPlay(), MovieClip.gotoAndPlay()


prevFrame Function

prevFrame() : Void

Player version:  Flash Player 2

Sends the playhead to the previous frame. If the current frame is Frame 1, the playhead does not move.

Example
When the user clicks a button called myBtn_btn and the following ActionScript is placed on a frame in the Timeline for that button, the playhead is sent to the previous frame:
stop();
this.myBtn_btn.onRelease = function(){
    prevFrame();
};

See also
    nextFrame(), MovieClip.prevFrame()


prevScene Function

prevScene() : Void

Player version:  Flash Player 2

Sends the playhead to Frame 1 of the previous scene.

See also
    nextScene()


print Function

print(target:Object, boundingBox:String) : Void

Player version:  Flash Player 4 — (4.0.20.0) If you are authoring for Flash Player 7 or later, you can create a PrintJob object, which gives you (and the user) more control over the printing process. For more information, see the PrintJob class entry.

Prints the target movie clip according to the boundaries specified in the parameter (bmovie, bmax, or bframe). If you want to print specific frames in the target movie clip, attach a #p frame label to those frames. Although print() results in higher quality prints than printAsBitmap() it cannot be used to print movie clips that use alpha transparencies or special color effects.

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.

Parameters
target:Object — The instance name of a movie clip to print. By default, all of the frames in the target instance can be printed. If you want to print specific frames in the movie clip, assign a #p frame label to those frames.
boundingBox:String — A modifier that sets the print area of the movie clip. Enclose this parameter in quotation marks (" or '), and specify one of the following values:

  • bmovie Designates the bounding box of a specific frame in a movie clip as the print area for all printable frames in the movie clip. Assign a #b frame label to the frame whose bounding box you want to use as the print area.
  • bmax Designates a composite of all the bounding boxes of all the printable frames as the print area. Specify bmax if the printable frames in your movie clip vary in size.
  • bframe Indicates that the bounding box of each printable frame should be used as the print area for that frame, which changes the print area for each frame and scales the objects to fit the print area. Use bframe if you have objects of different sizes in each frame and want each object to fill the printed page.

Example
The following example prints all of the printable frames in holder_mc with a print area defined by the bounding box of each frame:
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");
};
In the previous ActionScript, you could replace bframe with bmovie so that the print area is defined by the bounding box of a frame with the #b frame label attached.

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


printAsBitmap Function

printAsBitmap(target:Object, boundingBox:String) : Void

Player version:  Flash Player 4 — (4.0.20.0) If you are authoring for Flash Player 7 or later, you can create a PrintJob object, which gives you (and the user) more control over the printing process. For more information, see the PrintJob class entry.

Prints the target movie clip as a bitmap according to the boundaries specified in the parameter (bmovie, bmax, or bframe). Use printAsBitmap() to print movie clips that contain frames with objects that use transparency or color effects. The printAsBitmap() action prints at the highest available resolution of the printer in order to maintain as much definition and quality as possible.

If your movie clip does not contain alpha transparencies or color effects, Adobe 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.

Parameters
target:Object — The instance name of the movie clip to print. By default, all of the frames in the movie clip are printed. If you want to print specific frames in the movie clip, attach a #p frame label to those frames.
boundingBox:String — A modifier that sets the print area of the movie clip. Enclose this parameter in quotation marks (" or '), and specify one of the following values:
  • bmovie Designates the bounding box of a specific frame in a movie clip as the print area for all printable frames in the movie clip. Assign a #b frame label to the frame whose bounding box you want to use as the print area.
  • bmax Designates a composite of all the bounding boxes of all the printable frames as the print area. Specify the bmax parameter if the printable frames in your movie clip vary in size.
  • bframe Indicates that the bounding box of each printable frame should be used as the print area for that frame. This changes the print area for each frame and scales the objects to fit the print area. Use bframe if you have objects of different sizes in each frame and want each object to fill the printed page.

Example
The following example prints all of the printable frames in holder_mc with a print area defined by the bounding box of the frame:
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

printAsBitmapNum(level:Number, boundingBox:String) : Void

Player version:  Flash Player 5 — If you are authoring for Flash Player 7 or later, you can create a PrintJob object, which gives you (and the user) more control over the printing process. For more information, see the PrintJob class entry.

Prints a level in Flash Player as a bitmap according to the boundaries specified in the parameter (bmovie, bmax, or bframe). Use printAsBitmapNum() to print movie clips that contain frames with objects that use transparency or color effects. The printAsBitmapNum() action prints at the highest available resolution of the printer in order to maintain the highest possible definition and quality. To calculate the printable file size of a frame designated to be printed as a bitmap, multiply pixel width by pixel height by printer resolution.

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.

Parameters
level:Number — The level in Flash Player to print. By default, all of the frames in the level are printed. If you want to print specific frames in the level, assign a #p frame label to those frames.
boundingBox:String — A modifier that sets the print area of the movie clip. Enclose this parameter in quotation marks (" or '), and specify one of the following values:
  • bmovie Designates the bounding box of a specific frame in a movie clip as the print area for all of the printable frames in the movie clip. Assign a #b frame label to the frame whose bounding box you want to use as the print area.
  • bmax Designates a composite of all the bounding boxes of all the printable frames as the print area. Specify the bmax parameter if the printable frames in your movie clip vary in size.
  • bframe Indicates that the bounding box of each printable frame should be used as the print area for that frame. This changes the print area for each frame and scales the objects to fit the print area. Use bframe if you have objects of different sizes in each frame and you want each object to fill the printed page.

Example
The following example prints the contents of the Stage when the user clicks the button myBtn_btn. The area to print is defined by the bounding box of the frame.
myBtn_btn.onRelease = function(){
    printAsBitmapNum(0, "bframe")
};

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


printNum Function

printNum(level:Number, boundingBox:String) : Void

Player version:  Flash Player 5 — If you are authoring for Flash Player 7 or later, you can create a PrintJob object, which gives you (and the user) more control over the printing process. For more information, see the PrintJob class entry.

Prints the level in Flash Player according to the boundaries specified in the boundingBox parameter (bmovie, bmax, bframe). If you want to print specific frames in the target movie clip, attach a #p frame label to those frames. Although using printNum() results in higher quality prints than using printAsBitmapNum(), you cannot use printNum() to print movies with alpha transparencies or special color effects.

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.

Parameters
level:Number — The level in Flash Player to print. By default, all of the frames in the level are printed. If you want to print specific frames in the level, assign a #p frame label to those frames.
boundingBox:String — A modifier that sets the print area of the movie clip. Enclose this parameter in quotation marks (" or '), and specify one of the following values:
  • bmovie Designates the bounding box of a specific frame in a movie clip as the print area for all printable frames in the movie clip. Assign a #b frame label to the frame whose bounding box you want to use as the print area.
  • bmax Designates a composite of all the bounding boxes of all the printable frames as the print area. Specify the bmax parameter if the printable frames in your movie clip vary in size.
  • bframe Indicates that the bounding box of each printable frame should be used as the print area for that frame. This changes the print area for each frame and scales the objects to fit the print area. Use bframe if you have objects of different sizes in each frame and want each object to fill the printed page.

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


random Function

random(value:Number) : Number

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

Player version:  Flash Player 4

Returns a random integer between 0 and one less than the integer specified in the value parameter.

Parameters
value:Number — An integer.

Returns
     Number — A random integer.

Example
The following use of random() returns a value of 0, 1, 2, 3, or 4:
random(5);

See also
    Math.random()


removeMovieClip Function

removeMovieClip(target:Object)

Player version:  Flash Player 4

Deletes the specified movie clip.

Parameters
target:Object — The target path of a movie clip instance created with duplicateMovieClip() or the instance name of a movie clip created with MovieClip.attachMovie(), MovieClip.duplicateMovieClip(), or MovieClip.createEmptyMovieClip().

Example
The following example creates a new movie clip called myClip_mc and duplicates the movie clip. The second movie clip is called newClip_mc. Images are loaded into both movie clips. When a button, button_mc, is clicked, the duplicated movie clip is removed from the Stage.
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

Player version:  Flash Player 6

Calls a function or a method of an object at periodic intervals while a SWF file plays. You can use setInterval() to execute any function repetitively over time.

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.
These tips are discussed in further detail in the following paragraphs.

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.

Parameters
functionReference:Function — A reference to the function to be called.
interval:Number — The time in milliseconds between calls to the functionReference or methodName function passed in.

If interval is less than the SWF file's frame rate (for example, 10 frames per second [fps] is equal to 100 millisecond intervals), the interval function is called as close in time to the value of interval as possible. Executing long, memory-intensive scripts during an interval causes delays. If the function being called initiates a change to visual elements, you should use the updateAfterEvent() function to make sure that the screen refreshes often enough. If interval is greater than the SWF file's frame rate, the interval function is called only after interval has expired and the playhead has entered the next frame; this minimizes the impact each time the screen is refreshed.

param:Object [optional] — Parameters passed to the function that was sent to functionReference or methodName. Multiple parameters should be separated by commas: param1 , param2 , ..., paramN
objectReference:Object — An object that contains the method specified by methodName. You must include this parameter when using setInterval() in an <mx:Script> block in Flex applications.
methodName:String — A method that exists in the scope of the object specified by objectReference.

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

Example
Example 1: The following example traces a message at an interval of 20 milliseconds, up to 10 times, and then clears the interval. The object scope, this, is passed in as the first parameter, and the method name, executeCallback, as the second. This ensures that executeCallback() is executed from the same scope as the calling script.

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

Example 2: The following example is similar to the first, except that it calls clearInterval() before setInterval(). This can help prevent unwanted loops and is especially important in event-based systems where the initiating script can be executed multiple times before any particular interval has been cleared.

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

Example 3: The following example shows how to pass a custom argument to the function that is being called.

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

Example 4: The following example shows how to use setInterval() correctly from an ActionScript 2.0 custom class. Note that similar to previous examples, this is passed to the setInterval() function to ensure that the called method is executed within the correct scope.

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

In a new document, instantiate a new instance of the new class:

var custom:CustomClass = new CustomClass();

See also
    clearInterval(), updateAfterEvent(), class


setProperty Function

setProperty(target:Object, property:Object, expression:Object) : Void

Player version:  Flash Player 4

Changes a property value of a movie clip as the movie clip plays.

Parameters
target:Object — The path to the instance name of the movie clip whose property is to be set.
property:Object — The property to be set.
expression:Object — Either the new literal value of the property, or an equation that evaluates to the new value of the property.

Example
The following ActionScript creates a new movie clip and loads an image into it. The _xand _y coordinates are set for the clip using setProperty(). When you click the button called right_btn, the _x coordinate of a movie clip named params_mc is incremented by 20 pixels.
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

setTimeout() : Number

Player version:  Flash Player 8

Runs a specified function after a specified delay (in milliseconds). The setTimeout() function is similar to the setInterval() function, except that setTimeout() calls the function once and then is automatically deleted.

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.

Parameters
functionReference:Object — The name of the function to execute. Do not include quotation marks or parentheses, and do not specify parameters of the function to call. For example, use functionName, not functionName() or functionName(param).
delay:Number — The delay, in milliseconds, until the function is executed.
args:Object — Zero or more arguments, separated by commas, to be passed to the function.

Returns
     Number — Unique numeric identifier for the timed process.

Example
The following example uses setTimeout() to call a function named my_delayedFunction after a two(2) second delay, and uses the return value to call clearTimeout() if the user presses the Escape key. The example will output the string "two second delay" after two seconds has elapsed, unless the user presses the Escape key before my_delayedFunction is called.
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

showRedrawRegions(enable:Boolean, [color:Number]) : Void

Player version:  Flash Player 8

Provides the ability for the debugger player to outline the regions of the screen that are being redrawn (that is, dirty regions that are being updated). The outlines can also be turned on with the Show Redraw Regions menu option.

Parameters
enable:Boolean — Specifies whether to enable (true) or disable (false) redraw regions. When set to true, the redraw rectangles are shown. When set to false, the redraw rectangles are cleared.
color:Number [optional] — The color to draw with. The default is red: 0xFF0000.

Example
The following example demonstrates the 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

startDrag(target:Object, [lock:Boolean, left:Number, top:Number, right:Number, bottom:Number]) : Void

Player version:  Flash Player 4

Makes the target movie clip draggable while the movie plays. Only one movie clip can be dragged at a time. After a startDrag() operation is executed, the movie clip remains draggable until it is explicitly stopped by stopDrag() or until a startDrag() action for another movie clip is called.

Parameters
target:Object — The target path of the movie clip to drag.
lock:Boolean [optional] — A Boolean value specifying whether the draggable movie clip is locked to the center of the mouse position (true ) or locked to the point where the user first clicked the movie clip (false ).
left,top,right,bottom:Number [optional] — Values relative to the coordinates of the movie clip's parent that specify a constraint rectangle for the movie clip.

Example
The following example creates a movie clip, pic_mc, at runtime that users can drag to any location by attaching the startDrag() and stopDrag() actions to the movie clip. An image is loaded into pic_mc using the MovieClipLoader class.
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

stop() : Void

Player version:  Flash Player 2

Stops the SWF file that is currently playing. The most common use of this action is to control movie clips with buttons.

See also
    gotoAndStop(), MovieClip.gotoAndStop()


stopAllSounds Function

stopAllSounds() : Void

Player version:  Flash Player 3

Stops all sounds currently playing in a SWF file without stopping the playhead. Sounds set to stream will resume playing as the playhead moves over the frames in which they are located.

Example
The following code creates a text field, in which the song's ID3 information appears. A new Sound object instance is created, and your MP3 is loaded into the SWF file. ID3 information is extracted from the sound file. When the user clicks stop_mc, the sound is paused. When the user clicks play_mc, the song resumes from its paused position.
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

stopDrag() : Void

Player version:  Flash Player 4

Stops the current drag operation.

Example
The following code, placed in the main Timeline, stops the drag action on the movie clip instance my_mc when the user releases the mouse button:
my_mc.onPress = function () {
    startDrag(this);
}

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

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


String Function

String(expression:Object) : String

Player version:  Flash Player 4 — Behavior changed in Flash Player 7.

Returns a string representation of the specified parameter, as described in the following list:

If expression is undefined, the return values are as follows:

If expression is undefined, the return value is undefined.

Note: Slash notation is not supported by ActionScript 2.0.

Note: Slash notation is not supported in Flex applications.

Parameters
expression:Object — An expression to convert to a string.

Returns
     String — A string.

Example
In the following example, you use ActionScript to convert specified expressions to a string:
var string1:String = String("3");
var string2:String = String("9");
trace(string1+string2);  // 39
Because both parameters are strings, the values are concatenated rather than added.

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


substring Function

substring(string:String, index:Number, count:Number) : String

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

Player version:  Flash Player 4

Extracts part of a string. This function is one-based, whereas the String object methods are zero-based.

Parameters
string:String — The string from which to extract the new string.
index:Number — The number of the first character to extract.
count:Number — The number of characters to include in the extracted string, not including the index character.

Returns
     String — The extracted substring.

See also
    String.substr()


targetPath Function

targetPath(targetObject:Object) : String

Player version:  Flash Player 5 — Support for Button, TextField, and Video objects added in Flash Player 6.

Returns a string containing the target path of a MovieClip, Button, TextField, or Video object. The target path is returned in dot (.) notation. To retrieve the target path in slash (/) notation, use the _target property.

Parameters
targetObject:Object — Reference (for example, _root or _parent ) to the object for which the target path is being retrieved. This can be a MovieClip, Button, or TextField object.

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

Example
The following example traces the target path of a movie clip as soon as it loads:
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 — Adobe recommends that you use dot (.) notation and the with statement.

Player version:  Flash Player 3

Applies the instructions specified in the statements parameter to the Timeline specified in the target parameter. The tellTarget action is useful for navigation controls. Assign tellTarget to buttons that stop or start movie clips elsewhere on the Stage. You can also make movie clips go to a particular frame in that clip. For example, you might assign tellTarget to buttons that stop or start movie clips on the Stage or prompt movie clips to jump to a particular frame.

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.

Parameters
target:String — A string that specifies the target path of the Timeline to be controlled.
statement(s) — The instructions to execute if the condition is true.

Example
This tellTarget statement controls the movie clip instance ball on the main Timeline. Frame 1 of the ball instance is blank and has a stop() action so it isn't visible on the Stage. When you click the button with the following action, tellTarget tells the playhead in ball to go to Frame 2, where the animation starts:
    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

toggleHighQuality()

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

Player version:  Flash Player 2

Turns anti-aliasing on and off in Flash Player. Anti-aliasing smooths the edges of objects and slows down SWF playback. This action affects all SWF files in Flash Player.

Example
The following code could be applied to a button that, when clicked, would toggle anti-aliasing on and off:
    on(release) {
        toggleHighQuality();
    }
    

See also
    _highquality, _quality


trace Function

trace(expression:Object)

Player version:  Flash Player 4

You can use Flash Debug Player to capture output from the trace() function and display the result. If any argument in a trace statement includes a data type other than a String, the trace function invokes the associated toString() method for that data type. For example, if the argument is a Boolean value the trace function invokes Boolean.toString() and displays the return value.

Use this statement to record programming notes or to display messages in the Output panel while testing a SWF file. Use the expression parameter to check whether a condition exists, or to display values in the Output panel. The trace() statement is similar to the alert function in JavaScript.

Use this statement to record programming notes or to write messages in the log file. Use the expression parameter to check whether a condition exists, or to write values to the log file.

You can use the Omit Trace Actions command in the Publish Settings dialog box to remove trace()actions from the exported SWF file.

Parameters
expression:Object — An expression to evaluate. When a SWF file is opened in the Flash authoring tool (using the Test Movie command), the value of the expression parameter is displayed in the Output panel.

Example
The following example uses a trace() statement to display in the Output panel the methods and properties of the dynamically created text field called error_txt: The following example uses a trace() statement to write the methods and properties of the dynamically created text field called error_txt to the log file:
this.createTextField("error_txt", this.getNextHighestDepth(), 0, 0, 100, 22);
for (var i in error_txt) {
trace("error_txt."+i+" = "+error_txt[i]);
}
/*
error_txt.styleSheet = undefined
error_txt.mouseWheelEnabled = true
error_txt.condenseWhite = false
...
error_txt.maxscroll = 1
error_txt.scroll = 1
*/


unescape Function

unescape(string:String) : String

Player version:  Flash Player 5

Evaluates the parameter x as a string, decodes the string from URL-encoded format (converting all hexadecimal sequences to ASCII characters), and returns the string.

Parameters
string:String — A string with hexadecimal sequences to escape.

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

Example
The following example shows the escape-to-unescape conversion process:

var email:String = "user@somedomain.com";
trace(email);
var escapedEmail:String = escape(email);
trace(escapedEmail);
var unescapedEmail:String = unescape(escapedEmail);
trace(unescapedEmail);
The following result is displayed in the Output panel. The following result is written to the log file.
user@somedomain.com
user%40somedomain%2Ecom
user@somedomain.com


unloadMovie Function

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

Player version:  Flash Player 3

Removes a movie clip that was loaded by means of loadMovie() from Flash Player. To unload a movie clip that was loaded by means of loadMovieNum(), use unloadMovieNum() instead of unloadMovie().

Parameters
target:Object — The target path of a movie clip. This parameter can be either a String (e.g. "my_mc") or a direct reference to the movie clip instance (e.g. my_mc). Parameters that can accept more than one data type are listed as type Object.

Example
The following example creates a new movie clip called pic_mc and loads an image into that clip. It is loaded using the MovieClipLoader class. When you click the image, the movie clip unloads from the SWF file:
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

unloadMovieNum(level:Number) : Void

Player version:  Flash Player 3

Removes a SWF or image that was loaded by means of loadMovieNum() from Flash Player. To unload a SWF or image that was loaded with MovieClip.loadMovie(), use unloadMovie() instead of unloadMovieNum().

Parameters
level:Number — The level (_level N ) of a loaded movie.

Example
The following example loads an image into a SWF file. When you click unload_btn, the loaded content is removed.
loadMovieNum("yourimage.jpg", 1);
unload_btn.onRelease = function() {
    unloadMovieNum(1);
}

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


updateAfterEvent Function

updateAfterEvent() : Void

Player version:  Flash Player 5

Updates the display (independent of the frames per second set for the movie) when you call it within an onClipEvent() handler or as part of a function or method that you pass to setInterval(). Flash ignores calls to updateAfterEvent that are not within an onClipEvent() handler or part of a function or method passed to setInterval(). This function works only with certain Mouse and MovieClip handlers: the mouseDown, mouseUp, mouseMove, keyDown and keyUp handlers for the Mouse class; the onMouseMove, onMouseDown, onMouseUp, onKeyDown, and onKeyUp handlers for the MovieClip class. It does not work with the Key class.

Example
The following example show how to create a custom cursor called cursor_mc. ActionScript is used to replace the mouse cursor with cursor_mc. Then updateAfterEvent() is used to continually refresh the Stage to make the cursor's movement appear smooth.
Mouse.hide();
cursor_mc.onMouseMove = function() {
    this._x = this._parent._xmouse;
    this._y = this._parent._ymouse;
    updateAfterEvent();
};

See also
    onClipEvent(), setInterval()