Writing Scripts with ActionScript > Creating custom functions

Creating custom functions

You can define functions to execute a series of statements on passed values. Your functions can also return values. Once a function is defined, it can be called from any Timeline, including the Timeline of a loaded movie.

A function can be thought of as a "black box": when a function is called, it is provided with input (arguments). It performs some operation and then generates output (a return value). A well-written function has carefully placed comments about its input, output, and purpose. This way, a user of the function does not need to understand exactly how the function works.


 
Defining a function

Functions, like variables, are attached to the movie clip that defines them. When a function is redefined, the new definition replaces the old definition.

To define a function, use the function action followed by the name of the function, any arguments to be passed to the function, and the ActionScript statements that indicate what the function does.

The following is a function named Circle with the argument radius:

function Circle(radius) {
	this.radius = radius;
	this.area = Math.PI * radius * radius;
}

Note: The keyword this, used in a function body, is a reference to the movie clip that the function belongs to.

You can also define a function by creating a function literal. A function literal is an unnamed function that is declared in an expression instead of in a statement. You can use a function literal to define a function, return its value, and assign it to a variable in one expression, as in the following:

area = (function () {return Math.PI * radius *radius;})(5);


 
Passing arguments to a function

Arguments are the elements on which a function executes its code. (In this book, the terms argument and parameter are interchangeable.) For example, the following function takes the arguments initials and finalScore:

function fillOutScorecard(initials, finalScore) {
	scorecard.display = initials;
	scorecard.score = finalScore;
}

When the function is called, the required arguments must be passed to the function. The function substitutes the passed values for the arguments in the function definition. In this example, scorecard is the instance name of a movie clip; display and score are input text fields in the instance. The following function call assigns the variable display the value "JEB" and the variable score the value 45000:

fillOutScorecard("JEB", 45000);

The argument initials in the function fillOutScorecard is similar to a local variable; it exists while the function is called and ceases to exist when the function exits. If you omit arguments during a function call, the omitted arguments are passed as undefined. If you provide extra arguments in a function call that are not required by the function declaration, they are ignored.


 
Using local variables in a function

Local variables are valuable tools for organizing code and making it easier to understand. When a function uses local variables, it can hide its variables from all other scripts in the movie; local variables are scoped to the body of the function and are destroyed when the function exits. Any arguments passed to a function are also treated as local variables.

Note: If you modify global variables in a function, use script comments to document these modifications.


 
Returning values from a function

You can use the return action to return values from functions. The return action stops the function and replaces it with the value of the return action. If Flash doesn't encounter a return action before the end of a function, an empty string is returned. For example, the following function returns the square of the argument x:

function sqr(x) {
	return x * x;
}

Some functions perform a series of tasks without returning a value. For example, the following function initializes a series of global variables:

function initialize() {
	boat_x = _root.boat._x;
	boat_y = _root.boat._y;
	car_x = _root.car._x;
	car_y = _root.car._y;
}


 
Calling a function

To invoke a function using the Actions panel in Normal Mode, you use the evaluate action. Pass the required arguments inside parentheses. You can call a function in any Timeline from any Timeline, including a loaded movie. For example, the following statement invokes the function sqr in movie clip MathLib on the main Timeline, passes it the argument 3, and stores the result in the variable temp:

var temp = _root.MathLib.sqr(3);

In Flash 4, to simulate calling a function you could write a script on a frame after the end of the movie and invoke it by passing the name of the frame label to the call action. For example, if a script that initialized variables was on a frame labeled initialize, you would call it as follows:

call("initialize");

This kind of script was not a true function because it could not accept arguments and it could not return a value. Although the call action still functions in Flash 5, its use is not recommended.