Preorder Estimated Availability Date. Your credit card will not be charged until the product is shipped. Estimated availability date is subject to change.Preorder Estimated Availability Date. Your credit card will not be charged until the product is ready to download. Estimated availability date is subject to change.

Requirements

User level

Required products

Sample files

The rise in broadband penetration has enabled tremendous growth in the use of video on the web. According to a March 2007 comScore Video Metrix rankings study, five out of every seven Internet users (71.4 percent) in the US streamed video online. In addition, a June 2007 Pew Internet & American Life Project report states that 47% of adults in the US have high-speed connections at home.

Contributing to this trend, Flash video is being used to deliver new types of integrated, interactive video content and applications, as well as enabling new business models for video on the web. Ever since the release of Macromedia Studio 8 and Macromedia Flash Player 8, the use of Flash video exploded on the Internet for all kinds of content—from video sharing sites that highlight home videos of teens dressed as ninjas singing karaoke to movie trailers, ads, and full episodes of TV shows.

While Flash Player and Flash video currently provide a great video experience that "just works," it hasn't quite delivered on the full immersive experience many people posting video to the web would like to provide for their viewers. To enable a richer experience, one that takes the viewer out of the frame of the browser and fills the entire computer screen, you can take advantage of the full-screen mode in Adobe Flash Player 9 and later.

Although you can use full-screen mode for any type of Flash application, Flash video applications were the primary use case that the Flash Player team focused on in this initial implementation. For this reason, there are a number of security restrictions to full-screen mode (detailed in the next section), which may limit its usefulness with some fully interactive Flash applications or games. We hope to address these limitations in future versions of Flash Player as we continue to develop this feature.

How full-screen mode works

Full-screen mode was already supported in previous versions of the Flash stand-alone player and projectors, and we have not changed that implementation. However, we have added new ActionScript that will work in both the stand-alone player and the browser players, and a new HTML tag parameter allowFullScreen to enable the mode. The full-screen mode in Flash Player is initiated through ActionScript and can be terminated through ActionScript, keyboard shortcuts, or by the user switching focus to another window.

If you have the latest version of Flash Player installed, you can now also choose what part of your stage fills the screen. By assigning a value to fullScreenRect before going into full-screen mode, you can trigger a hardware-scaled view of your video that plays back your video with even better performance.

Because hardware scaling involves using capabilities of the user's video card, Flash Player will fall back to the original software-rendered full screen if the video card does not support this feature. Also, the user can choose to disable hardware scaling which will also cause the original software-rendered full-screen mode to be displayed.

Full-screen mode was not originally supported if the wmode is opaque or transparent windowless, but it is now supported starting with the latest version of Flash Player. If the user has multiple monitors, Flash Player uses a metric to determine the monitor that contains the greatest portion of the Flash movie and then goes full-screen in that main monitor.

You must have version 9,0,28,0 or later of Flash Player installed to use full-screen mode and 9,0,115,0 or later for hardware-scaled full-screen mode.

Security considerations

End-user security was a key consideration in the implementation of this feature, and developers need to understand the following end-user, security-related restrictions and design content accordingly:

To enable full-screen mode, developers must add a new <object> and <embed> tag parameter, allowFullScreen, to their HTML. This parameter defaults to false, or not allowing full screen. To allow full-screen, developers must set allowFullScreen to true in their <object>/<embed> tags.

An overlay dialog box will appear when the movie enters full-screen mode, instructing the user how to exit and return to normal mode. The dialog box appears for a few seconds and then fades out.

The ActionScript that initiates full-screen mode can be called only in response to a mouse click or keypress. If it is called in other situations, it will be ignored (in ActionScript 2.0) or throw an exception (in ActionScript 3.0).

Users cannot enter text in text input fields while in full-screen mode. All keyboard input and key-related ActionScript is disabled while in full-screen mode, with the exception of the keyboard shortcuts that take the viewer out of full-screen mode.

These restrictions apply to the Flash plug-in and ActiveX control but not to the Flash stand-alone player or Flash projectors.

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:

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:

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 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.

Sample application

As an example of how to use the new full-screen mode ActionScript, we show how to add a custom context menu containing items to allow your Flash movie to enter and leave full-screen mode. Take a Flash movie, any Flash movie, and add the following ActionScript to frame 1:

Publish template for Flash

To support the new <object> and <embed> tag parameters for full-screen mode, we have created a new publish template which is included with Flash CS3 Professional. It is a version of the basic "Flash only" template that will also add the proper tags to your HTML to allow full-screen mode.

Launch Flash CS3 Professional. In the Publish Settings dialog box, on the HTML tab, select Flash Only – Allow Full Screen from the the Template pop-up menu and publish your movie. Full-screen ActionScript will be enabled.

Publish template for Flex Builder

We have also provided HTML templates to be used with Flex Builder. These templates are modified versions of the default "express-installation" and "express-installation-with-history" HTML templates that will also add the correct <object> and <embed> tag parameters to support full-screen mode. Download and unzip the sample ZIP archive to get the new templates.

Copy the files in the "full-screen-support" or "full-screen-support-with-history" folders into the "html-template" directory of your Flex Builder project.

Publishing and testing

Publish and test your movie. Remember to do the following:

Verify that you have the latest version of the Flash plug-in or ActiveX control. You must have installed version 9,0,28,0 or greater to use full-screen mode.

Use one of the publish templates mentioned above, or make sure to edit your HTML to add the allowFullScreen<object>/<embed> parameter and set it to true.

Load your test movie in the browser. Right-click the movie or movie clip to bring up the custom context menu, which will contain items that allow you to enter or leave full-screen mode. Once you have entered full-screen mode using the context menu, you can exit it using the context menu or by hitting Escape on the keyboard, or by switching focus to some other window.