Tiitle: The Stage Object
Level: Beginner
Author: Benjie Moss
Website: www.232.info

The Stage object (an introduction to listeners)

Level: Beginner
Author: Benjie Moss
Website: www.232nd.net

One of the most common questions asked in the forums is how to centre the flash movie in a browser window. There are various possibilities including tables, CSS or javascript. Actionscript has it's own built in solution: The Stage object.

This tutorial is a gentle introduction to listeners, focusing on the Stage object, which will be used to centre a movie in a browser window. This is a beginner tutorial, so I'll not assume an in depth understanding of actionscript, however familiarity with the flash authoring environment will be helpful. All you need is a copy of Flash MX (2004 not required), a text editor (simpletext on the mac or notepad on pc will be fine) and a web browser. I'll start by giving a brief explanation of the Stage object, followed by the technique used for positioning your .swf in the centre of a browser window, and finally we'll look at making the whole thing interactive, with listeners and the onResize() listener event.

Introducing the Stage object

Stage is a predefined object available for the flash 6 player. It is used to access the properties of the display area of the flash file. It has five properties (align, width, height, scaleMode and showMenu), a couple of methods (addListener() and removeListener()) and a listener event (onResize()). The properties are as follows:

  • Stage.align: can be read and written in actionscript and provides a means of positioning the movie’s contents on the stage.
  • Stage.width: cannot be directly written in actionscript. It can be read, and provides a means of accessing the width of the visable area of the flash movie from left to right.
  • Stage.height: identical to Stage.width excepting that it reads top to bottom.
  • Stage.scaleMode: can be written and read in actionscript and provides a means of scaling the contents of a movie relative to the stage.
  • showMenu: dictates the contents of the menu when a user ctrl+click (mac) or right clicks (pc) your file. This one is irrelevent to this tutorial.

Stage.scaleMode

Open flash and create a new movie (save it as anything you like). If it's not already open, open the properties panel (Window > Properties) and click the button after 'Size:'. Set the dimensions of the movie to 100px (width) and 100px (height) then click 'OK'. Using the rectangle tool, draw a square on the stage, use the arrow tool to select your square, then in the properties panel set the width to 100, height to 100, x to 0, and y to 0 so it completely covers the stage. (Note: do not simply change the background colour of your movie, the square itself is necessary.) Publish your movie for both .swf and .html ensuring under the html tag that dimensions is set to 'Percent' and that the width and height are set to 100 percent. Save your file.

Open your text editor and open the .html file flash has just produced for you. The code should look something like this (Note: I've highlighted the html that's important):

<HTML>
<HEAD>
<meta http-equiv=Content-Type content="text/html; charset=ISO-8859-1">
<TITLE>stagetutorial</TITLE>
</HEAD>
<BODY bgcolor="#FFFFFF">
<!-- URL's used in the movie-->
<!-- text used in the movie-->
<OBJECT classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000"
codebase="http://download.macromedia.com/pub/shockwave/cabs/flash/swflash.cab#version=6,0,0,0"
WIDTH="100%" HEIGHT="100%" id="stagetutorial" ALIGN="">
<PARAM NAME=movie VALUE="stagetutorial.swf"> <PARAM NAME=quality VALUE=high> <PARAM NAME=bgcolor VALUE=#FFFFFF> <EMBED src="stagetutorial.swf" quality=high bgcolor=#FFFFFF WIDTH="100%" HEIGHT="100%" NAME="stagetutorial" ALIGN="" TYPE="application/x-shockwave-flash" PLUGINSPAGE="http://www.macromedia.com/go/getflashplayer"></EMBED>
</OBJECT>
</BODY>
</HTML>

Now open the html file, flash produced for you, in your web browser. You'll see that it resizes as you resize the window, and that it's centered in the browser window.

Open up your file again in flash and select the first frame. Open the actionscript panel and type the following script:

Stage.scaleMode = "exactFit";

Publish your file again and open the html file in your browser and you'll see the movie now distorts the shape of your square to match the browser window, even when you resize the window.

There are four options in total:

  • "exactFit": as you've seen, exactFit distorts the movie's contents to fit the browser window.
  • "noBorder": scales the movie's contents to the maximum available. If the width of the browser window is larger than the height then the square will have the width and the height equal to the browser window's width. This option almost always crops some of your movie.
  • "showAll": scales the movie's contents without distortion. So the smaller of the browser's width and height is the size of the square. This is the exact opposite of noBorder, and you won't crop anything.
  • "noScale": doesn't scale the movie's contents at all, even when the stage itself is resized.

Change your script to "noScale". I have found this to be the most useful option and it’s required for the rest of this tutorial. Your one line script should now look like this:

Stage.scaleMode = "noScale";

Save and publish and open your html file in your browser and you'll see your 100x100 px square, scaled to 100% and sitting in the middle of your window. If you ctrl+click (mac) or right click (pc) outside your square you'll see the menu appear. The menu appears because the stage (the viewable area of your flash movie) has been resized to match the browser window, the content of the movie has not been resized however. Even though Flash published a stage that was 100x100 pixels and a square of the same dimensions, what’s being displayed in your browser window is a square 100x100 pixels and a stage area that proportionally matches the size of the browser window.

This carries important implications: If you had a second square sitting just off to the side of the stage, it would now be visible, because the stage has grown in size.

Stage.align

The reason your .swf is positioned in the centre of the browser window is that we have not altered the Stage.align property from it's default, which is an empty string, indicating centre alignment. There are nine options for the align property. They're pretty self explanatory:

  • "" : centered
  • "T" : top
  • "RT": right top
  • "R" : right
  • "RB" : right bottom
  • "B" : Bottom
  • "LB" : left bottom
  • "L" : left
  • "LT" : left top

For the purposes of the rest of the tutorial I'd suggest "LT" to position the movie to the top left corner of the window because currently (0,0) in actionscript corresponds to the top left of our square, and life is a lot easier if we make (0,0) the top left of the browser window. Modify your code to appear thus:

Stage.scaleMode = "noScale";
Stage.align = "LT";

Stage.height & Stage.width

At this point the stage is set to fill the browser window, but not to scale the content and to align to the top left of the browser window. To align the content to the centre of the screen we read the Stage.height and the Stage.width properties, slot in some math and move our square accordingly. The first thing to do is open your flash file, select the square and convert it to a movieclip (Insert > Convert to symbol...). Name the symbol, ensure that movie clip (not button or graphic) is selected and that the registration point is top left, then click 'OK'. In the instance name box of the properties panel enter the instance name "square" (without the quotes). Now modify your script so it looks like this:

Stage.scaleMode = "noScale";
Stage.align = "LT";
square._x = Stage.width/2;
square._y = Stage.height/2;

Save, publish and test in your browser and you'll see that the registration point of the square is in the centre of the browser window, making the square itself offset from centre. To make the centre of the square match the centre of the browser window we modify the script to take account of the square's width and height:

Stage.scaleMode = "noScale";
Stage.align = "LT";
square._x = (Stage.width/2) - (square._width/2);
square._y = (Stage.height/2) - (square._height/2);

Your square is now positioned in the centre of the browser window. Try resizing your browser window and you'll see that the square maintains it’s position, we’ll deal with that next.

Stage.addListener() & Stage.onResize()

The square does not move to the new centre of the browser window when the window is resized because our script runs once. Resize the window, and unless the script runs again it doesn't know we want it to reposition the square, as far as Flash is concerned it did what we told it, and now it’s forgotten all about it. We have three methods of telling flash to perform the script again. We could add another frame after the first and put a gotoAndPlay(1) script on it, but that's clunky, and makes using the script in another movie awkward. We could enclose the script in an onEnterFrame, so it executes each frame (12 times a second if you're set at the default 12 fps), but that uses up system resources unnecessarily. Fortunatly Macromedia have built in a solution using listeners, this is edging towards more complicated arenas, but the script we're using is simple, so don't worry. You need to modify the script to look like this:

Stage.scaleMode = "noScale";
Stage.align = "LT";
Stage.addListener(square);
square.onResize = positionSquare;
function positionSquare() {
  square._x = (Stage.width/2)-(square._width/2);
  square._y = (Stage.height/2)-(square._height/2);
}
positionSquare();

If you save and publish the movie then test in your browser you'll see the square is vertically centered, even when you resize the window.

The first new line of script uses the addListener() method of the Stage object to add the movieclip square to the list of objects that get notified when Stage resizes. Because that's a fairly abstract concept here’s an analogy: When a lumberjack chops down a tree s/he shouts "TIMBER!" to his/her colleagues. They don't need to keep checking if the tree is falling because s/he will notify them. In this case the Stage is the tree, the user resizing the browser window is the lumberjack and using addListener() we've made the square the colleague that needs to notified when (and only when) the event occurs.

The second new line uses onResize which officially, is a listener event. The line says that when the square object recieves notification from the Stage object that it has resized the positionSquare function should be run. To continue the lumberjack metaphor, it's the equivalent of the colleague of the lumberjack knowing that when "TIMBER!" is heard s/he needs to do something.

The third line declares the positionSquare function, the sixth ends the function, Meaning that when the function is called the script inside the curly brackets will be performed. A function is one or more lines of script that can be called over and over again. Every time the lumberjack shouts his/her warning the colleague knows s/he has to do something, in this case s/he needs to get out the way, just as our square now knows it needs to position itself.

The final line calls the positionSquare() function. This is important, if this line were not included then the square would position itself centrally when the movie was resized. But what if the movie were never resized by the user? Calling the function once, as soon as the movie loads ensures the square movie clip will begin in the correct position.

That's the end of this beginner's introduction to the stage object and listeners. Hopefully you found it useful.