ASSetPropFlags

This function is used internally during the initializion stage for the predefined actionscript objects. It is used to hide an objects children from the for..in loop construct. The for..in loop construct iterates over all children of an object, this means it exposes both methods and properties of an object. It is also used to protect the predefined actionscript objects children from being over-written by another action with the same name and to protect the predefined actionscript objects from being deleted. The usefulness of this function can also be harnessed by the developer and that is when this function gets interesting…

ASSetPropFlags can be used to:

• Hide objects children from the for..in loop construct
• Un-hide objects children to the mercy of the for..in loop construct
• Protect objects children from being over-written
• Un-Protect objects children from being over-written
• Protect objects children from being deleted
• Un-Protect objects children from being deleted

Unfortuneatley because this function has been exposed, the protection this function provides for objects children being over-written and deleted has been rendered useless, because of course, you can also un-protect them, the same goes for hiding actions from the for..in loop construct, you can of course also unhide them.

That aside, if Macromedia can use it to do the job then so can we.

The ASSetPropFlags function accepts four arguments:

ASSetPropFlags(obj,props,n,allowFalse)

The first argument ‘obj’ is the object that this function is to act upon.

The Second argument ‘props’ is a list of child names contained inside of the object passed as the argument ‘obj’ in the form of a comma-delimited string or an array onto which this function will act upon. If you pass the value ‘null’ for this argument, this has the same effect as passing an array listing ‘all’ of the children contained inside of the object passed as the argument ‘obj’. So for example:

["start","stop","reset"]


Will act upon the children named start, stop and reset as will:

"start,stop,reset"

The third argument ‘n’ is a number which represents three bitwise flags which are used to determine whether the list of child names should be hidden, un-hidden, protected from over-write, un-protected from over-write, protected from deletion and un-protected from deletion. Refer to this table for the results achieved by the different possible values for this argument:

The fourth argument ‘allowFalse’ is a boolean value(true/false) which is used to specify whether the three different types of protection, protect from over-write, protect from deletion and hide from for..in loop constructs can be set to false. If this value is ommited(not passed) then the default value ‘false’ is used, meaning you cannot un-protect from over-write, you cannot un-protect from deletion and you cannot un-hide from the for..in loop construct.

ASSetPropFlags was exposed in Flash 5, however the fourth argument ‘allowFalse’ was not required as it always defaulted to the value ‘true’. When Flash MX was released, people tested to see if this function still existed, obviously it did exist and so the clever people amongst the beta testers, used this function to get a list of all the undocumented objects,methods,properties and functions that existed in Flash MX:

//un-hide all children contained
//inside of the _global object
//refer to the table above to
//see the result of the third argument
//as the value '6'
ASSetPropFlags(_global,null,6,true);
//iterate over all the children of
//the _global object
for(i in _global){
   trace(i)
}

However, if we were to iterate over all the children in the _global object without first un-hiding the properties from the for..in loop construct:

for(i in _global){
    trace(i);
}

Nothing is outputted.

All of the predefined objects have their methods and properties hidden from the for..in loop construct, even the undocumented hidden objects. So if for example we wanted to find out what is contained inside of the NetConnection object we could use:

//un-hide all the children in the NetConnection
//objects prototype object
ASSetPropFlags(NetConnection.prototype,null,6,true);
//iterate over all the children of the
//NetConnection objects prototype object
for(i in NetConnection.prototype){
    trace(i);
}

An interesting find, the output is:

addheader
call
close
connect
__proto__
constructor

So, their is a set process you can follow to achieve the desired results, first choose the object you want to act upon ‘obj’, then choose the children of that object that you want to act upon and create an array of those names ‘props’, then choose the behaviour you want to achieve by looking up the correct argument value in the table further up in this article ‘n’ and then if you are wanting to turn off any of the protection behaviours; un-hide from for..in, un-protect from deletion, un-protect from over-write you need to pass the fourth argument as the boolean value ‘true’ otherwise just omit this argument(dont pass it).

Lets create an object containing some properties and methods which we cant test the different behaviours of this function on:

//create a new object
myproperties={};
//place a few properties inside
myproperties.firstname='Guy';
myproperties.surname='Watson';
myproperties.icq=71063418;

Now lets try out the different behaviours on this object.

First lets see what happens when we iterate over all the children in this object before using the ASSetPropFlags function, we will make this code a function so we can re-use it later:

//define the function that iterates
//over all the children of the myproperties object
function doIterate()
{
	for(i in myproperties)
	{
		trace(i);
	}
}

//call the function
doIterate();

Hide some children from the for..in loop construct:

ASSetPropFlags(myproperties,['firstname','surname'],1,1);

And then run the iteration function again:

doIterate();

The output window shows:

icq

Hide all children from the for..in loop construct:

ASSetPropFlags(myproperties,null,1,1);

And then run the iteration function again:

doIterate();

The output window shows nothing.

Un-hide a property to the mercy of the for..in loop construct:

ASSetPropFlags(myproperties,['icq'],0,1);

And then run the iteration function again:


doIterate();

The output window shows:

icq

Un-hide all children to the mercy of the for..in loop construct:


ASSetPropFlags(myproperties,null,0,1);

And then run the iteration function again:


doIterate();

The output window shows:

icq
surname
firstname

Protect a property from deletion:

ASSetPropFlags(myproperties,['firstname'],2,1);

Try to delete the property:

delete myproperties.firstname;

Was the property deleted?

trace(myproperties.firstname);

The output window shows:

Guy

Un-Protect a property from deletion:

ASSetPropFlags(myproperties,['firstname'],0,1);

Try to delete the property:

delete myproperties.firstname;

Was the property deleted?

trace(myproperties.firstname);

The output window shows:

undefined

Re-define the properties value so we can use it again in the further examples:

myproperties.firstname='Guy';

Protect all properties from deletion:

ASSetPropFlags(myproperties,null,2,1);

Try to delete the properties:

delete myproperties.firstname;
delete myproperties.surname;
delete myproperties.icq;

Were the properties deleted?

trace(myproperties.firstname);
trace(myproperties.surname);
trace(myproperties.icq);

The output window shows:

Guy
Watson
71063418

Un-Protect all properties from deletion:

ASSetPropFlags(myproperties,null,0,1);

Try to delete the properties:

delete myproperties.firstname;
delete myproperties.surname;
delete myproperties.icq;

Were the properties deleted?

trace(myproperties.firstname);
trace(myproperties.surname);
trace(myproperties.icq);>/pre>

The output window shows:

undefined
undefined
undefined

Re-define the property values so we can use them again in the further examples:

myproperties.firstname='Guy';
myproperties.surname='Watson';
myproperties.icq=71063418;

Protect a property from being over-written:

ASSetPropFlags(myproperties,['firstname'],4,1);

Try to over-wrtite the property:

myproperties.firstname='Richard';

Was the property over-written?

trace(myproperties.firstname);

The output window shows:

Guy

Un-protect a property from being over-written:

ASSetPropFlags(myproperties,['firstname'],0,1);

Try to over-write the property:

myproperties.firstname='Richard';

Was the property over-written?

trace(myproperties.firstname);

The output window shows:

Richard

Re-define the property so that we can use it in further examples:

myproperties.firstname='Guy';

Protect all properties from being over-written:

ASSetPropFlags(myproperties,null,4,1);

Try to over-write all the properties:

myproperties.firstname='Richard';
myproperties.surname='Blackwood';
myproperties.icq=71063418;

Were the properties over-written?

trace(myproperties.firstname);
trace(myproperties.surname);
trace(myproperties.icq);

The output window shows:

Guy
Watson
71063418

Un-protect all properties from being over-written:

ASSetPropFlags(myproperties,null,0,1);

Dont forget that you can assign multiple behaviours at once, by choosing the appropriate argument value for ‘n’ from the table further up the page, so for example you can protect all the listed properties ‘prop’ from being over-written and from being deleted in the same function call, you could also do the same for only a selected list of properties by passing an array of the child names for the value ‘prop’, alternatively you could hide all the properties of an object and un-protect them from being deleted and over-written in the same function call. There are 7 different combinations of behaviours.

Personally, i usually use this undocumented feature to loop through all of the predefined objects to see what i can find lurking in the depths of hidden land, but i also use it to hide properties from for..in loop constructs and therefore also the ‘Control>List Variables’ output window when testing my scripts. This function comes in very handy when creating your own classes and also when you are defining methods and properties in the _global namespace, using ASSetPropFlags when defining methods and properties in the _global namespace can stop your code from being over-written or deleted.

For more information and examples related to ASSetPropFlags checkout the entry on the Flashcoders Wiki.