Requirements     

               
User level
All
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.
 
Note: The keyboard shortcuts which terminate full-screen mode are Escape (Windows and Mac OS), Control+W (Windows), Command+W (Mac OS), and Alt+F4 (Windows).
 

 
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.
  • The user can disable full-screen mode for all Flash movies by adding a setting to the Flash Player configuration file mms.cfg. The file is described in the TechNote, IT Administration: Configuring Flash Player Auto-Update Notification. Add the line: FullScreenDisable=1 to the mms.cfg file to disable 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:
 
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 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:
 
 
ActionScript 2.0 example
 
 
//Rectangle is needed when using hardware scaling. import flash.geom.Rectangle; // functions to enter and leave full-screen mode function goFullScreen() { Stage["displayState"] = "fullScreen"; } // An alternate full screen function that uses hardware scaling to display the upper left corner of the stage in full screen. function goScaledFullScreen(){ var screenRectangle:Rectangle = new Rectangle(); screenRectangle.x = 0; screenRectangle.y = 0; screenRectangle.width=Stage.width/2; screenRectangle.height=Stage.height/2; Stage["fullScreenSourceRect"] = screenRectangle; Stage["displayState"] = "fullScreen"; } function exitFullScreen() { Stage["displayState"] = "normal"; } // function to enable, disable context menu items, based on which mode we are in. function menuHandler(obj, menuObj) { if (Stage["displayState"] == "normal") { // if we're in normal mode, enable the 'go full screen' item, disable the 'exit' item menuObj.customItems[0].enabled = true; menuObj.customItems[1].enabled = false; } else { // if we're in full screen mode, disable the 'go full screen' item, enable the 'exit' item menuObj.customItems[0].enabled = false; menuObj.customItems[1].enabled = true; } } // create a new context menu var fullscreenCM:ContextMenu = new ContextMenu(menuHandler); // hide the regular built-in items fullscreenCM.hideBuiltInItems(); // now, add the items to enter and leave full screen mode var fs:ContextMenuItem = new ContextMenuItem("Go Full Screen", goFullScreen); fullscreenCM.customItems.push( fs ); var xfs:ContextMenuItem = new ContextMenuItem("Exit Full Screen", exitFullScreen); fullscreenCM.customItems.push( xfs ); // now, attach the context menu to any movieclip in your movie. // here we attach it to _root, (even though using _root is generally a bad idea,) // so it will appear if you right click anywhere on the movie. _root.menu = fullscreenCM;
 
ActionScript 3.0 example
 
 
import flash.display.Stage; import flash.display.StageDisplayState; import flash.display.*; import flash.events.*; import flash.geom.Rectangle; // functions to enter and leave full screen mode function goFullScreen(event:ContextMenuEvent):void { stage.displayState = StageDisplayState.FULL_SCREEN; } // An alternate full-screen function that uses hardware scaling to display the upper left corner of the stage in full screen. function goScaledFullScreen(){ var screenRectangle:Rectangle = new Rectangle(0, 0, stage.stageWidth/2, stage.stageHeight/2); stage.fullScreenSourceRect = screenRectangle; stage.displayState = StageDisplayState.FULL_SCREEN; } function exitFullScreen(event:ContextMenuEvent):void { stage.displayState = StageDisplayState.NORMAL; } // function to enable and disable the context menu items, // based on what mode we are in. function menuHandler(event:ContextMenuEvent):void { if (stage.displayState == StageDisplayState.NORMAL) { event.target.customItems[0].enabled = true; event.target.customItems[1].enabled = false; } else { event.target.customItems[0].enabled = false; event.target.customItems[1].enabled = true; } } // create the context menu, remove the built-in items, // and add our custom items var fullscreenCM:ContextMenu = new ContextMenu(); fullscreenCM.addEventListener(ContextMenuEvent.MENU_SELECT, menuHandler); fullscreenCM.hideBuiltInItems(); var fs:ContextMenuItem = new ContextMenuItem("Go Full Screen" ); fs.addEventListener(ContextMenuEvent.MENU_ITEM_SELECT, goFullScreen); fullscreenCM.customItems.push( fs ); var xfs:ContextMenuItem = new ContextMenuItem("Exit Full Screen"); xfs.addEventListener(ContextMenuEvent.MENU_ITEM_SELECT, exitFullScreen); fullscreenCM.customItems.push( xfs ); // finally, attach the context menu to a movieclip mc.contextMenu = fullscreenCM;

 
HTML for full-screen mode

To use full-screen mode, you need to add a new parameter to the <object> and <embed> tags in your HTML. Here is an example of the <object> and <embed> tags with full screen enabled:
 
<object classid="clsid:d27cdb6e-ae6d-11cf-96b8-444553540000" codebase="http://fpdownload.macromedia.com/pub/shockwave/cabs/flash/swflash.cab#version=9,0,18,0" width="600" height="400" id="fullscreen" align="middle"> <param name="allowFullScreen" value="true" /> <param name="movie" value="fullscreen.swf" /> <param name="bgcolor" value="#333333" /> <embed src="fullscreen.swf" allowFullScreen="true" bgcolor="#333333" width="600" height="400" name="fullscreen" align="middle" type="application/x-shockwave-flash" pluginspage="http://www.macromedia.com/go/getflashplayer" /> </object>
 
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.
 
To use these templates in a Flex Builder project, follow these steps:
 
  1. In your existing Flex Builder project, delete all the files inside the "html-template" directory.
  2. 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.
 

More Like This