Flash CS3 Documentation

Programming ActionScript 3.0 > Display programming > Working with display objects > Setting Stage properties

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

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 ActionScript 3.0 Language and Components Reference.

Controlling Stage scaling

When a Flash Player screen is resized, Flash Player automatically adjusts the Stage contents to compensate. The Stage class's scaleMode property determines how the Stage contents are adjusted. This property can be set to four different values, defined as constants in the flash.display.StageScaleMode class.

For three of the scaleMode values (StageScaleMode.EXACT_FIT, StageScaleMode.SHOW_ALL, and StageScaleMode.NO_BORDER), Flash Player will scale the contents of the Stage to fit within its boundaries.The three options differ in determining how the scaling is accomplished:

• StageScaleMode.EXACT_FIT scales the SWF proportionally.
• StageScaleMode.SHOW_ALL determines whether a border appears, like the black bars that appear when viewing a wide-screen movie on a standard television.
• StageScaleMode.NO_BORDER determines whether the content can be partially cropped or not.

<update: 7/11/2007> Alternatively, if scaleMode is set to StageScaleMode.NO_SCALE, the Stage contents maintain their defined size when the viewer resizes the Flash Player window. In this scale mode only, the stageWidth and stageHeight properties of the Stage class can be used to determine the actual pixel dimensions of the resized Flash Player window. (In the other scale modes, the stageWidth and stageHeight properties always reflect the original width and height of the SWF.) In addition, when scaleMode is set to StageScaleMode.NO_SCALE and the SWF file is resized, the Stage class's resize event is dispatched, allowing you to make adjustments accordingly.

Consequently, having scaleMode set to StageScaleMode.NO_SCALE allows you to have greater control over how the screen contents adjust to the window resizing if you desire. For example, in a SWF containing a video and a control bar, you might want to make the control bar stay the same size when the Stage is resized, and only change the size of the video window to accommodate the Stage size change. This is demonstrated in the following example:

// videoScreen is a display object (e.g. a Video instance) containing a
// video; it is positioned at the top-left corner of the Stage, and
// it should resize when the SWF resizes.

// controlBar is a display object (e.g. a Sprite) containing several
// buttons; it should stay positioned at the bottom-left corner of the
// Stage (below videoScreen) and it should not resize when the SWF
// resizes.

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 make a SWF fill a viewer's entire monitor, without any borders, menu bars, and so forth. 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:

// mySprite is a Sprite instance, already added to the display list
mySprite.stage.displayState = StageDisplayState.FULL_SCREEN;

To exit full-screen mode, set the displayState property to StageDisplayState.NORMAL:

mySprite.stage.displayState = StageDisplayState.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. As always, 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).

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:

• Full-screen mode can only be initiated through ActionScript in response to a mouse click (including right-click) or keypress.
• For users with multiple monitors, the SWF content will expand to fill only one monitor. Flash Player uses 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.

Flash CS3