CTest API Documentation: class Object

Main Page | Packages | Help

Previous \| Next	Frames \| No Frames
Summary: Field \| Property \| Contructor \| Method	Detail: Field \| Property \| Contructor \| Method

<root>

class Object

All Known Subclasses: CCommon, CTestSuperClass

intrinsic class Object

The Object class is at the root of the ActionScript class hierarchy.

This class contains a small subset of the features provided by the JavaScript Object class.

Since:: Flash Player 5 (became a native object in Flash Player 6, which improved performance significantly).

Field Summary
	__proto__: Object
	A reference to the prototype property of the object’s constructor function.

	constructor: Object
	A reference to the object’s constructor function.

static	prototype: Object


Constructor
	Object ( )
	Constructor;

Method Summary
	addProperty ( name: String, getter: Function, setter: Function ): Boolean
	Creates a getter/setter property.

	hasOwnProperty ( name: String ): Boolean


	isPropertyEnumerable ( name: String ): Boolean


	isPrototypeOf ( theClass: Object ): Boolean


static	registerClass ( name: String, theClass: Function ): Boolean
	Associates a movie clip symbol with an ActionScript object class

	toLocaleString ( ): String


	toString ( ): String
	Converts the specified object to a string and returns it.

	unwatch ( name: String ): Boolean
	Removes a watchpoint created with Object.watch()

	valueOf ( ): Object
	Returns the primitive value of the specified object

	watch ( name: String, callback: Function, userData: Object ): Boolean
	Registers an event handler to be invoked when a specified property of an ActionScript object changes.

Field Documentation

proto

var __proto__: Object

A reference to the prototype property of the object’s constructor function.

Refers to the prototype property of the constructor function that created myObject. The __proto__ property is automatically assigned to all objects when they are created. The ActionScript interpreter uses the __proto__ property to access the prototype property of the object’s constructor function to find out what properties and methods the object inherits from its class.

Usage:: myObject.__proto__

constructor

var constructor: Object

A reference to the object’s constructor function.

The constructor property is automatically assigned to all objects when they are created using the constructor for the Object class.

Usage:: myObject.constructor

prototype

static var prototype: Object

Constructor Documentation

Object

function Object

()

Constructor;

Creates an Object object and stores a reference to the object’s constructor method in the object’s constructor property.

Usage:: new Object([value]) : Object

Returns:: A reference to an Object object.

Example:: The following example creates a generic object named myObject: var myObject:Object = new Object();

Method Documentation

addProperty

function addProperty

(name: String,
getter: Function,
setter: Function): Boolean

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

Error condition	What happens
`prop` is not a valid property name; for example, 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.

Usage:: myObject.addProperty(prop:String, getFunc:Function, setFunc:Function) : Boolean

Parameters:

name		A string; the name of the object property to create.
getter		The function that is invoked to retrieve the value of the property; this parameter is a Function object.
setter		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:: true if the property is successfully created , false otherwise.

Since:: Flash Player 6. In ActionScript 2.0 classes, you can use get or set instead of this method.

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);

hasOwnProperty

function hasOwnProperty

(name: String): Boolean

isPropertyEnumerable

function isPropertyEnumerable

(name: String): Boolean

isPrototypeOf

function isPrototypeOf

(theClass: Object): Boolean

registerClass

static function registerClass

(name: String,
theClass: Function): Boolean

Associates a movie clip symbol with an ActionScript object class

If a symbol doesn’t exist, Flash creates an association between a string identifier and an object class.

When an instance of the specified movie clip symbol is placed on the Timeline, it is registered to the class specified by the theClass parameter rather than to the class MovieClip. When an instance of the specified movie clip symbol is created by using MovieClip.attachMovie or MovieClip.duplicateMovieClip, it is registered to the class specified by theClass rather than to the MovieClip class. If theClass is null, this method removes any ActionScript class definition associated with the specified movie clip symbol or class identifier. For movie clip symbols, any existing instances of the movie clip remain unchanged, but new instances of the symbol are associated with the default class MovieClip.

If a symbol is already registered to a class, this method replaces it with the new registration.

When a movie clip instance is placed by the Timeline or created using MovieClip.attachMovie or MovieClip.duplicateMovieClip, ActionScript invokes the constructor for the appropriate class with the keyword this pointing to the object. The constructor function is invoked with no parameters. If you use this method to register a movie clip with an ActionScript class other than MovieClip, the movie clip symbol doesn’t inherit the methods, properties, and events of the built-in MovieClip class unless you include the MovieClip class in the prototype chain of the new class. The following code creates a new ActionScript class called theClass that inherits the properties of the MovieClip class:

theClass.prototype = new MovieClip();

Usage:: Object.registerClass(symbolID:String, theClass:Function) : Boolean

Parameters:

name		The linkage identifier of the movie clip symbol or the string identifier for the ActionScript class.
theClass		A reference to the constructor function of the ActionScript class or null to unregister the symbol.

Returns:: If the class registration succeeds, a value of true is returned; false otherwise.

See also:: MovieClip.attachMovie, MovieClip.duplicateMovieClip

toLocaleString

function toLocaleString

(): String

toString

function toString

(): String

Converts the specified object to a string and returns it.

Usage:: myObject.toString() : String

Returns:: A string.

Example:

This example shows the return value for toString() on a generic object:

var myObject:Object = new Object();
trace(myObject.toString()); // output: [object Object]

This method can be overridden to return a more meaningful value. The following examples show that this method has been overridden for the built-in classes Date, Array, and Number:

// Date.toString() returns the current date and time
var myDate:Date = new Date();
trace(myDate.toString()); // output: [current date and time]

// Array.toString() returns the array contents as a comma-delimited string
var myArray:Array = new Array("one", "two");
trace(myArray.toString()); // output: one,two

// Number.toString() returns the number value as a string
// Because trace() won’t tell us whether the value is a string or number
// we will also use typeof() to test whether toString() works.
var myNumber:Number = 5;
trace(typeof (myNumber));  // output: number
trace(myNumber.toString()); // output: 5
trace(typeof (myNumber.toString())); // output: string

The following example shows how to override toString() in a custom class. First create a text file named Vehicle.as that contains only the Vehicle class definition and place it into your Classes folder inside your Configuration folder.

// contents of Vehicle.as
class Vehicle {
  var numDoors:Number;
  var color:String;
  function Vehicle(param_numDoors:Number, param_color:String) {
    this.numDoors = param_numDoors;
    this.color = param_color;
  }
  function toString():String {
    var doors:String = "door";
    if (this.numDoors > 1) {
      doors += "s";
    }
    return ("A vehicle that is " + this.color + " and has " + this.numDoors + " " + doors);
  }
}

// code to place into a FLA file
var myVehicle:Vehicle = new Vehicle(2, "red");
trace(myVehicle.toString());
// output: A vehicle that is red and has 2 doors

// for comparison purposes, this is a call to valueOf()
// there is no primitive value of myVehicle, so the object is returned
// giving the same output as toString().
trace(myVehicle.valueOf());
// output: A vehicle that is red and has 2 doors

unwatch

function unwatch

(name: String): Boolean

Removes a watchpoint created with Object.watch()

This method returns a value of true if the watchpoint is successfully removed, false otherwise.

Usage:: myObject.unwatch (prop:String) : Boolean

Parameters:

name

A string; the name of the object property that should no longer be watched.

Returns:: true if the watchpoint is successfully removed, false otherwise.

Example:: See the example for watch

See also:: addProperty, watch

valueOf

function valueOf

(): Object

Returns the primitive value of the specified object

If the object does not have a primitive value, the object is returned.

Usage:: myObject.valueOf() : Object

Returns:: The primitive value of the specified object or the object itself.

Example:

The following example shows the return value of valueOf() for a generic object (which does not have a primitive value) and compares it to the return value of toString():

// Create a generic object
var myObject:Object = new Object();
trace(myObject.valueOf()); // output: [object Object]
trace(myObject.toString()); // output: [object Object]

The following examples show the return values for the built-in classes Date and Array, and compares them to the return values of Object.toString():

// Create a new Date object set to February 1, 2004, 8:15 AM
// The toString() method returns the current time in human-readable form
// The valueOf() method returns the primitive value in milliseconds
var myDate:Date = new Date(2004,01,01,8,15);
trace(myDate.toString()); // output: Sun Feb 1 08:15:00 GMT-0800 2004
trace(myDate.valueOf()); // output: 1075652100000

// Create a new Array object containing two simple elements
// In this case both toString() and valueOf() return the same value: one,two
var myArray:Array = new Array("one", "two");
trace(myArray.toString()); // output: one,two
trace(myArray.valueOf()); // output: one,two

See the example for toString for an example of the return value of Object.valueOf() for a custom class that overrides toString().

watch

function watch

(name: String,
callback: Function,
userData: Object): Boolean

Registers an event handler to be invoked when a specified property of an ActionScript object changes.

When the property changes, the event handler is invoked with myObject as the containing object. Your can use the return statement in your callback method definition to affect the value of the property you are watching. The value returned by your callback method is assigned to the watched object property. The value you choose to return depends on whether you wish to monitor, modify or prevent changes to the property:

If you are merely monitoring the property, return the newVal parameter.
If you are modifying the value of the property, return your own value.
If you want to prevent changes to the property, return the oldVal parameter.

If the callback method you define does not have a return statement, then the watched object property is assigned a value of undefined.

A watchpoint can filter (or nullify) the value assignment, by returning a modified newval (or oldval). If you delete a property for which a watchpoint has been set, that watchpoint does not disappear. If you later recreate the property, the watchpoint is still in effect. To remove a watchpoint, use the Object.unwatch method.

Only a single watchpoint can be registered on a property. Subsequent calls to Object.watch() on the same property replace the original watchpoint.

The Object.watch() method behaves similarly to the Object.watch() function in JavaScript 1.2 and later. The primary difference is the userData parameter, which is a Flash addition to Object.watch() that Netscape Navigator does not support. You can pass the userData parameter to the event handler and use it in the event handler.

The Object.watch() method cannot watch getter/setter properties. Getter/setter properties operate through lazy evaluation— the value of the property is not determined until the property is actually queried. Lazy evaluation is often efficient because the property is not constantly updated; it is, rather, evaluated when needed. However, Object.watch() needs to evaluate a property to determine whether to invoke the callback function. To work with a getter/setter property, Object.watch() needs to evaluate the property constantly, which is inefficient.

Generally, predefined ActionScript properties, such as _x, _y, _width, and _height, are getter/setter properties and cannot be watched with Object.watch().

Usage:: myObject.watch( prop:String, callback:Function [, userData:Object] ) : Boolean

Parameters:

name		A string; the name of the object property to watch.
callback		The function to invoke when the watched property changes. This parameter is a function object, not a function name as a string. The form of `callback` is callback(prop, oldVal, newVal, userData).
userData		An arbitrary piece of ActionScript data that is passed to the `callback` method. If the `userData` parameter is omitted, `undefined` is passed to the callback method. This parameter is optional.

Returns:: true if the watchpoint is created successfully, false otherwise.

Example:

The following example uses watch() to check whether the speed property exceeds the speed limit:

// Create a new object
var myObject:Object = new Object();
// Add a property that tracks speed
myObject.speed = 0;
 
// Write the callback function to be executed if the speed property changes
var speedWatcher:Function = function(prop, oldVal, newVal, speedLimit) {
  // Check whether speed is above the limit
  if (newVal > speedLimit) {
    trace ("You are speeding.");
  }
  else {
    trace ("You are not speeding.");
  }
 
  // Return the value of newVal.
  return newVal;
}
// Use watch() to register the event handler, passing as parameters:
//   - the name of the property to watch: "speed"
//   - a reference to the callback function speedWatcher
//   - the speedLimit of 55 as the userData parameter
myObject.watch("speed", speedWatcher, 55);
 
// set the speed property to 54, then to 57
myObject.speed = 54; // output: You are not speeding
myObject.speed = 57; // output: You are speeding
 
// unwatch the object
myObject.unwatch("speed");
myObject.speed = 54; // there should be no output

See also:: addProperty, unwatch

The documentation was generated from the following file:

Object.as, Last Modified: 22.08.2004 01:58:54

Previous \| Next	Frames \| No Frames
Summary: Field \| Property \| Contructor \| Method	Detail: Field \| Property \| Contructor \| Method

class Object

Field Summary

Constructor

Method Summary

Field Documentation

__proto__

constructor

prototype

Constructor Documentation

Object

Method Documentation

addProperty

hasOwnProperty

isPropertyEnumerable

isPrototypeOf

registerClass

toLocaleString

toString

unwatch

valueOf

watch

proto