Packageflash.utils
Classpublic class Proxy
InheritanceProxy Inheritance Object
Subclasses Environment

Language Version : ActionScript 3.0
Runtime Versions : Flash Player 9, AIR 1.0

The Proxy class lets you override the default behavior of ActionScript operations (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.

Note: RedTamarin keep the Proxy class in the flash.utils package. reason: inconsistency in Adobe documentation (we use last known doc for the Proxy class from "Mon Nov 28 2011, 06:48 AM -08:00").

View the examples

See also

AS3LCR Flash Platform flash.utils.Proxy
flash_proxy


Public Methods
 MethodDefined By
 Inherited
_init():*
[static]
_init
 Inherited
AS3
 Inherited
init():*
[static]
init
 Inherited
AS3
 Inherited
AS3
Protected Methods
 MethodDefined By
 Inherited
[static]
protected
 Inherited
_setPropertyIsEnumerable(o:*, V:String, enumerable:Boolean):void
[static]
protected
  
callProperty(name:*, ... rest):*
Overrides the behavior of an object property that can be called as a function.
Proxy
  
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
  
Overrides a request to check whether an object has a particular property by name.
Proxy
  
Checks whether a supplied QName is also marked as an attribute.
Proxy
  
Allows enumeration of the proxied object's properties by index number to retrieve property names.
Proxy
  
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
Public Constants
 ConstantDefined By
 Inheritedlength : int = 1
[static]
length
Method Detail
callProperty()method
flash_proxy function callProperty(name:*, ... rest):*

Language Version : ActionScript 3.0
Runtime Versions : Flash Player 9, AIR 1.0

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.

See also

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

Language Version : ActionScript 3.0
Runtime Versions : Flash Player 9, AIR 1.0

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.

See also

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

Language Version : ActionScript 3.0
Runtime Versions : Flash Player 9, AIR 1.0

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.

See also

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

Language Version : ActionScript 3.0
Runtime Versions : Flash Player 9, AIR 1.0

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.

See also

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

Language Version : ActionScript 3.0
Runtime Versions : Flash Player 9, AIR 1.0

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.

See also

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

Language Version : ActionScript 3.0
Runtime Versions : Flash Player 9, AIR 1.0

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.

See also

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

Language Version : ActionScript 3.0
Runtime Versions : Flash Player 9, AIR 1.0

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.

See also

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

Language Version : ActionScript 3.0
Runtime Versions : Flash Player 9, AIR 1.0

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.

See also

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

Language Version : ActionScript 3.0
Runtime Versions : Flash Player 9, AIR 1.0

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.

See also

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

Language Version : ActionScript 3.0
Runtime Versions : Flash Player 9, AIR 1.0

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.

See also

Examples
Usage
     package
     {
          import flash.display.Sprite;
     
          public class ProxyExample extends Sprite
          {
              public function ProxyExample()
              {
                  var arr:ProxyArray = new ProxyArray();
                      arr.push( 1 );
                      arr.psuh( -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;
              }
          }
     
     }