What Every Flash Developer Ought to Know About flash.display.StageScaleMode

While this post is only cursory related to using YouTube, it is important knowledge if you want to create fullscreen Flash applets and/or make sure they resize properly. So I have made it part of the series. In this post I’ll explain the StageScaleMode, which is a property that sometimes causes, what appears to be, weird behavior.

A recap of the ActionScript 3.0 YouTube player series:

• Getting a list of videos (and some project setup)
• A bit about how the Flash stage works and fullscreen [this post]
• Install a php script to get the randomly generated key
• Getting the key for a video
• playing the video using Flash’s FLV player classes

If you are an experienced Flash developer, you might want to skip this section, but it got me puzzled for a while. If you want to use the fullscreen mode of Flash, you’ll probably need a little knowledge of how a Flash applet can be resized. You could fix everything, so that images stay the same size, no matter how large your window is, but that would result in empty borders around the picture. It will look better if the video scales with the size of the applet. However, the interface elements usually don’t scale, or else you’d get giant play and pause buttons. To obtain this, you need to handle resizing yourself.

First I’d suggest to try out this basic applet. It’s not user friendly, but it should give you an idea of how this thing works. Open it in a new window and resize away. Then change the scaleMode attribute to see how Flash handles resizing (click on the text to change it):

The full code is available, but the important part is actually only a few lines:

1
2
3
4
5
6
7
8
9
10

private var modes:Array = new Array(StageScaleMode.EXACT_FIT,
				StageScaleMode.NO_BORDER,
				StageScaleMode.NO_SCALE,
				StageScaleMode.SHOW_ALL);
private var current:Number = 0;
private function changeMode(event:MouseEvent):void {
	stage.scaleMode = modes[++current % 4];
	modeText.text = "current stage scale mode: " + stage.scaleMode;
	event.stopPropagation();
}

Setting the stage.scaleMode attribute makes all the difference when resizing. Everytime you click on the text, the program will rotate over the 4 different possible values for the scaleMode:

• StageScaleMode.EXACT_FIT: This stretches the image to fit the entire screen. Thus the image is deformed. You’re probably never going to need this mode, unless in very special circumstances.
• StageScaleMode.NO_BORDER: Makes sure that the application fills the entire screen without deforming. No borders will be visible (unlike SHOW_ALL), but some parts of the application might drop of the screen. When using this mode, take extra care that user interface elements do not fall of the screen. In example applet, if you resize it just right, you can no longer change the mode. This is not exactly what you’d want in a finished application.
• StageScaleMode.NO_SCALE: This is the easiest mode: just leave everything as is. This is the mode you want if you need complete control.
• StageScaleMode.SHOW_ALL: Always show the entire applet, and keep the aspect ratio fixed (no stretching). In many cases this will be the best choice. It might however cause borders to appear alongside your applet.

Once you got that working, the Flash fullscreen mode is really a piece of cake. You need to do two things to make it happen:

• In the ActionScript code change the display state of the stage:

1

stage.displayState = StageDisplayState.FULL_SCREEN;

• If you run the applet now, you will get a security exception. On the page where you use the applet, you must explicitly specify that the applet is allowed to go fullscreen. If you use the index.html that FlashDevelop generates for you, you need to add the “allowFullScreen” parameter to the JavaScript loader:

1
2
3
4
5

var params = {
	menu: "false",
	scale: "noScale",
	<strong>allowFullScreen: "true"</strong>
};

Note:

• I have now added the SWF metadata to specify screen size. I find it a little more convenient than specifying it in the properties. See Derek’s post about it for more info [via the comments here].

Conclusion

In this post I’ve shown you that the StageDisplayState could be important to your Flash applet and how to use it. I have also demonstrated how easy it is to go full screen in Flash. I hope you enjoyed this post and let me know if you create anything based on it.