Recipe 12.2 Creating an Instance of a Class

12.2.1 Problem

You want to access the properties and methods of a class to achieve a particular goal, but those properties and methods are specific to a particular object (i.e., an instance of the class).

12.2.2 Solution

Create a instance of the class using the new operator and the constructor function for the class of interest. Then access the properties and methods of the instance, as returned by the constructor function.

12.2.3 Discussion

Many ActionScript classes must be instantiated before you can use them. This means that you must create an object that is based on the blueprint defined by the class. For example, the Array class defines the blueprint for all arrays. All arrays have the same kinds of properties and methods; however, each array instance is an individual object that merely inherits the common properties and methods from the class. It is important that each instance be individualized so that when you request the value for arrayA.length, you retrieve the length of arrayA and not the length of some other array, such as arrayB.

To create an instance of a class, you typically use the new operator with the appropriate constructor function for the class. The constructor function takes the same name as the class itself and is followed by the function operator (that is, parentheses). For example, the following creates a new generic instance of the Object class:

myObject = new Object(  );

Note that the new statement returns an instance of the class, which you ordinarily store in a variable, in this case myObject.

Most classes allow you to construct objects in an analogous manner. For example, here is one way to create a new Array object:

myArray = new Array(  );

As with all functions, constructor functions can accept parameters. In some cases, no parameters are accepted. In other cases, parameters are optional, and in still other cases, they are required. As you can see in the preceding example, you do not need to specify any parameters when constructing an array. However, the Array( ) constructor function accepts optional parameters of several varieties, as discussed in the Introduction to Chapter 6. This example constructs an array with two elements:

myArray = new Array("first element", "second element");

Once you have created an object (an instance), you can access the properties and methods of that object via dot syntax. For example, arrays have a length property that returns the number of elements:

trace(myArray.length);  // Displays: 2

Returning to the subject of specifying parameters when constructing an object, when you construct a Color object, you must provide the target movie clip as a parameter. For example:

myColor = new Color(myMovieClip);

See Recipe 3.1 for more details.

There are alternative ways to create certain types of objects without using the new operator. For example, using object literal notation, which employs curly braces, you can create a generic object. This example creates an object of the Object class:

myObj = {};

You can specify zero or more properties to add to the object within the curly braces. This example creates an object and adds two properties (x and y) to it:

myPoint = {x: 100, y: 50};
trace(myPoint.x);          // Displays: 100

Likewise, a new array can be created using array literal notation, which employs square brackets. This example creates an array with three elements:

myArray = ["a", "b", "c"];

There are other indirect ways to create objects. Most notably, some methods of existing objects return entirely new objects. For example, the Array.splice( ) method returns a new array (remember that arrays are one type of object). In this example, the call to myArray.splice( ) returns a second array containing the elements deleted from myArray, which we arbitrarily store in the variable deletedElems:

myArray = ["a", "b", "c", "d"];
// Remove two elements from myArray starting at index 0. The removed elements are
// stored in a new array, deletedElems.
deletedElems = myArray.splice(0, 2);

We've seen alternatives to using the new operator to construct an object. In fact, there are some classes that cannot be instantiated using a new operator, which necessitates an appropriate alternative. One alternative is to create an object in the authoring tool. For example, placing a movie clip on the Stage effectively creates an instance of the MovieClip class. Likewise, placing a text field on the Stage effectively creates an instance of the TextField class.

But what if you want to create a new text field object at authoring time? You might be tempted to use the following syntax, but it won't work:

myTextField = new TextField(  );  // This will not work!

Instead, you must invoke the createTextField( ) method on a movie clip object to create a new text field, as described in Recipe 8.2.

To create a new movie clip object, you might be tempted to use the following syntax:

myClip = new MovieClip(  );  // This creates a subclass, not a new clip!

However, the preceding example won't have the intended effect. Instead of creating a new movie clip, it actually creates a subclass, as described in Recipe 12.12. To create new movie clips at runtime, use the MovieClip.attachMovie( ) method, or alternatives, as described in Recipe 7.19.

We've seen a variety of ways to construct new objects, including using the new operator and a constructor function. The exceptions and special cases are discussed in appropriate recipes throughout the book.

12.2.4 See Also

Recipe 7.1, Recipe 7.19, Recipe 8.1, Recipe 8.2, Recipe 12.12, Recipe 16.1, and Recipe 16.6. Recipe 12.5 discusses how to define your own custom classes rather than merely instantiating objects of an existing class. Recipe 12.1 explains how to access the properties and methods of any class, whether custom or built-in. See the "Language Reference" section of ActionScript for Flash MX: The Definitive Guide, which documents the properties and methods of ActionScript's Array, Boolean, Button, Color, Date, Function, LocalConnection, LoadVars, MovieClip, Number, Object, Sound, String, TextField, TextFormat, XML, XMLnode, and XMLSocket classes in detail.