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 |
|
Returns |
|
Returns |
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.
![]() ![]() ![]() |