N-R > Object.addProperty

 

Object.addProperty

Availability

Flash Player 6.

Usage

myObject.addProperty( prop, getFunc, setFunc )

Parameters

prop The name of the object property to create.

getFunc The function that is invoked to retrieve the value of the property; this parameter is a function object.

setFunc The function that is invoked to set the value of the property; this parameter is a function object. If you pass the value null for this parameter, the property is read-only.

Returns

Returns a value of true if the property is successfully created; otherwise, returns false.

Description

Method; Creates a getter/setter property. When Flash reads a getter/setter property, it invokes the get function and the function's return value becomes a value of prop. When Flash writes a getter/setter property, it invokes the set function and passes it the new value as a parameter. If a property with the given name already exists, the new property overwrites it.

A get function is a function with no parameters. Its return value can be of any type. Its type can change between invocations. The return value is treated as the current value of the property.

A set function is a function that takes one parameter, which is the new value of the property. For instance, if property x is assigned by the statement x = 1, the set function is passed the parameter 1 of type number. The return value of the setter function is ignored.

You can add getter/setter properties to prototype objects. If you add a getter/setter property to a prototype object, all object instances that inherit the prototype object inherit the getter/setter property. This makes it possible to add a getter/setter property in one location, the prototype object, and have it propagate to all instances of a class (much like adding methods to prototype objects). If a get/set function is invoked for a getter/setter property in an inherited prototype object, the reference passed to the get/set function will be the originally referenced object, not the prototype object.

If invoked incorrectly, Object.addProperty may fail with an error. The following table describes errors that may occur:

Error Condition

What Happens

prop is not a valid property name; for instance, an empty string.

Returns false and the property is not added.

getFunc is not a valid function object.

Returns false and the property is not added.

setFunc is not a valid function object.

Returns false and the property is not added.


Example

Usage 1: The built-in properties TextField.scroll and TextField.maxscroll are getter/setter properties. The TextField object has internal methods getScroll, setScroll and getMaxScroll. The TextField constructor creates the getter/setter properties and points them to the internal get/set methods, as in the following:

this.addProperty("scroll", this.getScroll, this.setScroll);
this.addProperty("maxscroll", this.getMaxScroll, null);

When a script retrieves the value of myTextField.scroll, the ActionScript interpreter automatically invokes myTextField.getScroll. When a script modifies the value of myTextField.scroll, the interpreter invokes myTextField.setScroll. The maxscroll property does not specify a set function, so attempts to modify maxscroll are ignored.

Usage 2: The above example of TextField.scroll and TextField.maxscroll work, but the properties scroll and maxscroll are added to every instance of the TextField object. That means the cost of having the properties is two property slots for every instance of the object. If there are many properties like scroll and maxscroll in a class, they could consume a great deal of memory. Instead, you can add the scroll and maxscroll properties to TextField.prototype:

TextField.prototype.addProperty("scroll", this.getScroll, this.setScroll);
TextField.prototype.addProperty("maxscroll", this.getMaxScroll, null);

Now, the scroll and maxscroll properties only exist in one place: the TextField.prototype object. The effect, however, is the same as the above code that added scroll and maxscroll directly to every instance. If scroll or maxscroll is accessed in a TextField instance, the prototype chain is ascended and the getter/setter property in TextField.prototype is found.