Macromedia Flash 8 Bible

What Functions Do

A function (or procedure) sets aside a block of code that can be executed with just one line of code. Functions can execute several actions, and pass options (called arguments or parameters) to those actions. All functions must have a unique name, so that you know what to reference in later lines of code. In a way, functions are equivalent to your own custom additions to the Flash ActionScript language. In ActionScript, you can define a function on a specific timeline, and refer to its path and name to execute it.

When to Create a Function

For people new to scripting, perhaps the most confusing aspect of functions is knowing when to create them in a Flash movie. Use the following guidelines to help you determine when a function should be created:

• If you find yourself reusing the same lines of code on several Button instances, MovieClip objects, or keyframes, then you should consider moving the actions to a function. In general, you should not pile up ActionScript on any single Button or Movie Clip instance.

• If you need to perform the same operation throughout a Flash movie, such as hiding specific Movie Clip instances on the Stage, you should consider defining a function to take care of the work for you.

• When you need to perform operations to determine a value (such as determining the current day of the week or calculating values in a mathematical formula), you should move the operations to a function.

How to Define a Function

When you add a function to a keyframe on the Main Timeline or a Movie Clip timeline, you are defining the function. All functions have a target path, just like other objects in ActionScript. All functions need a name followed by opening and closing parentheses, but arguments (options to pass to the function) inside the parentheses are optional.

As a simple example, let's say you want to create a function that has one gotoAndStop() action. This function will have a shorter name than gotoAndStop(), and will be faster to type and use in your ActionScript code. Place this code on the first keyframe of the Main Timeline.

function gts():Void {
     this.gotoAndStop("start");
}

This function, when evoked, will send the current timeline Playhead to the start label You could further expand the functionality of gts() by adding an argument, which we'll call frameLabel:

function gts(frameLabel:String):Void {
     this.gotoAndStop(frameLabel);
}

In this version of the gts() function, instead of hard-coding a frame label such as start into the actual gotoAndStop() action, you specify an argument with the name frameLabel. Just like variable names, the names of your function and its arguments are entirely up to you — the name frameLabel has no significance. ActionScript simply knows that if you pass an argument to the gts() function, that it should place that argument where the frameLabel term occurs in your actions. An argument acts as a placeholder for information that will be supplied to the function on a per-use basis; that is, you can specify a different value for frameLabel each time you evoke the gts() function. You can also use as many (or as few) arguments as you need. Insert a comma between each argument in the function declaration:

function calculateRange (min:Number, max:Number):Number{
   var diff:Number = Math.abs(max - min);
   return diff;
}

How to Execute a Function

After you have defined a function on a timeline's keyframe, you can create actions that refer to the function's actions. The standard method for executing a function is:

path_to_function.functionName(arguments);

At the end of the previous section, you defined a function named gts() on the Main Timeline. If you added a Button instance to your movie, you could then execute the function from the Button instance with the following code:

on(release){
     this.gts("start");
}

When this Button instance is clicked, the function gts() on the current timeline (this) is executed, and passed the argument "start". In your function gts(), you defined frameLabel as an argument that occurs in the gotoAndStop() action. Therefore, the Main Timeline will go to and stop on the "start" frame label.