Function.apply()

Availability

Flash Player 6.

Usage

myFunction.apply(thisObject:Object, argumentsArray:Array)

Parameters

thisObject The object to which myFunction is applied.

argumentsArray An array whose elements are passed to myFunction as parameters.

Returns

Any value that the called function specifies.

Description

Method; specifies the value of this to be used within any function that ActionScript calls. This method also specifies the parameters to be passed to any called function. Because apply() is a method of the Function class, it is also a method of every Function object in ActionScript.

The parameters are specified as an Array object, unlike Function.call(), which specifies parameters as a comma-delimited list. This is often useful when the number of parameters to be passed is not known until the script actually executes.

Example

The following function invocations are equivalent:

Math.atan2(1, 0)
Math.atan2.apply(null, [1, 0])

The following simple example shows how apply() passes an array of parameters:

function theFunction() {
   trace(arguments);
}

// create a new array to pass as a parameter to apply()
var firstArray:Array = new Array(1,2,3);
theFunction.apply(null,firstArray);
// outputs: 1,2,3

// create a second array to pass as a parameter to apply()
var secondArray:Array = new Array("a", "b", "c");
theFunction.apply(null,secondArray);
// outputs a,b,c

The following example shows how apply() passes an array of parameters and specifies the value of this:

// define a function 
function theFunction() {
   trace("this == myObj? " + (this == myObj));
   trace("arguments: " + arguments);
}

// instantiate an object
var myObj:Object = new Object();

// create arrays to pass as a parameter to apply()
var firstArray:Array = new Array(1,2,3);
var secondArray:Array = new Array("a", "b", "c");

// use apply() to set the value of this to be myObj and send firstArray
theFunction.apply(myObj,firstArray);
// output: 
// this == myObj? true
// arguments: 1,2,3

// use apply() to set the value of this to be myObj and send secondArray
theFunction.apply(myObj,secondArray);
// output: 
// this == myObj? true
// arguments: a,b,c

See also

Function.call()

RSS feed | Send me an e-mail when comments are added to this page | Comment Report

Current page: http://livedocs.adobe.com/flash/mx2004/main_7_2/00001355.html

Add Comment