Setting Stage properties

The Stage class overrides most properties and methods of the DisplayObject class. If you call one of these overridden properties or methods, Flash Player and AIR throw an exception. For example, the Stage object does not have x or y properties, since its position is fixed as the main container for the application. The x and y properties refer to the position of a display object relative to its container, and since the Stage is not contained in another display object container, these properties do not apply.

Note: Some properties and methods of the Stage class are only available to display objects that are in the same security sandbox as the first SWF file loaded. For details, see Stage security.

Subtopics

Controlling the playback frame rate

The framerate property of the Stage class is used to set the frame rate for all SWF files loaded into the application. For more information, see the Flex ActionScript Language Reference.

import flash.display.Stage;
import flash.display.StageAlign;
import flash.display.StageScaleMode;
import flash.events.Event;

var swfStage:Stage = videoScreen.stage;
swfStage.scaleMode = StageScaleMode.NO_SCALE;
swfStage.align = StageAlign.TOP_LEFT;

function resizeDisplay(event:Event):void
{
    var swfWidth:int = swfStage.stageWidth;
    var swfHeight:int = swfStage.stageHeight;

    // Resize the video window.
    var newVideoHeight:Number = swfHeight - controlBar.height;
    videoScreen.height = newVideoHeight;
    videoScreen.scaleX = videoScreen.scaleY;
    
    // Reposition the control bar.
    controlBar.y = newVideoHeight;
}

swfStage.addEventListener(Event.RESIZE, resizeDisplay);

Working with full-screen mode

Full-screen mode allows you to set a movie's stage to fill a viewer's entire monitor without any container borders or menus. The Stage class's displayState property is used to toggle full-screen mode on and off for a SWF. The displayState property can be set to one of the values defined by the constants in the flash.display.StageDisplayState class. To turn on full-screen mode, set displayState to StageDisplayState.FULL_SCREEN:

// Send the stage to full-screen in AS3
stage.displayState = StageDisplayState.FULL_SCREEN;

// Exit full-screen mode in AS3
stage.displayState = StageDisplayState.NORMAL;

// Send the stage to full-screen in AS2
Stage.displayState = "fullScreen";

// Exit full-screen mode in AS2
Stage.displayState = "normal";

In addition, a user can choose to leave full-screen mode by switching focus to a different window or by using one of several key combinations: the Esc key (all platforms), Ctrl-W (Windows), Command-W (Mac), or Alt-F4 (Windows).

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

When working with full-screen mode in ActionScript, you'll want to keep the following considerations in mind:

In Flash Player, full-screen mode can only be initiated through ActionScript in response to a mouse click (including right-click) or keypress. AIR content running in the application security sandbox does not require that full-screen mode be entered in response to a user gesture.
For users with multiple monitors, the SWF content will expand 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.
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>
```
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 by both Flex Builder and Flash-generated HTML pages), 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.
All keyboard-related ActionScript, such as keyboard events and text entry in TextField instances, is disabled in full-screen mode. The exception is the keyboard shortcuts that close full-screen mode.

There are a few additional security-related restrictions you'll want to understand, too. These are described in Security sandboxes.

Hardware scaling

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 AS3 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, as shown in the code examples.

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

stage.fullScreenSourceRect = new Rectangle(0,0,320,240); // Valid, will enable hardware scaling.

To disable scaling, set the fullScreenSourceRect property to null in AS3, and undefined in AS2.

stage.fullScreenSourceRect = null;

Adobe Flex 3 Help

Setting Stage properties