flash.utils Proxy

Package | flash.utils
Class | public class Proxy
Inheritance | Proxy Object
Subclasses | AbstractService, ConfigMap, DynamicManagedItem, ListCollectionView, NetClient, ObjectProxy, OLAPCube, OLAPElement, OrderedObject, ShaderFilter

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

The Proxy class lets you (such as retrieving and modifying properties) on an object.

The Proxy class has no constructor, and you should not attempt to instantiate Proxy. Instead, subclass the Proxy class to override methods such as `getProperty` and provide custom behavior. If you try to use a method of the Proxy class without overriding the method, an exception is thrown.

And, keep in mind, your own code overriding the methods of the Proxy class can throw exceptions unintentionally. Throwing exceptions when using these methods causes problems because the calling code (using operators like `in`, `is`, `delete` and others) does not expect exceptions. Unless you're already sure your overriding method does not throw exceptions, Adobe recommends using `try..catch` statements around your implementation of the Proxy class to avoid fatal errors when operators call your methods. For example:

     dynamic class MyProxy extends Proxy {
         flash_proxy override function callProperty(name:*, ...rest):* {
           try {
             // custom code here
           }
           catch (e:Error) {
             // respond to error here
           }
     }

The Proxy class is a replacement for the `Object.__resolve` and `Object.addProperty` features of ActionScript 2.0, which are no longer available in ActionScript 3.0. The `Object.addProperty()` feature allowed you to dynamically create get and set methods in ActionScript 2.0. Although ActionScript 3.0 provides get and set methods at compile time, you cannot dynamically assign one to an object unless you use the Proxy class.

To avoid collisions with the `public` namespace, the methods of the Proxy class are in the `flash_proxy` namespace.

Where methods of the Proxy class take a `name` argument, `name` can be either a String or a QName object (if namespaces are being used).

Note: Prior to Flash 11 and AIR 3.0, the Proxy class was a member of the `flash.utils` package. It is now a top-level class.

View the examples

Public Properties
Hide Inherited Public Properties
Show Inherited Public Properties

| Property | Defined By
--- | --- | ---
|  | constructor : Object A reference to the class object or constructor function for a given object instance. | Object
|  | prototype : Object [static] A reference to the prototype object of a class or function object. | Object

Public Methods
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined By
--- | --- | ---
|  | hasOwnProperty(name:String):Boolean Indicates whether an object has a specified property defined. | Object
|  | isPrototypeOf(theClass:Object):Boolean Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter. | Object
|  | propertyIsEnumerable(name:String):Boolean Indicates whether the specified property exists and is enumerable. | Object
|  | setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void Sets the availability of a dynamic property for loop operations. | Object
|  | toLocaleString():String Returns the string representation of this object, formatted according to locale-specific conventions. | Object
|  | toString():String Returns the string representation of the specified object. | Object
|  | valueOf():Object Returns the primitive value of the specified object. | Object

Protected Methods

| Method | Defined By
--- | --- | ---
|  | callProperty(name:*, ... rest):* Overrides the behavior of an object property that can be called as a function. | Proxy
|  | deleteProperty(name:*):Boolean Overrides the request to delete a property. | Proxy
|  | getDescendants(name:*):* Overrides the use of the descendant operator. | Proxy
|  | getProperty(name:*):* Overrides any request for a property's value. | Proxy
|  | hasProperty(name:*):Boolean Overrides a request to check whether an object has a particular property by name. | Proxy
|  | isAttribute(name:*):Boolean Checks whether a supplied QName is also marked as an attribute. | Proxy
|  | nextName(index:int):String Allows enumeration of the proxied object's properties by index number to retrieve property names. | Proxy
|  | nextNameIndex(index:int):int Allows enumeration of the proxied object's properties by index number. | Proxy
|  | nextValue(index:int):* Allows enumeration of the proxied object's properties by index number to retrieve property values. | Proxy
|  | setProperty(name:*, value:*):void Overrides a call to change a property's value. | Proxy

Method Detail

## callProperty

()
method

`flash_proxy function callProperty(name:*, ... rest):*`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

Overrides the behavior of an object property that can be called as a function. When a method of the object is invoked, this method is called. While some objects can be called as functions, some object properties can also be called as functions.

Parameters

| `name:*` — The name of the method being invoked.
| `... rest` — An array specifying the arguments to the called method.

Returns

| `*` — The return value of the called method.

Learn more

ECMA-262 Language Specification, 3rd Edition, section 15

Related API Elements

Function.call()

## deleteProperty

()
method

`flash_proxy function deleteProperty(name:*):Boolean`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

Overrides the request to delete a property. When a property is deleted with the `delete` operator, this method is called to perform the deletion.

Parameters

| `name:*` — The name of the property to delete.

Returns

| `Boolean` — If the property was deleted, `true`; otherwise `false`.

Learn more

ECMA-262 Language Specification, 3rd Edition, 8.6.2.5

Related API Elements

delete operator

## getDescendants

()
method

`flash_proxy function getDescendants(name:*):*`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

Overrides the use of the `descendant` operator. When the `descendant` operator is used, this method is invoked.

Parameters

| `name:*` — The name of the property to descend into the object and search for.

Returns

| `*` — The results of the `descendant` operator.

Learn more

E4X Specification

Related API Elements

descendant operator

## getProperty

()
method

`flash_proxy function getProperty(name:*):*`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

Overrides any request for a property's value. If the property can't be found, the method returns `undefined`. For more information on this behavior, see the ECMA-262 Language Specification, 3rd Edition, section 8.6.2.1.

Parameters

| `name:*` — The name of the property to retrieve.

Returns

| `*` — The specified property or `undefined` if the property is not found.

Learn more

ECMA-262 Language Specification, 3rd Edition, section 8.6.2.1

Related API Elements

get statement

## hasProperty

()
method

`flash_proxy function hasProperty(name:*):Boolean`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

Overrides a request to check whether an object has a particular property by name.

Parameters

| `name:*` — The name of the property to check for.

Returns

| `Boolean` — If the property exists, `true`; otherwise `false`.

Learn more

ECMA-262 Language Specification, 3rd Edition, section 8.6.2.4

Related API Elements

Object.hasOwnProperty()

## isAttribute

()
method

`flash_proxy function isAttribute(name:*):Boolean`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

Checks whether a supplied QName is also marked as an attribute.

Parameters

| `name:*` — The name of the property to check.

Returns

| `Boolean` — Returns `true` if the argument for `name` is a QName that is also marked as an attribute.

Related API Elements

QName class

## nextName

()
method

`flash_proxy function nextName(index:int):String`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

Allows enumeration of the proxied object's properties by index number to retrieve property names. However, you cannot enumerate the properties of the Proxy class themselves. This function supports implementing `for...in` and `for each..in` loops on the object to retrieve the desired names.

For example (with code from `Proxy.nextNameIndex()`):

         protected var _item:Array; // array of object's properties
         override flash_proxy function nextNameIndex (index:int):int {
             // initial call
             if (index == 0) {
                 _item = new Array();
                 for (var x:* in _target) {
                    _item.push(x);
                 }
             }

             if (index < _item.length) {
                 return index + 1;
             } else {
                 return 0;
             }
         }
         override flash_proxy function nextName(index:int):String {
             return _item[index - 1];
         }

Parameters

| `index:int` — The zero-based index value of the object's property.

Returns

| `String` — The property's name.

Related API Elements

Proxy.nextNameIndex()
Proxy.nextValue()

## nextNameIndex

()
method

`flash_proxy function nextNameIndex(index:int):int`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

Allows enumeration of the proxied object's properties by index number. However, you cannot enumerate the properties of the Proxy class themselves. This function supports implementing `for...in` and `for each..in` loops on the object to retrieve property index values.

For example:

         protected var _item:Array; // array of object's properties
         override flash_proxy function nextNameIndex (index:int):int {
             // initial call
             if (index == 0) {
                 _item = new Array();
                 for (var x:* in _target) {
                    _item.push(x);
                 }
             }

             if (index < _item.length) {
                 return index + 1;
             } else {
                 return 0;
             }
         }
         override flash_proxy function nextName(index:int):String {
             return _item[index - 1];
         }

Parameters

| `index:int` — The zero-based index value where the enumeration begins.

Returns

| `int` — The property's index value.

Related API Elements

Proxy.nextName()
Proxy.nextValue()

## nextValue

()
method

`flash_proxy function nextValue(index:int):*`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

Allows enumeration of the proxied object's properties by index number to retrieve property values. However, you cannot enumerate the properties of the Proxy class themselves. This function supports implementing `for...in` and `for each..in` loops on the object to retrieve the desired values.

For example (with code from `Proxy.nextNameIndex()`):

         protected var _item:Array; // array of object's properties
         override flash_proxy function nextNameIndex (index:int):int {
             // initial call
             if (index == 0) {
                 _item = new Array();
                 for (var x:* in _target) {
                    _item.push(x);
                 }
             }

             if (index < _item.length) {
                 return index + 1;
             } else {
                 return 0;
             }
         }
         override flash_proxy function nextName(index:int):String {
             return _item[index - 1];
         }

Parameters

| `index:int` — The zero-based index value of the object's property.

Returns

| `*` — The property's value.

Related API Elements

Proxy.nextNameIndex()
Proxy.nextName()

## setProperty

()
method

`flash_proxy function setProperty(name:*, value:*):void`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

Overrides a call to change a property's value. If the property can't be found, this method creates a property with the specified name and value.

Parameters

| `name:*` — The name of the property to modify.
| `value:*` — The value to set the property to.

Learn more

ECMA-262 Language Specification, 3rd Edition, section 8.6.2.2

Related API Elements

set statement
Examples How to use this example
ProxyExample.as

    package {
        import flash.display.Sprite;

        public class ProxyExample extends Sprite {
            public function ProxyExample() {
                var arr:ProxyArray = new ProxyArray();
                arr.push(1);
                arr.push(-2);
                arr.push(3);
                arr.push(4);
                arr.push("five");

                trace(arr.length); // 5
                trace(arr[0]);     // 1
                trace(arr[1]);     // -2
                trace(arr[2]);     // 3
                trace(arr[3]);     // 4

                trace(arr.sum());  // 6

                arr.clear();
                trace(arr); // (empty string)

                arr[0] = "zero";
                trace(arr); // zero
            }
        }
    }

    import flash.utils.Proxy;
    import flash.utils.flash_proxy;

    dynamic class ProxyArray extends Proxy {
        private var _item:Array;

        public function ProxyArray() {
            _item = new Array();
        }

        override flash_proxy function callProperty(methodName:*, ... args):* {
            var res:*;
            switch (methodName.toString()) {
                case 'clear':
                    _item = new Array();
                    break;
                case 'sum':
                    var sum:Number = 0;
                    for each (var i:* in _item) {
                        // ignore non-numeric values
                        if (!isNaN(i)) {
                            sum += i;
                        }
                    }
                    res = sum;
                    break;
                default:
                    res = _item[methodName].apply(_item, args);
                    break;
            }
            return res;
        }

        override flash_proxy function getProperty(name:*):* {
            return _item[name];
        }

        override flash_proxy function setProperty(name:*, value:*):void {
            _item[name] = value;
        }
    }

© 2011 Adobe Systems Incorporated. All rights reserved.
Mon Nov 28 2011, 06:48 AM -08:00