Using Functions in ActionScript 3.0

By Blue_Chi | Flash CS3 | ActionScript 3.0 | Beginner

Functions are fundamental tools used in ActionScript to reduce the amount of written code, save time, and add a logical structure to your code. This tutorial will describe the basic usage of functions in ActionScript 3.0.

This is an ActionScript 3.0 tutorial. To learn about using Functions in AS2 please review our tutorial on that topic.

Our tutorial is divided into these sections:

What is a function?

A function is a block of code wrapped together in a way so that it can be re-used at anytime in the code. It is used to save time as repeated tasks can be written only once and then called multiple times. It centralizes the code so that all of it is placed in a specific place that can be easily updated without having to manually modify each time the code is used. Using functions also makes reading the code by humans easier as it could be used to logically arrange code performing a collective task in a single place.

Function Code Example

For example, say that you want to create an instance of a certain Star object, set its x and y properties, and add it to the display list. You can do that by using the code below:

var myStar:Star;

myStar = new Star();
myStar.x = 100;
myStar.y = 150;

addChild(myStar);
The Star Class is an imaginary class, it does not exist in the default set of Flash Player classes.
You can learn more about AS3 Variables by reviewing our tutorial on this topic.
You can learn more about the Display List by reviewing our tutorial on this topic.

Now if you want to create another square using the same variable, set its x and y properties, and add it to the display list. You would have to repeat most of the code again:

var myStar:Star;

myStar = new Star();
myStar.x = 100;
myStar.y = 150;
addChild(myStar);

myStar = new Square();
myStar.x = 100;
myStar.y = 150;

addChild(myStar);

You would then have to repeat the same code multiple times each time you want to add a new square to the screen. This is a tiresome job and would end up in the creation of massive identical code. In order to avoid duplicating the same code, you can create a function. This function will have the core code you need and then you can reuse it multiple times to repeat the code:

var myStar:Star;

function makeStar():void {
myStar = new Star();
myStar.x = 100;
myStar.y = 150;
addChild(myStar);
}

makeStar();
makeStar();

The code above will create two stars because the function has been called twice. The section below will explain how this works in detail.

Function Basics

Any function could be written using the generalized code shown below:

function functionName(argument):returnType{
statements;
}

The first requirement for creating a function is to use the function keyword. You simply follow this by the name you want your function to have. You can almost use any name for this. We are going to use the name magicalFunction:

function magicalFunction(){
}

The code which the function will execute must be written between the curly brackets {}. We are going to make this function create a new MovieClip and set its .x and .y properties:

function magicalFunction(){
var myMovie:MovieClip = new MovieClip();
myMovie.x=100;
myMovie.y=150;

}

The process for creating a function is called defining a function, in order to use a function you need to invoke it. Invoking the function is a separate process that requires you to type the function name followed by two brackets:

function magicalFunction(){
var myMovie:MovieClip = new MovieClip();
myMovie.x=100;
myMovie.y=150;
}

magicalFunction();

That last command will execute your function, you can simply type magicalFunction anytime you wish to create new MovieClip and set its x and y properties to 100 and 150 respectively. You must always remember to invoke your function because simply defining it will not execute any code.

Advanced Function Features

You might have noticed that our earlier function was a generic code that contained a number of parameters which we did not use:

function functionName(argument):returnType{
statements;
}

The first of these is the argument parameter, using this feature lets you create flexible functions which can be reused to carry out a unique action each time the function is invoked. An argument can hold a reference to an object or variable which will be passed when the function is invoked so that it can be used with different objects or variables.

To make things clearer, we might want to create Star objects which are created at a different position each time a new one is created, our previous code would have created stars that were positioned directly over each other:

var myStar:Star;

function makeStar():void {
myStar = new Star();
myStar.x = 100;
myStar.y = 150;
addChild(myStar);
}

makeStar();
makeStar();

We can pass an argument to the function so that we specify the x and y values when the function is called by specifying these values between the brackets:

var myStar:Star;

function makeStar(myX:Number, myY:Number):void {
myStar = new Star();
myStar.x = myX;
myStar.y = myY;
addChild(myStar);
}

makeStar();
makeStar();

You should notice that our function does not have any actual value for the myX and myY variables, these can be specified when the function is invoked, and not only that, but you can specify different values each time you invoke the function:

var myStar:Star;

function makeStar(myX:Number, myY:Number):void {
myStar = new Star();
myStar.x = myX;
myStar.y = myY;
addChild(myStar);
}

makeStar(100,200);
makeStar(150,320);

Using the code above, the first star will be placed at 100, 200 while the second one will be placed at 150, 320. This shows the power and flexibility of functions, it can be further modified so that it creates a different shape or a different star size depending on what values the user specifies when the function is invoked.

In addition to this, a function can be used to perform a process and then return a result. This is an advanced technique, a very basic example of it is as follows:

function calculate(){
var num1:Number = 50;
var num2:Number = 100;
var myResult:Number;

myResult = num1+num2;
return myResult;
}

This value can then be used in various situations for example, you can now set this function as the x property of an object you wish to position at that number. You know that num1+num2 will equal 150, so the object will be positioned at 150.

function calculate(){
var num1:Number = 50;
var num2:Number = 100;
var myResult:Number;

myResult = num1+num2;
return myResult;
}

var myMC:MovieClip = new MovieClip();
myMC.x = calculate();

This is not a practical example, but it is just intended to show you that a function can be used to process variables and then output that value. What is important to know is that you should always specify the type of value your function is supposed to return. The example above returns a number, so you should specify that the return value of this function is a number data type. You specify this data type by using the colon : and the data type after the function brackets:

function calculate():Number{
var num1:Number = 50;
var num2:Number = 100;
var myResult:Number;

myResult = num1+num2;
return myResult;
}

var myMC:MovieClip = new MovieClip();
myMC.x = calculate();

The majority of all functions created will not return a value, so you should always make that clear by specifying that the return value of the function is void meaning that no value is returned. You might have noticed this from our examples above:

var myStar:Star;

function makeStar(myX:Number, myY:Number):void {
myStar = new Star();
myStar.x = myX;
myStar.y = myY;
addChild(myStar);
}

makeStar(100,200);
makeStar(150,320);

Specifying the data type as void when no return value is expected is good AS3 practice, make sure you do it all the time.

Final Comment About Function Variables

You should be aware of the effect of creating a variable inside a function. Using the var keyword inside a function will lead to the creation of a local variable that will not be accessible outside the function. For example, in the code below, the variable myResult will not be accessible from outside the function:

function calculate ():Number {

var num1:Number = 50;
var num2:Number = 100;
var myResult:Number;
myResult = num1+num2;

}

If you try to access the myResult variable outside the function, you will receive an error message:

function calculate ():Number {

var num1:Number = 50;
var num2:Number = 100;
var myResult:Number;
myResult = num1+num2;

}

trace(myResult); // THIS WILL GENERATE AN ERROR - MYRESULT DOES NOT EXIST OUTSIDE THE FUNCTION.

If you would like to have your variable accessible outside you function you will have to define it outside the function and then simply modify it from inside the function:

var myResult:Number;

function calculate ():Number {

var num1:Number = 50;
var num2:Number = 100;
myResult = num1+num2;

}

trace(myResult); // THIS WILL NOT GENERATE AN ERROR.

This is an important point to note as you might be tempted to create variables inside your function thinking that you can access them later, but you cannot. Make sure you define all the variables you wish to use throughout your movie at the start of your code outside any function to make sure that it becomes a permanent variable.

This concludes our tutorial, I hope that you've learnt something new from it. Feel free to post any questions you have at the Republic of Code forum.

- End of Tutorial.