Where does it come from? Clearly it’s built into the Flash Player, but what may be surprising is that when it displays, it is actually added to the stage. It doesn’t float above the stage, it is added to the stage. This is no big deal… usually.

To consider when it might be a problem, try hitting the fullscreen button then hitting the draw button in the demo below. (Depending on the size of your screen, mouse skills will probably be required!)

One of the problems with adding the display to the stage is that it sits in a different security domain to your application. If your application attempts to reference the stage, for example to draw the stage into a BitmapData, then you get hit with a Security sandbox violation. Of course, if your mouse skills weren’t up to it and the element had removed itself from the stage, the error would not occur.

Now, there is probably no good reasons why you should ever need to take draw a copy of the stage, and in fact I found this error because I had (or maybe a colleague had?) done it when I wanted to draw a copy of a particular element. However, since screen-wipe transitions and other effects could easily be implemented in such a way (and since their implementation usually precedes implementing a fullscreen button), the potential for this error does exist.

It doesn’t look like anyone has noticed this error before. I searched for https://www.macromedia.com/support/flashplayer/sys/ in JIRA and Google and didn’t find anything useful. I present it here in the hope that at least one other person won’t be skewered on this AS3 Gotcha like me!

ps. I took some liberties with the code as displayed in the demo above. For full disclosure, view the real source code on GitHub.

Error: Error #2078: The name property of a Timeline-placed object cannot be modified.
	at flash.display::DisplayObject/set name()
	at flash.display::Sprite/constructChildren()
	at flash.display::Sprite()
	at flash.display::MovieClip()

The culprit? I had named a MovieClip instance within the IDE “name”, which the Flash player doesn’t like at all. It would have been good of the IDE to warn me of this problem (ie, scan the named MovieClips in an FLA and check for reserved words), or give me a more graceful error message, but sadly not. Instead I had to find it the hard way – changing stuff and publishing, changing stuff and publishing, changing stuff and publishing… Hopefully this will save someone a few minutes!

Back to work, and I was doing a little prototyping this evening, when I came across a familiar problem: In AS3 we can use

[Embed(source="asset.swf", symbol="symbol")]
private var symbolClass:Class;

var symbol:MovieClip = new symbolClass();

to embed a symbol from an art SWF in what is probably a code-built SWF. That’s great, but what if you want to embed an entire SWF?

[Embed(source="asset.swf")]
private var assetClass:Class;

var asset:MovieClip = new assetClass();

looks like it should do the trick, but you can’t access any of the information within the asset. That’s a real pain, the reason for which is pretty convoluted. I remembered working around this problem in the past, and happily managed to unearth a long-forgotten treasure in my codebase, which I thought I’d share (having rapidly refactored it to use as3-signals, naturally).

package com.alecmce.util
{
	import org.osflash.signals.Signal;

	import mx.core.MovieClipAsset;

	import flash.display.Loader;
	import flash.display.LoaderInfo;
	import flash.display.MovieClip;
	import flash.events.Event;

	public class UnpackEmbed
	{
		private var _ready:Signal;

		private var _asset:MovieClipAsset;
		private var _content:MovieClip;

		public function UnpackEmbed(assetClass:Class)
		{
			_asset = new assetClass();
			_ready = new Signal(UnpackEmbed);

			var loader:Loader = Loader(_asset.getChildAt(0));
			var info:LoaderInfo = loader.contentLoaderInfo;
			info.addEventListener(Event.COMPLETE, onLoadComplete);
		}

		private function onLoadComplete(event:Event):void
		{
			var info:LoaderInfo = LoaderInfo(event.target);
			info.removeEventListener(Event.COMPLETE, onLoadComplete);

			_content = MovieClip(info.loader.content);
			_ready.dispatch(this);
		}

		public function get content():MovieClip
		{
			return _content;
		}

		public function get ready():Signal
		{
			return _ready;
		}

		public function get asset():MovieClipAsset
		{
			return _asset;
		}
	}
}

When you embed a SWF in this way then instantiate it, Flash somehow conspires to create a MovieClipAsset with a Loader inside, which will be ‘loading’ the already-embedded content. The content is not available immediately (it may be sometimes, I have encountered cases where it was not), so you have to wait for an Event.COMPLETE to be fired before you can access it. This class exposes a signal that informs you when the content is ready. It could probably be more rigorous, such as including an isComplete flag, but it serves my purposes, when used in the following manner:

[Embed(source="asset.swf")]
private var assetClass:Class;

asset = new UnpackEmbed(assetClass);
asset.ready.addOnce(onAssetReady);

private function onAssetReady(asset:UnpackEmbed):void
{
	// now we can access the asset.content!
}

// given two sprites called "a" and "b"...

a.transform.matrix = new Matrix(-.5, 0, 0, -.5, a.x, a.y);
b.scaleX = b.scaleY = -.5;

trace(a.scaleX, a.scaleY, b.scaleX, b.scaleY); // outputs: 0.5, 0.5, -0.5, -0.5

Both clips have been scaled by -0.5, but because the transform was used to produce the scale for a, the scaleX/Y variables do not reflect the object’s true scale.

Now, just to confuse yourself, add a third sprite to the stage:

// given another sprite called "c"...

c.transform.matrix = new Matrix(-.5, 0, 0, -.5, c.x, c.y);
c.scaleX = c.scaleY = -.5;

Curiouser and curiouser! This needed a more complete experimentation…

The source for this experiment can be found here: scaleAndTransform. The buttons call the following methods:

function onGo(event:Event):void
{
	a.transform.matrix = new Matrix(-.5, 0, 0, -.5, a.x, a.y);

	b.scaleX = b.scaleY = -.5;

	c.transform.matrix = new Matrix(-.5, 0, 0, -.5, c.x, c.y);
	c.scaleX = c.scaleY = -.5;
}

function onResetScale(event:Event):void
{
	a.scaleX = a.scaleY = 1;
	b.scaleX = b.scaleY = 1;
	c.scaleX = c.scaleY = 1;
}

function onResetTransform(event:Event):void
{
	a.transform.matrix = new Matrix(1, 0, 0, 1, a.x, a.y);
	b.transform.matrix = new Matrix(1, 0, 0, 1, b.x, b.y);
	c.transform.matrix = new Matrix(1, 0, 0, 1, c.x, c.y);
}

What Is Going On?

If you apply a transformation matrix then a scale, the magnitude of the scale is applied, but the direction is determined by the product of the transformation and the scalar… which is to say that:

a.realScaleX = (a.transform.matrix.a * a.scaleX > 0 ? 1 : -1) * a.scaleX;

If however you apply a scale then a transformation, the scale is defined by the transformation only!

a.realScaleX = a.transform.matrix.a;

Bug?

Does this qualify as a bug? I haven’t thought about this for long enough. The conditions in which a transformation matrix rotates and skews the MovieClip confuse me; how would I define scaleX and scaleY in that scenario? I need to give this some thought; perhaps you the community can give me some help! I am reluctant to call anything a bug immediately now, after my experience with my The Problem With Vector.<T> post, where I was just plain wrong!

A similar bug exists in Adobe JIRA: UIComponent.scaleX, scaleY differ from transform.matrix.a,d. You’ll need an account to look at this – it’s free, and once you’ve got it you can pester Adobe with your bugs too.

var list:Vector.<MockObject> = new Vector.<MockObject>();

var a:MockObject = new MockObject("a");
var b:MockObject = new MockObject("b");
var c:MockObject = new MockObject("c");

list.push(a);
trace(list);			// outputs "a"

list.push(b);
trace(list);			// outputs "a,b"

list.unshift(c);
trace(list);			// outputs "c,a"

No, I haven’t made a mistake. It’s a bug! The Flash 10 Language Reference explicitly says that this isn’t supposed to happen. After a little searching, Adobe JIRA affirms that this bug is known, and fixed – well fixed in the ‘Future – Next Build’ release.

I really hate wasting two hours of my time to discover that my test case is failing because the Flash Player is itself broken, and not because I’m an idiot. Clearly, Adobe don’t unit test. As ever, I am really glad that I do!

private const DATA:XML = <data message="Hello World!" />;

and

private const DATA:String = "Hello World!";

are intuitively the same sorts of things. XML is like an advanced sort of String. We encode it as we encode text, and we convert it to and from Strings without difficulty. I don’t construct XML, at least it doesn’t feel like I do. In my preferred coding environment (FDT) by default they’re even similarly coloured.

However, they are clearly not the same, because XML is mutable:

DATA.@message = "This message has been changed!";

Needless to say, that doesn’t work on a String! Somehow by labelling the XML a ‘constant’ I expect the XML to be immutable.

On reflection I know this about XML, but it feels wrong. This ‘gotcha’ does not identify a language bug, but suggests a mental corrective: when you think about XML, make sure that you don’t mistake it for a primitive type. When I’m not concentrating I do, and it occassionally trips me up.

addEventListener(BulkLoader.ERROR, function (e:Event):void{}, false, 1, true);

I passed malformed XML into the loader, and found that about 25% of the time, I was getting just such a stack trace. I was not changing anything, but simply running and re-running a whole list of tests, with this test among them. The only thing that I could think of is that the Garbage Collector was occassionally considering the event listener available for collection and was removing it. Testing that hypothesis, I replaced the code with:

addEventListener(BulkLoader.ERROR, squashError, false, 1, true);
...
private function squashError(event:Event):void {}

and the error disappeared. I have posted a patch to the Bulk Library codebase, so hopefully it will be resolved soon.

There’s Nothing New Under The Sun

I’ve known about Grant Skinner’s analysis of event listeners for years, and have accepted that event listeners should always be defined weakly for as long. However, that article contains the very point that I have spent an afternoon rediscovering! It turns out I’ve been doing work that Grant Skinner did three years ago on behalf of another third party library vendor… which is disheartening because if I knew that article in more detail I could have saved my afternoon. It’s encouraging as well though; there’s a cliché about earning your learning somewhere…

var xml:XML = new XML(null);

Personally I don’t think that constructing XML from a null object should work, but it does. I would have expected an error, like if I try to do this:

var xml:XML = new XML("<bad>hello world</tags>");

That’s about as clear a case of error throwing as you can get, I think. Why not for null?

It turns out that null is interpreted as a sort of weird XML singularity. It has one node which has no name, to which you can add attributes and children. However much you add, always the length is 1 and the toXMLString() is an empty string. Happily, this latter fact can save you from being consumed by the singularity: you can test for it by checking whether

xml.toXMLString() == "";

and take appropriate steps if it does!

I haven’t thought through all the consequences of this behaviour but it took me completely by surprise… if you can explain to me why Adobe considered this the preferred behaviour, please let me know! This is another of those hard-to-spot XML bugs like this one I found earlier. Someone, preferably Simone since he’s already on it, should wrap fixes for this stuff into a helper class!

Update

var xml:XML = new XML(null);

is – of course – the same as

var xml:XML = new XML();

The documentation doesn’t indicate that you can pass an empty value into the XML constructor, but as my colleague Simone pointed out, playerglobal.swc indicates that you can. The documentation meanwhile says that the constructor parameter for an XML object should be

Any object that can be converted to XML with the top-level XML() function.

and the top-level XML function documentation states that if you pass a null into it:

null: A runtime error occurs (TypeError exception).

However, that doesn’t throw an error either!

I started this update having seen the playerglobal.swc definition about to eat some humble pie, but this further investigation has served to strengthen my understanding of how weird this behaviour is. Be warned, this stuff is out there waiting to spoil your afternoon’s coding!

Though I have created an artificial example to isolate the problem, it arose in a real-world situation. I had two package folders in which I intended to create tests. I created all the AllTest TestSuites but only populated one of the packages with tests. When I tried to run the TestRunner to see the results of these tests, though they appeared to have run the TestRunner had never completed.

The source of the problem lies in the architecture of the TestSuite class, the main functionality for which is launched by the run method but which dispatches an event to indicate that it has finished performing tests in its testCompleteHandler method. However, testCompleteHandler can only ever be triggered as a consequence of a test completing in run, so if no tests are defined, the TestSuite never finishes.

Update

I posted my resolution of this problem on github, but it has since been merged to the asunit trunk, so I have removed the github repository. My solution added checks for empty TestCases and TestSuites to prevent the TestRunner trying to run them.

var flag:Boolean;
var xml:XML;

flag = false;
xml = <xml value={flag} />;
flag = xml.@value;

trace(xml.toXMLString());
trace(flag);

The result is that serializing a Boolean into XML and deserializing it from XML will break. Happily, the solution is simple, to retrieve the value

flag = xml.@value == "true";

will guarantee that the Boolean is cast correctly.