Overview of Functions as Procedures

A primary building block of any scripting or programming language is a procedure. A procedure is any set of code that you wish to reserve for a specific task. A procedure is useful for code that you wish to reuse in multiple event handlers (for example, Button instances and keyframes). In Flash ActionScript, procedures are called functions, and are created with the function action.

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.

Note 

For Flash Player 4-compatible movies, use the call() action to execute code blocks located on other keyframes in the Flash movie.

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.

Tip 

Functions are usually defined at the very beginning of a Flash movie. We recommend only defining functions on timeline keyframes — you can, however, execute functions from any event handler in a Flash movie.

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

Tip 

You can specify ActionScript 2.0 data typing on function arguments as well. Note that the Void data type is used to indicate that no value is returned from this function. We talk about return values from functions next.

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

Caution 

Beware of naming your functions (and arguments) after already existing ActionScript terms. If in doubt, you should probably choose a word that does not resemble any JavaScript syntax (with later upgrades to ActionScript in mind). You'll see many examples in tutorials or books in which programmers always prefix names with my, as in myColor or myLabel, to avoid any potential naming conflicts.

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.

Caution 

A function cannot be executed unless it was previously defined in the movie and recognized by the Flash Player. The keyframe containing the function declaration needs to be "played" before the function is available for use. For example, if you define a function on frame 10 of a Movie Clip instance that has stopped on frame 1 (and never played to frame 10), the Flash Player will not have registered the function in memory. For this reason, it's usually a good idea to place your functions on the first frame of the Flash movie, or at a location where they will be initialized before you need to use them.