Exploring full-screen mode in Flash Player 9

ActionScript API

There are new ActionScript methods in ActionScript 2.0 and ActionScript 3.0 to initiate or leave full-screen mode, and corresponding events to notify the movie when full-screen mode begins or ends. As previously mentioned, the ActionScript to initiate full-screen mode works only in reaction to a mouse click or keypress.

ActionScript 2.0

Stage.displayState:String property

This property is gettable and settable. Possible values are:

• fullScreen
• normal

This property is used to check the current state of the movie or to enter or exit full-screen mode.

An event listener on the Stage object provides notification when the movie enters or leaves full-screen mode:

EventListener.onFullScreen = function( bFull:Boolean ){}
Stage.addListener( EventListener );

This method is called when the movie enters or leaves full-screen mode. The Boolean argument to this function indicates whether the movie has entered (true) or exited (false) full-screen mode.

Stage.fullScreenSourceRect:Rectangle property

This property lets you choose what part of the Stage will be scaled to fit the screen. It also triggers the hardware scaling mode. This property is a rectangle that can be anywhere on or off the Stage. It must be set before entering full-screen mode.

Adjusting fullScreenSourceRect after entering full-screen mode will not change the displayed region of a SWF. Also, if your rectangle has a different aspect ratio from the user's monitor, "bars" will be added on the sides, as appropriate, that are the same color as the background color of the SWF or background color for the SWF that is set in the HTML.

If a user has turned off hardware scaling in the Flash Player settings, or if Flash Player is running on a machine that is not capable of hardware scaling, fullScreenSourceRect will be ignored and normal software-rendered full-screen mode will be used instead.

ActionScript 3.0

flash.display.Stage.displayState:String property

This property is gettable and settable. The valid values are from the class StageDisplayState:

• StageDisplayState.FULL_SCREEN
• Stage.DisplayState.NORMAL

This property is used to check the current state of the movie or to enter or exit full-screen mode.

An event listener on the Stage object provides notification when the movie enters or leaves full-screen mode:

fullScreenHandler = function( event:FullScreenEvent ) {};
stage.addEventListener( FullScreenEvent.FULL_SCREEN, fullScreenHandler );

The AS3 event received is FullScreenEvent, which extends ActivityEvent. FullScreenEvent has a Boolean fullScreen property, which indicates whether the movie has entered (true) or exited (false) full-screen mode.

ActionScript 3.0 will throw a security error in the plug-in or ActiveX control if the display state is set to StageDisplayState.FULL_SCREEN when it is not permitted by one of the security restrictions listed above.

flash.display.Stage.fullScreenSourceRect:Rectangle property

This property lets you choose what part of the Stage will be scaled to fit the screen. It also triggers the hardware scaling mode. This property is a rectangle that can be anywhere on or off the Stage. It must be set before entering full-screen mode.

Adjusting fullScreenSourceRect after entering full-screen mode will not change the displayed region of a SWF. Also, if your rectangle has a different aspect ratio from the user's monitor, "bars" will be added on the sides, as appropriate, that are the same color as the background color of the SWF or background color for the SWF that is set in the HTML.

If a user has turned off hardware scaling in the Flash Player settings, or if Flash Player is running on a machine that is not capable of hardware scaling, fullScreenSourceRect will be ignored and normal software-rendered full-screen mode will be used instead.

Using the new ActionScript APIs

To ensure that you do not get errors when publishing a movie using the new full-screen ActionScript, you may need to update your installed version of Flash CS3 Professional or the Flex SDK.

If you are using ActionScript 3.0 with Flash CS3 Professional or with Flex Builder using the Flex 2.0.1 SDK, the ActionScript 3.0 class files will support the new full-screen ActionScript. No action is necessary.

If you are using ActionScript 2.0 with Flash CS3 Professional and publishing your movie as Flash 9, the ActionScript 2.0 class files will contain the new ActionScript properties and you should not get any errors. If you would like to publish as an earlier version of Flash, you can use the somewhat ugly syntax:

Stage["displayState"] = "fullScreen";

rather than the nicer:

Stage.displayState = "fullScreen";

Scaling

The scaling behavior in software-rendered full-screen mode is determined by the movie's scaleMode setting, set through ActionScript or the <object> and <embed> tags. The default scaleMode setting is showAll, which means that in full-screen mode the movie will be stretched to the size of the screen but its aspect ratio will be maintained. If you want to control the scaling behavior of the movie programmatically, the scaleMode should be set to noScale. In this case, the movie will not be scaled but the Stage width and height properties will be updated in full-screen mode to indicate the new size of the Stage, and the Stage resize event handlers will be called.

If you are using hardware-scaled full-screen mode by supplying a fullScreenSourceRect, the SWF scaling does not affect how the full-screen mode functions.

Page 2 of 4

Previous Page

Next Page