Accessibility

Exploring full-screen mode in Flash Player 9

Tracy Stampfli

Adobe

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. Since the release of Macromedia Studio 8 and Macromedia Flash Player 8, the use of Flash video has 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 now take advantage of the full-screen mode in Adobe Flash Player 9.

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

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:

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

Requirements

To complete this tutorial you will need to install the following software and files:

Flash CS3 Professional

Note: For users of Flash CS3 Professional, an update including all debug and release versions of Flash Player 9 Update 3—and a new video playback component supporting H.264—is now available via Adobe Update Manager or directly from the Flash Support Center.

Flash Player 9

Sample HTML templates for Flex Builder:

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:

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:

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.

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:

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.

Where to go from here

Visit the Full-Screen Demos page in Adobe Labs for demos contributed by the community. If you have created a demo using the new full-screen feature, and would like to share it with the community, please add a link to your demo on the Full-Screen Demos page.

About the author

Tracy first joined Macromedia back in the day when the Internet was still just a series of tubes. She left the company in 2000, but returned to the mother ship a few years ago. Tracy has worked as a developer on Flash Player, Breeze (now Adobe Connect), Central, Director, Flash, and various other projects. Tracy is a practitioner of eight-step praying mantis kung fu and has a master's degree in mathematics, so don't mess with her.