Recipe 12.4 Adding Custom Methods to an Object Instance

12.4.1 Problem

You want to add custom methods to an object.

12.4.2 Solution

Assign a function definition (or a reference to one) to a custom property of an object that is already instantiated.

12.4.3 Discussion

You can add functionality to objects (instances of a class) by assigning new methods to them. First, define a function. Then store a reference to the function in a custom property of the object. That is, the definitions of an object's methods are stored as properties of the same object.

This example stores a function in the custom property methodProp:

myObject = new Object(  );
myObject.methodProp = function (  ) {
  trace("Hello World");
};

The preceding example assigns a method to an object using an anonymous function. However, you can also use object properties to store references to named functions. The following example stores a reference to the named function, myMethodFunction( ), in the property myMethod:

// Define a named function.
function myMethodFunction (  ) {
  trace(this.myProperty);
}

// Create a new object. You can assign custom methods to any kind of object (movie
// clip, array, etc.), but this example uses a generic object of the Object class.
myObject = new Object(  );

// Create a custom property on the object. This is not necessary, per se, but we use
// it here to illustrate that when a function is called as a method of an object, the
// function has access to all the properties of that object by means of 
// self-references (using the this keyword).
myObject.myProperty = "this is a custom property";

// Store a reference to myMethodFunction(  ) in the property named myMethod. Note the
// lack of parentheses following myMethodFunction.
myObject.myMethod = myMethodFunction;

// Invoke the custom myMethodFunction(  ) method by referring to the property that
// stores it. myMethod(  ) is used to invoke myMethodFunction(  ). Note the inclusion of
// the parentheses following myMethod.
myObject.myMethod(  );  // Displays: "this is a custom property"

Once you have assigned a function to a property of an object, you can invoke that function as a method of the object, as shown in the preceding example.

Do not include the parentheses after the function name when assigning it to the object's property. Without the parentheses, the function name is treated as a reference to the function definition, and the function is not invoked. However, use parentheses when invoking the function, as shown in the last line of the preceding example.

The preceding example shows how to store a named function in an object property. However, custom methods are commonly assigned using anonymous functions, as was briefly introduced earlier. An anonymous function is never given a name in its definition but is assigned directly to a variable (such as a custom property). Note that anonymous functions, also called function literals, should be followed by a semicolon after the closing curly brace. This technique results in slightly more compact code because the assignment and function definition all take place at once.

Here is the analog of the preceding example, implemented with an anonymous function instead of a named function:

myObject = new Object(  );
myObject.myProperty = "this is a custom property";

// Assign an anonymous function to the custom myMethod property. The myMethod(  ) 
// method is now a reference to an anonymous function.
myObject.myMethod = function (  ) {
  trace(this.myProperty);
};

// Invoke the custom method. 
myObject.myMethod(  );   // Displays: "this is a custom property"

Adding methods to objects is absolutely essential in many cases. For example, to use event handler methods for movie clips or onLoad( ) methods for XML objects or LoadVars objects, you have to define an appropriate method for that object, albeit with a specific name. For example, here we assign a custom function to the onEnterFrame property of a movie clip. This reserved property name holds the method to be invoked whenever the Flash Player triggers an onEnterFrame event, which occurs whenever the playhead reaches a frame.

myMovieClip.onEnterFrame = function (  ) {
  trace("onEnterFrame(  ) was reached");
};

In the preceding example, the onEnterFrame( ) method applies only to the movie clip to which it is attached. It has no effect on other movie clips. Because the Flash Player automatically generates onEnterFrame events during movie playback, our movie clip can respond to the event by simply defining a method (deemed an event handler) with the same name as the event. Although there may appear to be a difference between defining a custom method and defining an event handler, ActionScript makes no such distinction. Both are implemented by defining functions and storing the function reference in a property of the object. The only difference is that Flash movies automatically invoke the event handler methods when certain events occur, while custom methods are generally invoked manually by other ActionScript code written by you, the developer.

As seen in Chapter 7, you might want to define custom methods and make them available to all movie clips.

Often, custom methods are defined for the entire class and not just an object (an instance of the class). To add a method to the class, assign it to the class's prototype property, rather than directly to an instance.

For example, Recipe 7.10 defines a new method that is made accessible to all movie clips by assigning it to the MovieClip.prototype property from which all movie clip instances inherit.

12.4.4 See Also

Recipe 12.5. Recipes throughout this book implement custom functions and attach them to the class's prototype property to enhance that class. Also refer to Chapter 7 and Chapter 9.