Object
Object public class ObjectThe 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. Availability: ActionScript 1.0; Flash Player 5 - (became a native object in Flash Player 6, which improved performance significantly). Property summary
Constructor summary
Method summary
addProperty (Object.addProperty method)public 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 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:
Availability: ActionScript 1.0; Flash Player 6 - In ActionScript 2.0 classes, you can use get or set instead of this method. 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 RyeThe 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 constructor (Object.constructor property)public constructor : Object Reference to the constructor function for a given object instance. The constructor property is automatically assigned to all objects when they are created using the constructor for the Object class. Availability: ActionScript 1.0; Flash Player 5 Example The following example is a reference to the constructor function for the myObject object. var my_str:String = new String("sven"); trace(my_str.constructor == String); //output: trueIf you use the instanceof operator, you can also determine if an object belongs to a specified class: var my_str:String = new String("sven"); trace(my_str instanceof String); //output: trueHowever, in the following example the Object.constructor property converts primitive data types (such as the string literal seen here) into wrapper objects. The instanceof operator does not perform any conversion, as seen in the following example: var my_str:String = "sven"; trace(my_str.constructor == String); //output: true trace(my_str instanceof String); //output: false See also instanceof operator hasOwnProperty (Object.hasOwnProperty method)public hasOwnProperty(name:String) : Boolean Indicates whether an object has a specified property defined. This method returns true if the target object has a property that matches the string specified by the name parameter, and false otherwise. This method does not check the object's prototype chain and returns TRue only if the property exists on the object itself. Availability: ActionScript 1.0; Flash Player 6 Parameters name:String -Returns Boolean - A Boolean value: TRue if the target object has the property specified by the name parameter, false otherwise. isPropertyEnumerable (Object.isPropertyEnumerable method)public isPropertyEnumerable(name:String) : Boolean Indicates whether the specified property exists and is enumerable. If TRue, then the property exists and can be enumerated in a for..in loop. The property must exist on the target object because this method does not check the target object's prototype chain. Properties that you create are enumerable, but built-in properties are generally not enumerable. Availability: ActionScript 1.0; Flash Player 6 Parameters name:String -Returns Boolean - A Boolean value: true if the property specified by the name parameter is enumerable. Example The following example creates a generic object, adds a property to the object, then checks whether the object is enumerable. By way of contrast, the example also shows that a built-in property, the Array.length property, is not enumerable. var myObj:Object = new Object(); myObj.prop1 = "hello"; trace(myObj.isPropertyEnumerable("prop1")); // Output: true var myArray = new Array(); trace(myArray.isPropertyEnumerable("length")); // Output: falseSee also for..in statement isPrototypeOf (Object.isPrototypeOf method)public isPrototypeOf(theClass:Object) : Boolean Indicates whether an instance of the Object class is in the prototype chain of the object specified as an argument. This method returns TRue if the object is in the prototype chain of the object specified by the theClass parameter. The method returns false not only if the target object is absent from the prototype chain of the theClass object, but also if the theClass argument is not an object. Availability: ActionScript 1.0; Flash Player 6 Parameters theClass:Object -Returns Boolean - A Boolean value: TRue if the object is in the prototype chain of the object specified by the theClass parameter; false otherwise. Object constructorpublic Object() Creates an Object object and stores a reference to the object's constructor method in the object's constructor property. Availability: ActionScript 1.0; Flash Player 5 Example The following example creates a generic object named myObject: var myObject:Object = new Object(); __proto__ (Object.__proto__ property)public __proto__ : Object Refers to the prototype property of the class (ActionScript 2.0) or constructor function (ActionScript 1.0) used to create the object. 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 class or constructor function to find out what properties and methods the object inherits from its superclass. Availability: ActionScript 1.0; Flash Player 5 Example The following example creates a class named Shape and a subclass of Shape named Circle. // Shape class defined in external file named Shape.as class Shape { function Shape() {} } // Circle class defined in external file named Circle.as class Circle extends Shape{ function Circle() {} }The Circle class can be used to create two instances of Circle: var oneCircle:Circle = new Circle(); var twoCircle:Circle = new Circle(); The following trace statements show that the __proto_ property of both instances refers to the prototype property of the Circle class. trace(Circle.prototype == oneCircle.__proto__); // Output: true trace(Circle.prototype == twoCircle.__proto__); // Output: true See also prototype (Object.prototype property) prototype (Object.prototype property)public static prototype : Object A reference to the superclass of a class or function object. The prototype property is automatically created and attached to any class or function object you create. This property is static in that it is specific to the class or function you create. For example, if you create a custom class, the value of the prototype property is shared by all instances of the class, and is accessible only as a class property. Instances of your custom class cannot directly access the prototype property, but can access it through the __proto__ property. Availability: ActionScript 1.0; Flash Player 6 Example The following example creates a class named Shape and a subclass of Shape named Circle. // Shape class defined in external file named Shape.as class Shape { function Shape() {} } // Circle class defined in external file named Circle.as class Circle extends Shape{ function Circle() {} }The Circle class can be used to create two instances of Circle: var oneCircle:Circle = new Circle(); var twoCircle:Circle = new Circle(); The following trace statement shows that the prototype property of the Circle class points to its superclass Shape. The identifier Shape refers to the constructor function of the Shape class. trace(Circle.prototype.constructor == Shape); // Output: true The following trace statement shows how you can use the prototype property and the __proto__ property together to move two levels up the inheritance hierarchy (or prototype chain). The Circle.prototype.__proto__ property contains a reference to the superclass of the Shape class. trace(Circle.prototype.__proto__ == Shape.prototype); // Output: true See also __proto__ (Object.__proto__ property) registerClass (Object.registerClass method)public static 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 attachMovie() or 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(); Availability: ActionScript 1.0; Flash Player 6 - If you are using ActionScript 2.0 classes, you can use the ActionScript 2.0 Class field in the Linkage Properties or Symbol Properties dialog box to associate an object with a class instead of using this method. Parameters name:String - String; the linkage identifier of the movie clip symbol or the string identifier for the ActionScript class. theClass:Function - A reference to the constructor function of the ActionScript class or null to unregister the symbol. Returns Boolean - A Boolean value: if the class registration succeeds, a value of TRue is returned; false otherwise. See also attachMovie (MovieClip.attachMovie method), duplicateMovieClip (MovieClip.duplicateMovieClip method) __resolve (Object.__resolve property)public __resolve : Object A reference to a user-defined function that is invoked if ActionScript code refers to an undefined property or method. If ActionScript code refers to an undefined property or method of an object, Flash Player determines whether the object's __resolve property is defined. If __resolve is defined, the function to which it refers is executed and passed the name of the undefined property or method. This lets you programmatically supply values for undefined properties and statements for undefined methods and make it seem as if the properties or methods are actually defined. This property is useful for enabling highly transparent client/server communication, and is the recommended way of invoking server-side methods. Availability: ActionScript 1.0; Flash Player 6 Example The following examples progressively build upon the first example and illustrate five different usages of the __resolve property. To aid understanding, key statements that differ from the previous usage are in bold typeface. Usage 1: the following example uses __resolve to build an object where every undefined property returns the value "Hello, world!". // instantiate a new object var myObject:Object = new Object(); // define the __resolve function myObject.__resolve = function (name) { return "Hello, world!"; }; trace (myObject.property1); // output: Hello, world! trace (myObject.property2); // output: Hello, world!Usage 2: the following example uses __resolve as a functor, which is a function that generates functions. Using __resolve redirects undefined method calls to a generic function named myFunction. // instantiate a new object var myObject:Object = new Object(); // define a function for __resolve to call myObject.myFunction = function (name) { trace("Method " + name + " was called"); }; // define the __resolve function myObject.__resolve = function (name) { return function () { this.myFunction(name); }; }; // test __resolve using undefined method names myObject.someMethod(); // output: Method someMethod was called myObject.someOtherMethod(); //output: Method someOtherMethod was calledUsage 3: The following example builds on the previous example by adding the ability to cache resolved methods. By caching methods, __resolve is called only once for each method of interest. This allows lazy construction of object methods. Lazy construction is an optimization technique that defers the creation, or construction, of methods until the time at which a method is first used. // instantiate a new object var myObject:Object = new Object(); // define a function for __resolve to call myObject.myFunction = function(name) { trace("Method "+name+" was called"); }; // define the __resolve function myObject.__resolve = function(name) { trace("Resolve called for "+name); // to check when __resolve is called // Not only call the function, but also save a reference to it var f:Function = function () { this.myFunction(name); }; // create a new object method and assign it the reference this[name] = f; // return the reference return f; }; // test __resolve using undefined method names // __resolve will only be called once for each method name myObject.someMethod(); // calls __resolve myObject.someMethod(); // does not call __resolve because it is now defined myObject.someOtherMethod(); // calls __resolve myObject.someOtherMethod(); // does not call __resolve, no longer undefinedUsage 4: The following example builds on the previous example by reserving a method name, onStatus(), for local use so that it is not resolved in the same way as other undefined properties. Added code is in bold typeface. // instantiate a new object var myObject:Object = new Object(); // define a function for __resolve to call myObject.myFunction = function(name) { trace("Method "+name+" was called"); }; // define the __resolve function myObject.__resolve = function(name) { // reserve the name "onStatus" for local use if (name == "onStatus") { return undefined; } trace("Resolve called for "+name); // to check when __resolve is called // Not only call the function, but also save a reference to it var f:Function = function () { this.myFunction(name); }; // create a new object method and assign it the reference this[name] = f; // return the reference return f; }; // test __resolve using the method name "onStatus" trace(myObject.onStatus("hello")); // output: undefinedUsage 5: The following example builds on the previous example by creating a functor that accepts parameters. This example makes extensive use of the arguments object, and uses several methods of the Array class. // instantiate a new object var myObject:Object = new Object(); // define a generic function for __resolve to call myObject.myFunction = function (name) { arguments.shift(); trace("Method " + name + " was called with arguments: " + arguments.join(',')); }; // define the __resolve function myObject.__resolve = function (name) { // reserve the name "onStatus" for local use if (name == "onStatus") { return undefined; } var f:Function = function () { arguments.unshift(name); this.myFunction.apply(this, arguments); }; // create a new object method and assign it the reference this[name] = f; // return the reference to the function return f; }; // test __resolve using undefined method names with parameters myObject.someMethod("hello"); // output: Method someMethod was called with arguments: hello myObject.someOtherMethod("hello","world"); // output: Method someOtherMethod was called with arguments: hello,worldSee also arguments, Array toString (Object.toString method)public toString() : String Converts the specified object to a string and returns it. Availability: ActionScript 1.0; Flash Player 5 Returns String - 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: stringThe 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 doorsunwatch (Object.unwatch method)public unwatch(name:String) : Boolean Removes a watchpoint that Object.watch() created. This method returns a value of TRue if the watchpoint is successfully removed, false otherwise. Availability: ActionScript 1.0; Flash Player 6 Parameters name:String - A string; the name of the object property that should no longer be watched. Returns Boolean - A Boolean value: true if the watchpoint is successfully removed, false otherwise. Example See the example for Object.watch(). See also watch (Object.watch method), addProperty (Object.addProperty method) valueOf (Object.valueOf method)public valueOf() : Object Returns the primitive value of the specified object. If the object does not have a primitive value, the object is returned. Availability: ActionScript 1.0; Flash Player 5 Returns Object - 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(). First, create a generic object. Second, 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. Third, create a new Array object containing two simple elements. Both toString() and valueOf() return the same value: one,two: // 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,twoSee the example for Object.toString() for an example of the return value of Object.valueOf() for a custom class that overrides toString(). See also toString (Object.toString method) watch (Object.watch method)public 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. You 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 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(). Availability: ActionScript 1.0; Flash Player 6 Parameters name:String - A string; the name of the object property to watch. callback:Function - 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:Object [optional] - 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. Returns Boolean - A Boolean value: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 outputSee also addProperty (Object.addProperty method), unwatch (Object.unwatch method) |
EAN: 2147483647
Pages: 113