N-R > Object.addProperty |  |

Object.addProperty

Object, Object.addProperty, 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: An object has two internal methods, `getBookCount` and `setBookCount`. A property, `bookcount`, can be used to invoke these methods when it is either set or retrieved. A third internal method, `getTitle`, returns a read-only value that is associated with the property `bookname`:

    function Book() {

    this.setQuantity = function(numBooks) {

    		this.books = numBooks;
    	}

    this.getQuantity = function() {
    	return this.books;

    	}
    	this.getTitle = function() {
    		return "Catcher in the Rye";
    	}
    	this.addProperty("bookcount", this.getQuantity, this.setQuantity);
    	this.addProperty("bookname", this.getTitle, null);
    }
    myBook = new Book();
    myBook.bookcount = 5;
    order = "You ordered " + myBook.bookcount + " copies of " + myBook.bookname;

When a script retrieves the value of `myBook.bookcount`, the ActionScript interpreter automatically invokes `myBook.getQuantity`. When a script modifies the value of `myBook.bookcount`, the interpreter invokes `myObject.setQuantity`. The `bookname` property does not specify a set function, so attempts to modify `bookname` are ignored.

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

    function Book () {}
    Book.prototype.setQuantity = function(numBooks) {
    	this.books = numBooks;
    }
    Book.prototype.getQuantity = function() {
    	return this.books;
    }
    Book.prototype.getTitle = function() {
    	return "Catcher in the Rye";
    }
    Book.prototype.addProperty("bookcount", Book.prototype.getQuantity, Book.prototype.setQuantity);
    Book.prototype.addProperty("bookname", Book.prototype.getTitle, null);
    myBook = new Book();
    myBook.bookcount = 5;
    order = "You ordered "+myBook.bookcount+" copies of "+myBook.bookname;

Now, the `bookcount` and `bookname` properties exist only in one place: the `Book.prototype` object. The effect, however, is the same as that of the code in Usage 1, which added `bookcount` and `bookname` directly to every instance. If `bookcount` or `bookname` is accessed in a `Book` instance, the prototype chain is ascended and the getter/setter property in `Book.prototype` is found.

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.