class flash.display.Stage extends DisplayObjectContainer

Available on all platforms

The Stage class represents the main drawing area. *

For SWF content running in the browser(in Flash® Player), * the Stage represents the entire area where Flash content is shown. For * content running in AIR on desktop operating systems, each NativeWindow * object has a corresponding Stage object.

*

The Stage object is not globally accessible. You need to access it * through the stage property of a DisplayObject instance.

*

The Stage class has several ancestor classes - DisplayObjectContainer, * InteractiveObject, DisplayObject, and EventDispatcher - from which it * inherits properties and methods. Many of these properties and methods are * either inapplicable to Stage objects, or require security checks when * called on a Stage object. The properties and methods that require security * checks are documented as part of the Stage class.

*

In addition, the following inherited properties are inapplicable to * Stage objects. If you try to set them, an IllegalOperationError is thrown. * These properties may always be read, but since they cannot be set, they * will always contain default values.

*
    *
  • accessibilityProperties
  • *
  • alpha
  • *
  • blendMode
  • *
  • cacheAsBitmap
  • *
  • contextMenu
  • *
  • filters
  • *
  • focusRect
  • *
  • loaderInfo
  • *
  • mask
  • *
  • mouseEnabled
  • *
  • name
  • *
  • opaqueBackground
  • *
  • rotation
  • *
  • scale9Grid
  • *
  • scaleX
  • *
  • scaleY
  • *
  • scrollRect
  • *
  • tabEnabled
  • *
  • tabIndex
  • *
  • transform
  • *
  • visible
  • *
  • x
  • *
  • y
  • *
*

Some events that you might expect to be a part of the Stage class, such * as enterFrame, exitFrame, * frameConstructed, and render, cannot be Stage * events because a reference to the Stage object cannot be guaranteed to * exist in every situation where these events are used. Because these events * cannot be dispatched by the Stage object, they are instead dispatched by * every DisplayObject instance, which means that you can add an event * listener to any DisplayObject instance to listen for these events. These * events, which are part of the DisplayObject class, are called broadcast * events to differentiate them from events that target a specific * DisplayObject instance. Two other broadcast events, activate * and deactivate, belong to DisplayObject's superclass, * EventDispatcher. The activate and deactivate * events behave similarly to the DisplayObject broadcast events, except that * these two events are dispatched not only by all DisplayObject instances, * but also by all EventDispatcher instances and instances of other * EventDispatcher subclasses. For more information on broadcast events, see * the DisplayObject class.

* * @event fullScreen Dispatched when the Stage object enters, or * leaves, full-screen mode. A change in * full-screen mode can be initiated through * ActionScript, or the user invoking a keyboard * shortcut, or if the current focus leaves the * full-screen window. * @event mouseLeave Dispatched by the Stage object when the * pointer moves out of the stage area. If the * mouse button is pressed, the event is not * dispatched. * @event orientationChange Dispatched by the Stage object when the stage * orientation changes. *

Orientation changes can occur when the * user rotates the device, opens a slide-out * keyboard, or when the * setAspectRatio() is called.

*

Note: If the * autoOrients property is * false, then the stage * orientation does not change when a device is * rotated. Thus, StageOrientationEvents are * only dispatched for device rotation when * autoOrients is * true.

* @event orientationChanging Dispatched by the Stage object when the stage * orientation begins changing. *

Important: orientationChanging * events are not dispatched on Android * devices.

*

Note: If the * autoOrients property is * false, then the stage * orientation does not change when a device is * rotated. Thus, StageOrientationEvents are * only dispatched for device rotation when * autoOrients is * true.

* @event resize Dispatched when the scaleMode * property of the Stage object is set to * StageScaleMode.NO_SCALE and the * SWF file is resized. * @event stageVideoAvailability Dispatched by the Stage object when the state * of the stageVideos property changes.

Instance Fields

var align:StageAlign

A value from the StageAlign class that specifies the alignment of the * stage in Flash Player or the browser. The following are valid values: * *

The align property is only available to an object that is * in the same security sandbox as the Stage owner(the main SWF file). To * avoid this, the Stage owner can grant permission to the domain of the * calling object by calling the Security.allowDomain() method * or the Security.alowInsecureDomain() method. For more * information, see the "Security" chapter in the ActionScript 3.0 * Developer's Guide.

var allowsFullScreen:Bool

Specifies whether this stage allows the use of the full screen mode

var colorCorrection:ColorCorrection

Controls Flash runtime color correction for displays. Color correction * works only if the main monitor is assigned a valid ICC color profile, * which specifies the device's particular color attributes. By default, the * Flash runtime tries to match the color correction of its host(usually a * browser). *

Use the Stage.colorCorrectionSupport property to determine * if color correction is available on the current system and the default * state. . If color correction is available, all colors on the stage are * assumed to be in the sRGB color space, which is the most standard color * space. Source profiles of input devices are not considered during color * correction. No input color correction is applied; only the stage output is * mapped to the main monitor's ICC color profile.

*

In general, the benefits of activating color management include * predictable and consistent color, better conversion, accurate proofing and * more efficient cross-media output. Be aware, though, that color management * does not provide perfect conversions due to devices having a different * gamut from each other or original images. Nor does color management * eliminate the need for custom or edited profiles. Color profiles are * dependent on browsers, operating systems(OS), OS extensions, output * devices, and application support.

*

Applying color correction degrades the Flash runtime performance. A * Flash runtime's color correction is document style color correction * because all SWF movies are considered documents with implicit sRGB * profiles. Use the Stage.colorCorrectionSupport property to * tell the Flash runtime to correct colors when displaying the SWF file * (document) to the display color space. Flash runtimes only compensates for * differences between monitors, not for differences between input devices * (camera/scanner/etc.).

*

The three possible values are strings with corresponding constants in * the flash.display.ColorCorrection class:

* *
    *
  • "default": Use the same color correction as the host * system.
  • *
  • "on": Always perform color correction.
  • *
  • "off": Never perform color correction.
  • *

var colorCorrectionSupport:ColorCorrectionSupport

Specifies whether the Flash runtime is running on an operating system that * supports color correction and whether the color profile of the main * (primary) monitor can be read and understood by the Flash runtime. This * property also returns the default state of color correction on the host * system(usually the browser). Currently the return values can be: *

The three possible values are strings with corresponding constants in * the flash.display.ColorCorrectionSupport class:

*
    *
  • "unsupported": Color correction is not available.
  • *
  • "defaultOn": Always performs color correction.
  • *
  • "defaultOff": Never performs color correction.
  • *

var displayState:StageDisplayState

A value from the StageDisplayState class that specifies which display * state to use. The following are valid values: *

    *
  • StageDisplayState.FULLSCREEN Sets AIR application or * Flash runtime to expand the stage over the user's entire screen, with * keyboard input disabled.
  • *
  • StageDisplayState.FULLSCREENINTERACTIVE Sets the AIR * application to expand the stage over the user's entire screen, with * keyboard input allowed.(Not available for content running in Flash * Player.)
  • *
  • StageDisplayState.NORMAL Sets the Flash runtime back to * the standard stage display mode.
  • *
*

The scaling behavior of the movie in full-screen mode is determined by * the scaleMode setting(set using the * Stage.scaleMode property or the SWF file's embed * tag settings in the HTML file). If the scaleMode property is * set to noScale while the application transitions to * full-screen mode, the Stage width and height * properties are updated, and the Stage dispatches a resize * event. If any other scale mode is set, the stage and its contents are * scaled to fill the new screen dimensions. The Stage object retains its * original width and height values and does not * dispatch a resize event.

*

The following restrictions apply to SWF files that play within an HTML * page(not those using the stand-alone Flash Player or not running in the * AIR runtime):

*
    *
  • To enable full-screen mode, add the allowFullScreen * parameter to the object and embed tags in the * HTML page that includes the SWF file, with allowFullScreen * set to "true", as shown in the following example:
  • *
  • Full-screen mode is initiated in response to a mouse click or key * press by the user; the movie cannot change Stage.displayState * without user input. Flash runtimes restrict keyboard input in full-screen * mode. Acceptable keys include keyboard shortcuts that terminate * full-screen mode and non-printing keys such as arrows, space, Shift, and * Tab keys. Keyboard shortcuts that terminate full-screen mode are: Escape * (Windows, Linux, and Mac), Control+W(Windows), Command+W(Mac), and * Alt+F4. *

    A Flash runtime dialog box appears over the movie when users enter * full-screen mode to inform the users they are in full-screen mode and that * they can press the Escape key to end full-screen mode.

    *
  • *
  • Starting with Flash Player 9.0.115.0, full-screen works the same in * windowless mode as it does in window mode. If you set the Window Mode * (wmode in the HTML) to Opaque Windowless * (opaque) or Transparent Windowless * (transparent), full-screen can be initiated, but the * full-screen window will always be opaque.
  • *
*

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 which allows keyboard input.

*

For AIR content running in full-screen mode, the system screen saver * and power saving options are disabled while video content is playing and * until either the video stops or full-screen mode is exited.

* *

On Linux, setting displayState to * StageDisplayState.FULLSCREEN or * StageDisplayState.FULLSCREENINTERACTIVE is an asynchronous * operation.

* *

var focus:InteractiveObject

The interactive object with keyboard focus; or null if focus * is not set or if the focused object belongs to a security sandbox to which * the calling object does not have access. * *

var frameRate:Float

Gets and sets the frame rate of the stage. The frame rate is defined as * frames per second. By default the rate is set to the frame rate of the * first SWF file loaded. Valid range for the frame rate is from 0.01 to 1000 * frames per second. *

Note: An application might not be able to follow high frame rate * settings, either because the target platform is not fast enough or the * player is synchronized to the vertical blank timing of the display device * (usually 60 Hz on LCD devices). In some cases, a target platform might * also choose to lower the maximum frame rate if it anticipates high CPU * usage.

*

For content running in Adobe AIR, setting the frameRate * property of one Stage object changes the frame rate for all Stage objects * (used by different NativeWindow objects).

* *

var fullScreenHeight:UInt

Returns the height of the monitor that will be used when going to full * screen size, if that state is entered immediately. If the user has * multiple monitors, the monitor that's used is the monitor that most of the * stage is on at the time. *

Note: If the user has the opportunity to move the browser from * one monitor to another between retrieving the value and going to full * screen size, the value could be incorrect. If you retrieve the value in an * event handler that sets Stage.displayState to * StageDisplayState.FULL_SCREEN, the value will be correct.

*

This is the pixel height of the monitor and is the same as the stage * height would be if Stage.align is set to * StageAlign.TOPLEFT and Stage.scaleMode is set * to StageScaleMode.NOSCALE.

var fullScreenSourceRect:Rectangle

Sets the Flash runtime to scale a specific region of the stage to * full-screen mode. If available, the Flash runtime scales in hardware, * which uses the graphics and video card on a user's computer, and generally * displays content more quickly than software scaling. *

When this property is set to a valid rectangle and the * displayState property is set to full-screen mode, the Flash * runtime scales the specified area. The actual Stage size in pixels within * ActionScript does not change. The Flash runtime enforces 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 on platform and Flash runtime version.

*

This property can only be set when the Flash runtime 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:

*

The end user also can select within Flash Player Display Settings to * turn off hardware scaling, which is enabled by default. For more * information, see <a href="http://www.adobe.com/go/displaysettings" * scope="external">www.adobe.com/go/displaysettings.

var fullScreenWidth:UInt

Returns the width of the monitor that will be used when going to full * screen size, if that state is entered immediately. If the user has * multiple monitors, the monitor that's used is the monitor that most of the * stage is on at the time. *

Note: If the user has the opportunity to move the browser from * one monitor to another between retrieving the value and going to full * screen size, the value could be incorrect. If you retrieve the value in an * event handler that sets Stage.displayState to * StageDisplayState.FULL_SCREEN, the value will be correct.

*

This is the pixel width of the monitor and is the same as the stage * width would be if Stage.align is set to * StageAlign.TOPLEFT and Stage.scaleMode is set * to StageScaleMode.NOSCALE.

var quality:StageQuality

A value from the StageQuality class that specifies which rendering quality * is used. The following are valid values: *

    *
  • StageQuality.LOW - Low rendering quality. Graphics are * not anti-aliased, and bitmaps are not smoothed, but runtimes still use * mip-mapping.
  • *
  • StageQuality.MEDIUM - Medium rendering quality. * Graphics are anti-aliased using a 2 x 2 pixel grid, bitmap smoothing is * dependent on the Bitmap.smoothing setting. Runtimes use * mip-mapping. This setting is suitable for movies that do not contain * text.
  • *
  • StageQuality.HIGH - High rendering quality. Graphics * are anti-aliased using a 4 x 4 pixel grid, and bitmap smoothing is * dependent on the Bitmap.smoothing setting. Runtimes use * mip-mapping. This is the default rendering quality setting that Flash * Player uses.
  • *
  • StageQuality.BEST - Very high rendering quality. * Graphics are anti-aliased using a 4 x 4 pixel grid. If * Bitmap.smoothing is true the runtime uses a high * quality downscale algorithm that produces fewer artifacts(however, using * StageQuality.BEST with Bitmap.smoothing set to * true slows performance significantly and is not a recommended * setting).
  • *
*

Higher quality settings produce better rendering of scaled bitmaps. * However, higher quality settings are computationally more expensive. In * particular, when rendering scaled video, using higher quality settings can * reduce the frame rate.

*

In the desktop profile of Adobe AIR, quality can be set to * StageQuality.BEST or StageQuality.HIGH(and the * default value is StageQuality.HIGH). Attempting to set it to * another value has no effect(and the property remains unchanged). In the * moble profile of AIR, all four quality settings are available. The default * value on mobile devices is StageQuality.MEDIUM.

* *

For content running in Adobe AIR, setting the quality * property of one Stage object changes the rendering quality for all Stage * objects(used by different NativeWindow objects).

* Note: The operating system draws the device fonts, which are * therefore unaffected by the quality property. * *

var scaleMode:StageScaleMode

A value from the StageScaleMode class that specifies which scale mode to * use. The following are valid values: *

    *
  • StageScaleMode.EXACTFIT - The entire application is * visible in the specified area without trying to preserve the original * aspect ratio. Distortion can occur, and the application may appear * stretched or compressed.
  • *
  • StageScaleMode.SHOWALL - The entire application is * visible in the specified area without distortion while maintaining the * original aspect ratio of the application. Borders can appear on two sides * of the application.
  • *
  • StageScaleMode.NOBORDER - The entire application fills * the specified area, without distortion but possibly with some cropping, * while maintaining the original aspect ratio of the application.
  • *
  • StageScaleMode.NOSCALE - The entire application is * fixed, so that it remains unchanged even as the size of the player window * changes. Cropping might occur if the player window is smaller than the * content.
  • *
* *

var showDefaultContextMenu:Bool

Specifies whether to show or hide the default items in the Flash runtime * context menu. * *

If the showDefaultContextMenu property is set to * true(the default), all context menu items appear. If the * showDefaultContextMenu property is set to false, * only the Settings and About... menu items appear.

* *

var softKeyboardRect:Rectangle

The area of the stage that is currently covered by the software keyboard. *

The area has a size of zero(0,0,0,0) when the soft keyboard is not * visible.

*

When the keyboard opens, the softKeyboardRect is set at * the time the softKeyboardActivate event is dispatched. If the keyboard * changes size while open, the runtime updates the * softKeyboardRect property and dispatches an additional * softKeyboardActivate event.

* *

Note: On Android, the area covered by the keyboard is estimated * when the operating system does not provide the information necessary to * determine the exact area. This problem occurs in fullscreen mode and also * when the keyboard opens in response to an InteractiveObject receiving * focus or invoking the requestSoftKeyboard() method.

var stageFocusRect:Bool

Specifies whether or not objects display a glowing border when they have * focus. * *

var stageHeight:Int

The current height, in pixels, of the Stage. *

If the value of the Stage.scaleMode property is set to * StageScaleMode.NO_SCALE when the user resizes the window, the * Stage content maintains its size while the stageHeight * property changes to reflect the new height size of the screen area * occupied by the SWF file.(In the other scale modes, the * stageHeight property always reflects the original height of * the SWF file.) You can add an event listener for the resize * event and then use the stageHeight property of the Stage * class to determine the actual pixel dimension of the resized Flash runtime * window. The event listener allows you to control how the screen content * adjusts when the user resizes the window.

*

Air for TV devices have slightly different behavior than desktop * devices when you set the stageHeight property. If the * Stage.scaleMode property is set to * StageScaleMode.NOSCALE and you set the * stageHeight property, the stage height does not change until * the next frame of the SWF.

* *

Note: In an HTML page hosting the SWF file, both the * object and embed tags' height * attributes must be set to a percentage(such as 100%), not * pixels. If the settings are generated by JavaScript code, the * height parameter of the ACFL_RunContent() * method must be set to a percentage, too. This percentage is applied to the * stageHeight value.

* *

var stageVideos:Vector<StageVideo>

A list of StageVideo objects available for playing external videos. *

You can use only a limited number of StageVideo objects at a time. When * a SWF begins to run, the number of available StageVideo objects depends on * the platform and on available hardware.

*

To use a StageVideo object, assign a member of the * stageVideos Vector object to a StageVideo variable.

*

All StageVideo objects are displayed on the stage behind any display * objects. The StageVideo objects are displayed on the stage in the order * they appear in the stageVideos Vector object. For example, if * the stageVideos Vector object contains three entries:

*
    *
  1. The StageVideo object in the 0 index of the stageVideos * Vector object is displayed behind all StageVideo objects.
  2. *
  3. The StageVideo object at index 1 is displayed in front of the * StageVideo object at index 0.
  4. *
  5. The StageVideo object at index 2 is displayed in front of the * StageVideo object at index 1.
  6. *
*

Use the StageVideo.depth property to change this * ordering.

*

Note: AIR for TV devices support only one StageVideo object.

var stageWidth:Int

Specifies the current width, in pixels, of the Stage. *

If the value of the Stage.scaleMode property is set to * StageScaleMode.NO_SCALE when the user resizes the window, the * Stage content maintains its defined size while the stageWidth * property changes to reflect the new width size of the screen area occupied * by the SWF file.(In the other scale modes, the stageWidth * property always reflects the original width of the SWF file.) You can add * an event listener for the resize event and then use the * stageWidth property of the Stage class to determine the * actual pixel dimension of the resized Flash runtime window. The event * listener allows you to control how the screen content adjusts when the * user resizes the window.

*

Air for TV devices have slightly different behavior than desktop * devices when you set the stageWidth property. If the * Stage.scaleMode property is set to * StageScaleMode.NOSCALE and you set the * stageWidth property, the stage width does not change until * the next frame of the SWF.

* *

Note: In an HTML page hosting the SWF file, both the * object and embed tags' width * attributes must be set to a percentage(such as 100%), not * pixels. If the settings are generated by JavaScript code, the * width parameter of the ACFL_RunContent() * method must be set to a percentage, too. This percentage is applied to the * stageWidth value.

* *

var wmodeGPU:Bool

Indicates whether GPU compositing is available and in use. The * wmodeGPU value is true only when all * three of the following conditions exist: *

*

    *
  • GPU compositing has been requested.
  • *
  • GPU compositing is available.
  • *
  • GPU compositing is in use.
  • *
*

*

Specifically, the wmodeGPU property indicates one of the * following:

*

*

    *
  1. GPU compositing has not been requested or is unavailable. In this * case, the wmodeGPU property value is false.
  2. *
  3. GPU compositing has been requested(if applicable and available), * but the environment is operating in "fallback mode"(not optimal * rendering) due to limitations of the content. In this case, the * wmodeGPU property value is true.
  4. *
  5. GPU compositing has been requested(if applicable and available), * and the environment is operating in the best mode. In this case, the * wmodeGPU property value is also true.
  6. *
*

*

In other words, the wmodeGPU property identifies the * capability and state of the rendering environment. For runtimes that do * not support GPU compositing, such as AIR 1.5.2, the value is always * false, because(as stated above) the value is * true only when GPU compositing has been requested, is * available, and is in use.

*

The wmodeGPU property is useful to determine, at runtime, * whether or not GPU compositing is in use. The value of * wmodeGPU indicates if your content is going to be scaled by * hardware, or not, so you can present graphics at the correct size. You can * also determine if you're rendering in a fast path or not, so that you can * adjust your content complexity accordingly.

*

For Flash Player in a browser, GPU compositing can be requested by the * value of gpu for the wmode HTML parameter in the * page hosting the SWF file. For other configurations, GPU compositing can * be requested in the header of a SWF file(set using SWF authoring * tools).

*

However, the wmodeGPU property does not identify the * current rendering performance. Even if GPU compositing is "in use" the * rendering process might not be operating in the best mode. To adjust your * content for optimal rendering, use a Flash runtime debugger version, and * set the DisplayGPUBlendsetting in your mm.cfg file.

*

Note: This property is always false when referenced * from ActionScript that runs before the runtime performs its first * rendering pass. For example, if you examine wmodeGPU from a * script in Frame 1 of Adobe Flash Professional, and your SWF file is the * first SWF file loaded in a new instance of the runtime, then the * wmodeGPU value is false. To get an accurate * value, wait until at least one rendering pass has occurred. If you write * an event listener for the exitFrame event of any * DisplayObject, the wmodeGPU value at is the * correct value.

function invalidate():Void

Calling the invalidate() method signals Flash runtimes to * alert display objects on the next opportunity it has to render the display * list(for example, when the playhead advances to a new frame). After you * call the invalidate() method, when the display list is next * rendered, the Flash runtime sends a render event to each * display object that has registered to listen for the render * event. You must call the invalidate() method each time you * want the Flash runtime to send render events. *

The render event gives you an opportunity to make changes * to the display list immediately before it is actually rendered. This lets * you defer updates to the display list until the latest opportunity. This * can increase performance by eliminating unnecessary screen updates.

*

The render event is dispatched only to display objects * that are in the same security domain as the code that calls the * stage.invalidate() method, or to display objects from a * security domain that has been granted permission via the * Security.allowDomain() method.

function isFocusInaccessible():Bool

Determines whether the Stage.focus property returns * null for security reasons. In other words, * isFocusInaccessible returns true if the object * that has focus belongs to a security sandbox to which the SWF file does * not have access. * *

returnstrue if the object that has focus belongs to a * security sandbox to which the SWF file does not have access.