Setting Stage properties

Enabling full-screen mode in Flash Player

To enable full-screen mode for a SWF file embedded in an HTML page, the HTML code to embed Flash Player must include a param tag and embed attribute with the name allowFullScreen and value true , like this:

<object> 
    ... 
    <param name="allowFullScreen" value="true" /> 
    <embed ... allowFullScreen="true" /> 
</object>

In the Flash authoring tool, select File -> Publish Settings and in the Publish Settings dialog box, on the HTML tab, select the Flash Only - Allow Full Screen template.

In Flex, ensure that the HTML template includes <object> and <embed> tags that support full screen.

If you are using JavaScript in a web page to generate the SWF-embedding tags, you must alter the JavaScript to add the allowFullScreen param tag and attribute. For example, if your HTML page uses the AC_FL_RunContent() function (which is used in HTML pages generated by Flash Professional and Flash Builder), you should add the allowFullScreen parameter to that function call as follows:

AC_FL_RunContent( 
    ... 
    'allowFullScreen','true', 
    ... 
    ); //end AC code

This does not apply to SWF files running in the stand-alone Flash Player.

There are also security-related restrictions for using full-screen mode with Flash Player in a browser. These restrictions are described in Security .

Enabling full-screen interactive mode in Flash Player 11.3 and higher

Flash Player 11.3 and higher support full-screen interactive mode, which enables full support for all keyboard keys (except for Esc , which exits full-screen interactive mode). Full-screen interactive mode is useful for gaming (for example, to enable chat in a multi-player game or WASD keyboard controls in a first-person shooter game.)

To enable full-screen interactive mode for a SWF file embedded in an HTML page, the HTML code to embed Flash Player must include a param tag and embed attribute with the name allowFullScreenInteractive and value true , like this:

<object> 
    ... 
    <param name="allowFullScreenInteractive" value="true" /> 
    <embed ... allowFullScreenInteractive="true" /> 
</object>

In the Flash authoring tool, select File -> Publish Settings and in the Publish Settings dialog box, on the HTML tab, select the Flash Only - Allow Full Screen Interactive template.

In Flash Builder and Flex, ensure that the HTML templates include <object> and <embed> tags that support full screen interactive mode.

If you are using JavaScript in a web page to generate the SWF-embedding tags, you must alter the JavaScript to add the allowFullScreenInteractive param tag and attribute. For example, if your HTML page uses the AC_FL_RunContent() function (which is used in HTML pages generated by Flash Professional and Flash Builder), you should add the allowFullScreenInteractive parameter to that function call as follows:

AC_FL_RunContent( 
    ... 
    'allowFullScreenInteractive','true', 
    ... 
    ); //end AC code

This does not apply to SWF files running in the stand-alone Flash Player.

Full screen stage size and scaling

The Stage.fullScreenHeight and Stage.fullScreenWidth properties return the height and the width of the monitor that’s used when going to full-screen size, if that state is entered immediately. These values can be incorrect if the user has the opportunity to move the browser from one monitor to another after you retrieve these values but before entering full-screen mode. If you retrieve these values in the same event handler where you set the Stage.displayState property to StageDisplayState.FULL_SCREEN , the values are correct.For users with multiple monitors, the SWF content expands to fill only one monitor. Flash Player and AIR use a metric to determine which monitor contains the greatest portion of the SWF, and uses that monitor for full-screen mode. The fullScreenHeight and fullScreenWidth properties only reflect the size of the monitor that is used for full-screen mode. For more information, see Stage.fullScreenHeight and Stage.fullScreenWidth in the ActionScript 3.0 Reference for the Adobe Flash Platform .

Stage scaling behavior for full-screen mode is the same as under normal mode; the scaling is controlled by the Stage class’s scaleMode property. If the scaleMode property is set to StageScaleMode.NO_SCALE , the Stage’s stageWidth and stageHeight properties change to reflect the size of the screen area occupied by the SWF (the entire screen, in this case); if viewed in the browser the HTML parameter for this controls the setting.

You can use the Stage class’s fullScreen event to detect and respond when full-screen mode is turned on or off. For example, you might want to reposition, add, or remove items from the screen when entering or leaving full-screen mode, as in this example:

import flash.events.FullScreenEvent; 
 
function fullScreenRedraw(event:FullScreenEvent):void 
{ 
    if (event.fullScreen) 
    { 
        // Remove input text fields. 
        // Add a button that closes full-screen mode. 
    } 
    else 
    { 
        // Re-add input text fields. 
        // Remove the button that closes full-screen mode. 
    } 
} 
 
mySprite.stage.addEventListener(FullScreenEvent.FULL_SCREEN, fullScreenRedraw);

As this code shows, the event object for the fullScreen event is an instance of the flash.events.FullScreenEvent class, which includes a fullScreen property indicating whether full-screen mode is enabled ( true ) or not ( false ).

Keyboard support in full-screen mode

When Flash Player runs in a browser, all keyboard-related ActionScript, such as keyboard events and text entry in TextField instances, is disabled in full-screen mode. The exceptions (the keys that are enabled) are:

• Selected non-printing keys, specifically the arrow keys, space bar, and tab key

• Keyboard shortcuts that terminate full-screen mode: Esc (Windows and Mac), Control-W (Windows), Command-W (Mac), and Alt-F4

These restrictions are not present for SWF content running in the stand-alone Flash Player or in AIR. AIR supports an interactive full-screen mode that allows keyboard input.

Mouse support in full-screen mode

By default, mouse events in full-screen mode work the same way as when not in full-screen mode. However, in full-screen mode, you can optionally set the Stage.mouseLock property to enable mouse locking. Mouse locking disables the cursor and enables unbounded mouse movement.

Mouse locking is disabled automatically and the mouse cursor is made visible again when:

Events associated with mouse movement, such as the mouseMove event, use the MouseEvent class to represent the event object. When mouse locking is disabled, use the MouseEvent.localX and MouseEvent.localY properties to determine the location of the mouse.When mouse locking is enabled, use the MouseEvent.movementX and MouseEvent.movementY properties to determine the location of the mouse. The movementX and movementY properties contain changes in the position of the mouse since the last event, instead of absolute coordinates of the mouse location.

Hardware scaling in full-screen mode

You can use the Stage class’s fullScreenSourceRect property to set Flash Player or AIR to scale a specific region of the stage to full-screen mode. Flash Player and AIR scale in hardware, if available, using the graphics and video card on a user's computer, and generally display content more quickly than software scaling.

To take advantage of hardware scaling, you set the whole stage or part of the stage to full-screen mode. The following ActionScript 3.0 code sets the whole stage to full-screen mode:

import flash.geom.*;  
{ 
    stage.fullScreenSourceRect = new Rectangle(0,0,320,240); 
    stage.displayState = StageDisplayState.FULL_SCREEN; 
}

When this property is set to a valid rectangle and the displayState property is set to full-screen mode, Flash Player and AIR scale the specified area. The actual Stage size in pixels within ActionScript does not change. Flash Player and AIR enforce a minimum limit for the size of the rectangle to accommodate the standard “Press Esc to exit full-screen mode” message. This limit is usually around 260 by 30 pixels but can vary depending on platform and Flash Player version.

The fullScreenSourceRect property can only be set when Flash Player or AIR is not in full-screen mode. To use this property correctly, set this property first, then set the displayState property to full-screen mode.

To enable scaling, set the fullScreenSourceRect property to a rectangle object.

stage.fullScreenSourceRect = new Rectangle(0,0,320,240);

To disable scaling, set the fullScreenSourceRect property to null .

stage.fullScreenSourceRect = null;

To take advantage of all hardware acceleration features with Flash Player, enable it through the Flash Player Settings dialog box. To load the dialog box, right-click (Windows) or Control-click (Mac) inside Flash Player content in your browser. Select the Display tab, which is the first tab, and click the checkbox: Enable hardware acceleration.

Direct and GPU-compositing window modes

Flash Player 10 introduces two window modes, direct and GPU compositing, which you can enable through the publish settings in the Flash authoring tool. These modes are not supported in AIR. To take advantage of these modes, you must enable hardware acceleration for Flash Player.

Direct mode uses the fastest, most direct path to push graphics to the screen, which is advantageous for video playback.

GPU Compositing uses the graphics processing unit on the video card to accelerate compositing. Video compositing is the process of layering multiple images to create a single video image. When compositing is accelerated with the GPU it can improve the performance of YUV conversion, color correction, rotation or scaling, and blending. YUV conversion refers to the color conversion of composite analog signals, which are used for transmission, to the RGB (red, green, blue) color model that video cameras and displays use. Using the GPU to accelerate compositing reduces the memory and computational demands that are otherwise placed on the CPU. It also results in smoother playback for standard-definition video.

Be cautious in implementing these window modes. Using GPU compositing can be expensive for memory and CPU resources. If some operations (such as blend modes, filtering, clipping or masking) cannot be carried out in the GPU, they are done by the software. Adobe recommends limiting yourself to one SWF file per HTML page when using these modes and you should not enable these modes for banners. The Flash Test Movie facility does not use hardware acceleration but you can use it through the Publish Preview option.

Setting a frame rate in your SWF file that is higher than 60, the maximum screen refresh rate, is useless. Setting the frame rate from 50 through 55 allows for dropped frames, which can occur for various reasons from time to time.

Using direct mode requires Microsoft DirectX 9 with VRAM 128 MB on Windows and OpenGL for Apple Macintosh, Mac OS X v10.2 or higher. GPU compositing requires Microsoft DirectX 9 and Pixel Shader 2.0 support on Windows with 128 MB of VRAM. On Mac OS X and Linux, GPU compositing requires OpenGL 1.5 and several OpenGL extensions (framebuffer object, multitexture, shader objects, shading language, fragment shader).

You can activate direct and gpu acceleration modes on a per-SWF basis through the Flash Publish Settings dialog box, using the Hardware Acceleration menu on the Flash tab. If you choose None, the window mode reverts to default , transparent , or opaque , as specified by the Window Mode setting on the HTML tab.