home | O'Reilly's CD bookshelfs | FreeBSD | Linux | Cisco | Cisco Exam  


Book HomeActionScript: The Definitive GuideSearch this book

9.3. Passing Information to Functions

In the last section, we created a function that executed a simple trace( ) statement -- not exactly the most compelling specimen of the function species. Here's a more interesting function that moves a movie clip instance named ball a short distance:

function moveBall ( ) {
  ball._x += 10;
  ball._  y += 10;
}

With the function moveBall( ) defined, we can move ball diagonally anytime by calling the moveBall( ) function:

moveBall( );

The ball moves diagonally down and to the right. (Note that the origin (0, 0) is in the upper left of the main Stage. Increasing values of _x move the ball to the right, but unlike the Cartesian coordinates, increasing values of _ y move the ball down, not up.)

Our moveBall( ) function is convenient, but it lacks flexibility. It works only on one movie clip (ball), it moves ball in only one direction, and it always moves ball the same distance.

A well-designed function should define a single code segment that works in many circumstances. We can generalize our moveBall( ) function so that it can move any clip any distance in any direction. The first step in generalizing any function is determining what factors control its behavior. In our moveBall( ) function, the factors are the name of the movie clip to move, the distance to move it horizontally, and the distance to move it vertically. Such factors are known as the parameters of the function -- they're the information that we'd like to be able to adjust when the function is called.

9.3.1. Creating Functions with Parameters

Recall the generic syntax of a simple function declaration:

function funcName ( ) {
  statements
}

To add parameters, which are variables that can be used within a function, we provide a list of legal identifiers between the parentheses of a function declaration. Parameters are separated by commas as shown here:

function funcName (param1, param2, param3,...paramn) {
  statements
}

Once defined, we can access a function's parameter values from inside the function body just as we would any other variable. For example:

function say(msg) {                // Define the msg parameter
  trace("The message is " + msg);  // Use msg within the trace( ) statement
}

Our function declaration defines the parameter msg. The trace( ) statement uses the parameter as it would any variable, outputting its value to the Output window.

Let's use parameters with our moveBall( ) function so that we can set the clip's name, horizontal distance, and vertical distance differently each time it runs. Example 9-1 shows the code.

Example 9-1. A Generalized moveClip Function

function moveClip (theClip, xDist, yDist) {
  theClip._x += xDist;
  theClip._y += yDist;
}

We renamed the function from moveBall( ) to the generic name moveClip( ). We also defined three parameters: theClip (the movie clip we want to move), xDist (the horizontal distance to move), and yDist (the vertical distance to move). Inside the function body, we use those parameters instead of the hardcoded values in the original example, thereby allowing our function to reposition any clip by any horizontal and vertical distance.

9.3.2. Invoking Functions with Parameters

When we create a function, we define the parameter names, which are essentially placeholders; when we invoke the function, we'll provide values to be plugged in for each of the parameters.

The words parameters and arguments are used interchangeably in this book and in most documentation. Technically, arguments are the values used when invoking a function, and parameters are the placeholders in the function that "receive" the arguments.

Recall the generic syntax of function invocation with no arguments:

funcName( )

To supply (or pass) arguments to a function, we provide a list of values within the parentheses when invoking the function:

funcName(arg1, arg2, arg3,...argn)

The values used as arguments may be any legitimate expression in ActionScript, including compound expressions. For example, earlier we defined a simple function, say( ), that expects a single parameter, msg:

function say(msg) {
  trace("The message is " + msg);
}

To invoke say( ), we use a statement like this:

say("This is my first argument...how touching");

Or like this:

say(99);

Notice that the values, "This is my first argument . . . how touching" and 99, belong to different datatypes. ActionScript allows us to pass any data of any type to a function, as long as the function knows what to do with the passed value. (Languages such as C require that we predefine the datatype for each parameter, and they display an error if data of the wrong type is provided.)

Before each argument is passed, its value is fully resolved. We may, therefore, also invoke functions with complex expressions. For example:

var name = "Gula";
say("Welcome to my web site " + name);

Because the expression "Welcome to my web site " + name is evaluated before it is passed to the say( ) function, the function receives the resolved value "Welcome to my web site Gula". This means that we can programmatically generate function arguments. Powerful stuff.

To pass more than one argument to a function, we separate our arguments with commas. Recall that our moveClip( ) function from Example 9-1 accepts three parameters: theClip, xDist, yDist. Invoking moveClip( ), therefore, looks like this:

moveClip(ball, 5, -15);

Each of the three arguments is assigned as the value of the corresponding parameter named in the function declaration: ball is assigned to theClip, 5 is assigned to xDist, and -15 is assigned to yDist. We can move any clip any distance by invoking our generic moveClip( ) function with different arguments. Here we move the clip instance named square to the right 2 pixels and down 100 pixels:

moveClip(square, 2, 100);


Library Navigation Links

Copyright © 2002 O'Reilly & Associates. All rights reserved.