Recipe 12.3 Adding Properties to an Object Instance

12.3.1 Problem

You want to add custom properties (variables) to an object (an instance of a class).

12.3.2 Solution

Attach the new property to the object using an assignment statement and the dot operator.

12.3.3 Discussion

Objects derived from the built-in ActionScript classes have standard properties. For example, arrays have length properties, movie clips have _x and _y properties, and Sound objects have position and duration properties. But aside from these standard properties, you can add custom properties to any object in ActionScript. You can add new properties to an object (or change an existing property's value) by simply assigning the property a value. If the property does not yet exist, ActionScript creates it automatically.

myMovieClip.myProperty = "some value";

Custom properties of movie clip objects are sometimes referred to as timeline variables, as discussed in Recipe 1.12. However, you can apply the same principle not only to movie clip objects, but to any kind of object. For example, the following code adds a custom property to an array named myArray:

myArray.myProperty = "some value";

Attaching properties to objects is invaluable. For example, custom properties can store a value that is used internally within an event handler method (or any other method) of the object. You can initialize the property value outside any of the methods and then access it within a method. This technique creates a variable whose value persists between function invocations for the life of the object. For example:

// Initialize a clickedTimes property to 0. This happens only once.
myMovieClip.clickedTimes = 0;

// Increment the clickedTimes property whenever the movie clip is clicked. 
myMovieClip.onPress = function (  ) {
  this.clickedTimes++;
};

Another valuable reason for creating custom properties is to establish relationships between objects. Only movie clips can be targeted using relative paths. By creating a property of one object, objectA, that is a reference to another object, objectB, objectA can use or call objectB from within its methods in a relative fashion (without requiring the fully qualified target path). In this example, the targetArray property stored in the LoadVars object offers a convenient, relative way to access newArray:

// Create an array.
myArray = new Array(  );

// Create a LoadVars object.
lv = new LoadVars(  );

// Assign myArray to a custom property of the LoadVars object.
lv.targetArray = myArray;

// When the data from the server loads into the LoadVars object, use the targetArray 
// property to add a value to myArray. (val is a variable returned from the server).
lv.onLoad = function (  ) {
  this.targetArray.push(this.val);
};

It is important to understand the distinction between adding custom properties to objects (instances) and adding custom properties to classes. When you add a property to an object, it is available to that object only. In some situations, as discussed in this recipe, this is exactly what you want. If, however, you want to define a property that is accessible to all instances of a particular class, you should add that property to the class, as discussed in the Introduction and Recipe 12.5.