When building modular Flash applications, a common error that may be encountered is that related to accessing a property or method of the stage property when it is still null. If a display object is not yet added to the display list, its stage property returns null.

An ActionScript error has occurred: “Cannot access a property or method of a null object reference.”

Quite a cryptic message, especially if you test the module SWF standalone and nothing seems wrong, but the error is thrown when you load the module SWF into a host SWF.

Background of the Problem
When a module SWF is loaded into a host SWF, the constructor of the top-level class of the module SWF will be called before the instance itself (Sprite or MovieClip) is added to the display list. In other words, the stage property will still be null when the class is being instantiated and therefore, referencing a property or method of the Stage object (via the stage property) in the constructor of the top-level class will result in a “null object reference” error.

The same occurs, of course, if the constructor does not reference a property or method of the stage directly, but calls another member (function or get/set property) that does so.

Example of the Problem
Let’s take for example we want the application to be notified when the Stage is resized and will therefore attach a listener to the Stage. The following will work if the SWF is run standalone, but will throw the “null object reference” error if it is loaded into a host SWF:

package 
{
	import flash.display.Sprite;
	import flash.events.Event;
 
	public class Module extends Sprite 
	{
		public function Module()
		{
			init();
		}
 
		private function init():void
		{
			stage.addEventListener(Event.RESIZE, on_stageResize);
			// stage is null, cannot access method of null object, error is thrown
		}
 
		private function on_stageResize(evt:Event):void
		{
			// ** actual application code begins **
			trace("stageWidth: " + stage.stageWidth + " stageHeight: " + stage.stageHeight);
		}
	}	
}

Fix for the Problem
To avoid such an error, simply wait until the display object has been added to the Stage before referencing its stage property. You can do this by listening to the Event.ADDED_TO_STAGE event:

package 
{
	import flash.display.Sprite;
	import flash.events.Event;
 
	public class Module extends Sprite 
	{
		public function Module()
		{
			addEventListener(Event.ADDED_TO_STAGE, init);
		}
 
		private function init(evt:Event):void
		{
			removeEventListener(Event.ADDED_TO_STAGE, init);
			// remove the event listener, because it is possible for the instance
			// to be removed from its container, and re-added to the display list
			// and invoking the event again but we want to call the init method
			// only once per instance of the class
 
			// ** actual application code begins **
			trace(stage); // stage is no longer null
			stage.addEventListener(Event.RESIZE, on_stageResize);
		}
 
		private function on_stageResize(evt:Event):void
		{
			// ** actual application code begins **
			trace("stageWidth: " + stage.stageWidth + " stageHeight: " + stage.stageHeight);
		}
	}	
}

As mentioned above, even if the constructor itself does not reference a property or method of the stage directly, but calls another member (function or get/set property) that does so, or the member calls another member that does so, and so on (you get the idea)… this “null object reference” error will still occur. The referencing may be deeply nested, and therefore, it is probably best to make it a habit to have your top-level class listen for the Event.ADDED_TO_STAGE event before executing other code:

package 
{
	import flash.display.Sprite;
	import flash.events.Event;
 
	public class Module extends Sprite 
	{
		public function Module()
		{
			if (stage) init();
			else addEventListener(Event.ADDED_TO_STAGE, init);
		}
 
		private function init(e:Event = null):void 
		{
			removeEventListener(Event.ADDED_TO_STAGE, init);
 
			// ** actual application code begins **
			trace(stage); // stage is no longer null
		}
	}	
}

FlashDevelop
If you are using the FlashDevelop IDE, the Main.as class file, written in the way described above, will be created automatically for you when you create a new Project using the “AS3 Project” template. However, when writing module classes and compiling them using the Quick Build command, it will be up to you to remember to write them in the way described above (and it is especially for module SWFs that you need to do this).

Reminder:
A Flash application has only one Stage object – display objects in both the host SWF and in any loaded SWF(s) reference the same Stage. Do not confuse stage with the root property.

Other Posts You Might Enjoy:

• [AS3] Applying ROT128 Encryption On Embedded/Module SWFs
• [AS3] Difference Between Stage Size, Screen Size And SWF Size
• [AS3] Hiding Assets And Code By Embedding SWF Within Another SWF
• [AS3] Simple Editor For Loading And Saving XML As Binary
• [AS3] Hiding the Built-In Native MenuBar (And ContextMenu Items)

Comments RSS