Passing parameters to a function

Parameters, also referred to as arguments, are the elements on which a function executes its code. (In this book, the terms parameter and argument are interchangeable.) You can pass parameters (values) to a function. You can then use these parameters for processing the function. You use the values within the function block (statements within the function).

Sometimes parameters are required, and sometimes they are optional. You might even have some required and some optional parameters in a single function. If you do not pass enough parameters to a function, Flash sets the missing parameter values to undefined, which may cause unexpected results in your SWF file.

The following function called myFunc() takes the parameter someText:

function myFunc(someText:String):Void {
    trace(someText);
}

After passing the parameter, you can pass a value to the function when you call the function. This value traces in the Output panel, as follows:

myFunc("This is what traces");

When you call the function, you should always pass the specified number of parameters unless your function checks for undefined values and sets default values accordingly. The function substitutes the passed values for the parameters in the function definition; if any parameters are missing, Flash sets their value to undefined. You regularly pass parameters into functions when you write ActionScript code.

You can also pass multiple parameters to a function, which can be as simple as the following:

var birthday:Date = new Date(1901, 2, 3);
trace(birthday);

Each parameter is separated by a comma delimiter. Many built-in functions in the ActionScript language have multiple parameters. For example, the startDrag() method of the MovieClip class takes five parameters, lockCenter, left, top, right, and bottom:

startDrag(lockCenter:Boolean, left:Number, top:Number, right:Number, bottom:Number):Void

To pass a parameter to a function:

Create a new Flash document and save it as parameters.fla.
Add the following code to Frame 1 of the Timeline:
```
function traceMe(yourMessage:String):Void {
    trace(yourMessage);
}
traceMe("How are you doing?");
```
The first few lines of code create a user-defined function called traceMe(), which takes a single parameter, yourMessage. The last line of code calls the traceMe() function and passes the string value "How are you doing?".
Select Control > Test Movie to test the Flash document.

The next example demonstrates how to pass multiple parameters to a function.

To pass multiple parameters to a function:

Create a new Flash document and save it as functionTest.fla.
Add the following code to Frame 1 of the main Timeline:
```
function getArea(width:Number, height:Number):Number {
     return width * height;
}
```
The getArea() function takes two parameters, width and height.
Type the following code after the function:
```
var area:Number = getArea(10, 12);
trace(area); // 120 
```
The getArea() function call assigns the values 10 and 12 to the width and height, respectively, and you save the return value in the area instance. Then you trace the values that you save in the area instance.
Select Control > Test Movie to test the SWF file.
You see 120 in the Output panel.

The parameters in the getArea() function are similar to values in a local variable; they exist while the function is called and cease to exist when the function exits.

In the next example, the ActionScript returns the value NaN (not a number) if you don't pass enough parameters to the addNumbers() function.

To pass a variable number of parameters to a function:

Create a new Flash document and save it as functionTest2.fla.
Add the following code to Frame 1 of the main Timeline:
```
function addNumbers(a:Number, b:Number, c:Number):Number {
    return (a + b + c);
}
trace(addNumbers(1, 4, 6)); // 11
trace(addNumbers(1, 4)); // NaN (Not a Number), c equals undefined
trace(addNumbers(1, 4, 6, 8)); // 11
```
If you don't pass enough parameters to the addNumbers function, the missing arguments are assigned a default value of undefined. If you pass too many parameters, the excess parameters are ignored.
Select Control > Test Movie to test the Flash document.
Flash displays the following values: 11, NaN, 11.

Flash CS3