Flash CS3 Documentation

Flash Lite 2.x ActionScript Language Reference > ActionScript classes > Object > addProperty (Object.addProperty method)

addProperty (Object.addProperty 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 the value of name. 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 example, 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 set 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 (similar to 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 is the originally referenced object--not the prototype object.

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

Parameters

name:String - A string; the name of the object property to create.

getter:Function - The function that is invoked to retrieve the value of the property; this parameter is a Function object.

setter:Function - 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

Boolean - A Boolean value: true if the property is successfully created; false otherwise.

Example

In the following example, an object has two internal methods, setQuantity() and getQuantity(). 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. 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.

function Book() {
    this.setQuantity = function(numBooks:Number):Void {
    this.books = numBooks;
    };
    this.getQuantity = function():Number {
    return this.books;
    };
    this.getTitle = function():String {
    return "Catcher in the Rye";
    };
    this.addProperty("bookcount", this.getQuantity, this.setQuantity);
    this.addProperty("bookname", this.getTitle, null);
}
var myBook = new Book();
myBook.bookcount = 5;
trace("You ordered "+myBook.bookcount+" copies of "+myBook.bookname);
// output: You ordered 5 copies of Catcher in the Rye

The previous example works, but the properties bookcount and bookname are added to every instance of the Book object, which requires having two properties for every instance of the object. If there are many properties, such as bookcount and bookname, in a class, they could consume a great deal of memory. Instead, you can add the properties to Book.prototype so that the bookcount and bookname properties exist only in one place. The effect, however, is the same as that of the code in the example that added bookcount and bookname directly to every instance. If an attempt is made to access either property in a Book instance, the property's absence will cause the prototype chain to be ascended until the versions defined in Book.prototype are encountered. The following example shows how to add the properties to Book.prototype:

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

The following example shows how to use the implicit getter and setter functions available in ActionScript 2.0. Rather than defining the Book function and editing Book.prototype, you define the Book class in an external file named Book.as. The following code must be in a separate external file named Book.as that contains only this class definition and resides within the Flash application's classpath:

class Book {
    var books:Number;
    function set bookcount(numBooks:Number):Void {
    this.books = numBooks;
    }
    function get bookcount():Number {
    return this.books;
    }
    function get bookname():String {
    return "Catcher in the Rye";
    }
}

The following code can then be placed in a FLA file and will function the same way as it does in the previous examples:

var myBook:Book = new Book(); 
myBook.bookcount = 5; 
trace("You ordered "+myBook.bookcount+" copies of "+myBook.bookname);

See also

get statement, set statement

Flash CS3