In this post, we look at three different pairs of width and height properties that are commonly misunderstood – “stage.width/stage.height“, “stage.stageWidth/stage.stageHeight” and “loaderInfo.width/loaderInfo.height“.

Stage Size: stage.width / stage.height
The Stage refers to the main drawing area on which all Flash content is drawn. This area will encompass all display objects on the display list since all display objects are ultimately contained within the same Stage object.

The stage.width and stage.height properties give you the dimensions of the current rectangular bounds of the Stage. You can actually get the same results by querying the getBounds() method:

var bounds:Rectangle = stage.getBounds(stage);
trace(bounds.width == stage.width); // true
trace(bounds.height == stage.height); // true

These dimensions only take into account the area occupied by display objects and are therefore not necessarily computed from the origin (coordinates 0,0). For example, if there is only one display object on the display list and this object is 100px wide by 50px tall, the stage.width property returns 100 regardless of the x position of the object. Likewise, the height property returns 50 regardless of the y position of the object.

If you wish the dimensions to take into account the origin (0,0), you can place an invisible dot there:

var dot:Shape = new Shape();
dot.graphics.beginFill(0,0); // black transparent
dot.graphics.drawRect(0,0,1,1); // 1x1
dot.graphics.endFill();
stage.addChild(dot);

If there is nothing on the display list, or if all the display objects on the display list are empty (or of size zero), both stage.width and stage.height return zero (0). That is why if you query these properties at the very beginning of your application before you have anything on the display list, you can expect the value of both properties to be zero.

Screen Size: stage.stageWidth / stage.stageHeight
The stage.stageWidth and stage.stageHeight properties give you the current dimensions of the viewable screen area of the Flash Player (standalone window area or browser plug-in area).

Although these properties are read-write, setting them in your application code has no effect. No error will be thrown, but there will simply be no effect. A change in the value of these properties is typically end-user invoked when the end-user resizes the Flash Player. Your application can get notified of changes in these properties by listening for the Event.RESIZE event, dispatched by the Stage object.

stage.addEventListener(Event.RESIZE, on_stageResize);
 
function on_stageResize(evt:Event):void
{
    trace("screen width : " + stage.stageWidth);
    trace("screen height : " + stage.stageHeight);
}

Adobe’s documentation indicates that if you do not set stage.scaleMode property to StageScaleMode.NO_SCALE, then the stage.stageWidth and stage.stageHeight properties give you the original dimensions of the SWF file, the size that was specified during author-time in the Document Properties dialog box.

However, that is not true.

Contrary to what is stated in Adobe’s documentation, the stage.scaleMode property has no effect on the stage.stageWidth and stage.stageHeight properties. Regardless of the value of the stage.scaleMode property, be it set to StageScaleMode.NO_SCALE or otherwise, the stage.stageHeight will always give you the current height of the screen area occupied by the Flash Player, and the stage.stageWidth the current width. To implement these properties in the way the documentation described would have been wrong in the first place (it would have made the results confusing and less useful), so I would say this is simply a documentation error, not a Flash Player bug.

Knowing the current size of the Flash Player is useful if you wish to create fluid layout that responds to changes in the viewable screen area. These values are also required when checking if a certain display object is within or outside the bounds of the viewable area.

SWF Size: loaderInfo.width / loaderInfo.height
To obtain the original width and height of the SWF file, you must use loaderInfo.width and loaderInfo.height. These are read-only properties and stay constant. The values are hard-coded into the SWF file during compile time (you specify this size during authoring). Adobe’s documentation refer to these dimensions as the “nominal” width and height of the SWF file.

You must wait for the content to be sufficiently loaded before you can query these properties:

loaderInfo.addEventListener(Event.COMPLETE, on_loadComplete);
 
function on_loadComplete(evt:Event):void
{
    trace("swf width : " + loaderInfo.width);
    trace("swf height : " + loaderInfo.width);
}

If you are loading external content:

var ldr:Loader = new Loader();
ldr.contentLoaderInfo.addEventListener(Event.COMPLETE,on_loadComplete);
ldr.load(new URLRequest("module.swf"));
addChild(ldr);
 
function on_loadComplete(evt:Event):void
{
	var ldrInfo:LoaderInfo = evt.target as LoaderInfo;
	if (ldrInfo)
	{
		trace(ldrInfo.width);
		trace(ldrInfo.height);
	}
}

Knowing the nominal dimensions is useful when your application is hosting external module SWFs and you would like to know how much screen space to allocate to a loaded SWF (assuming that the dimensions that are hard-coded into the SWF should be honored). It is also useful if you wish to know the original aspect ratio of the content loaded into a Loader object (the width and height properties of the Loader object may be modified, but the values of loaderInfo.width and loaderInfo.height will always stay the same).

Conclusion
There is generally no correlation between the size of the Stage, the size of the viewable area, and the original size of the SWF.

If you want to know the current viewable area, use stage.stageWidth and stage.stageHeight.

If you want to know the original dimensions of a SWF when it was compiled, use loaderInfo.width and loaderInfo.height.

If you want to know the composite, total area occupied by display objects, you can use the stage.width and stage.height properties (or the getBounds() or getRect() methods).

It is easy to get confused over these three pairs of properties, so hopefully the above has helped to clarify on the differences.

Other Posts You Might Enjoy:

• [AS3] Avoiding NULL Object Reference Error When Loading Module SWF
• [AS3] Truncating ByteArray Does Not Dispose Contents, Free Up Memory
• [AS3] Hiding Assets And Code By Embedding SWF Within Another SWF
• [AS3] Domain Locking SWFs
• [AS3] Applying ROT128 Encryption On Embedded/Module SWFs

Comments RSS