3 December 2007
All
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.
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).
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:
<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.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.
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.
Stage.displayState:String property
This property is gettable and settable. Possible values are:
fullScreennormalThis 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.
flash.display.Stage.displayState:String property
This property is gettable and settable. The valid values are from the class StageDisplayState:
StageDisplayState.FULL_SCREENStage.DisplayState.NORMALThis 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.
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";
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.
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:
//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;
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;
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>
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.
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:
Publish and test your movie. Remember to do the following:
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.
