Stage  - AS3

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.

Related API Elements

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

Specifies whether this stage allows the use of the full screen with text input mode

Specifies whether the stage automatically changes orientation when the device orientation changes.

The initial value of this property is derived from the autoOrients element of the application descriptor and defaults to false. When changing the property to false, the behavior is not guaranteed. On some devices, the stage remains in the current orientation. On others, the stage orientation changes to a device-defined "standard" orientation, after which, no further stage orientation changes occur.

AIR profile support: This feature is supported on mobile devices, but it is not supported on desktop operating systems or AIR for TV devices. You can test for support at run time using the Stage.supportsOrientantionChange property. See AIR Profile Support for more information regarding API support across multiple profiles.

Learn more

Related API Elements

Specifies the browser zoom factor. A change in browser zoom factor affects the scaling factor of the stage.

The SWF background color.

Defaults to the stage background color, as set by the SWF tag SetBackgroundColor.

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.

Related API Elements

function addHandler(add_event:Event) {
    switch(stage.colorCorrection) {
        case ColorCorrection.ON:
            stage.colorCorrection = ColorCorrection.OFF;
            lblCMEnableState.text = "State: " + stage.colorCorrection;
            break;
        case ColorCorrection.OFF:
            stage.colorCorrection = ColorCorrection.DEFAULT;
            lblCMEnableState.text = "State: " + stage.colorCorrection;
            break;
        case ColorCorrection.DEFAULT:
            stage.colorCorrection = ColorCorrection.ON;
            lblCMEnableState.text = "State: " + stage.colorCorrection;
            break;
        default:
            lblCMEnableState.text = "Error.";
            break;
}

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.

Related API Elements

function addHandler(add_event:Event) {
    if (stage.colorCorrectionSupport == ColorCorrectionSupport.DEFAULT_ON || stage.colorCorrectionSupport == ColorCorrectionSupport.DEFAULT_OFF) {
           lblHasCM.text = "stage.colorCorrectionSupport: " + stage.colorCorrectionSupport;
    } 
    else {
        lblHasCM.text = "stage.colorCorrectionSupport: unsupported";
    }
}

Specifies the effective pixel scaling factor of the stage. This value is usually 1 on standard screens and 2 on HiDPI (a.k.a Retina) screens. When the stage is rendered on HiDPI screens the pixel resolution is doubled; even if the stage scaling mode is set to StageScaleMode.NO_SCALE. Stage.stageWidth and Stage.stageHeight continue to be reported in classic pixel units. Note: this value can change dynamically depending if the stage is on a HiDPI or standard screen.

The physical orientation of the device.

On devices with slide-out keyboards, the state of the keyboard has a higher priority in determining the device orientation than the rotation detected by the accelerometer. Thus on a portrait-aspect device with a side-mounted keyboard, the deviceOrientation property will report ROTATED_LEFT when the keyboard is open no matter how the user is holding the device.

Use the constants defined in the StageOrientation class when setting or comparing values for this property.

AIR profile support: This feature is supported on mobile devices, but it is not supported on desktop operating systems or AIR for TV devices. You can test for support at run time using the Stage.supportsOrientationChange property. See AIR Profile Support for more information regarding API support across multiple profiles.

Learn more

Related API Elements

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

• StageDisplayState.FULL_SCREEN Sets AIR application or content in Flash Player to expand the stage over the user's entire screen. Keyboard input is disabled, with the exception of a limited set of non-printing keys.
• StageDisplayState.FULL_SCREEN_INTERACTIVE Sets the application to expand the stage over the user's entire screen, with keyboard input allowed. (Available in AIR and Flash Player, beginning with Flash Player 11.3.)
• StageDisplayState.NORMAL Sets the stage 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 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:

  <param name="allowFullScreen" value="true" />
            ...
      <embed src="example.swf" allowFullScreen="true" ... >

  An HTML page may also use a script to generate SWF-embedding tags. You need to alter the script so that it inserts the proper allowFullScreen settings. HTML pages generated by Flash Professional and Flash Builder use the AC_FL_RunContent() function to embed references to SWF files, and you need to add the allowFullScreen parameter settings, as in the following:

  AC_FL_RunContent( ... "allowFullScreen", "true", ... )

• 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. (Use full-screen interactive mode to support input from additional keys.) Keyboard shortcuts that terminate full-screen mode are: Escape (Windows, Linux, and Mac), Control+W (Windows), Command+W (Mac), and Alt+F4.
• 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.
• To enable full-screen interactive mode, which supports keyboard interactivity, add the allowFullScreenInteractive parameter to the object and embed tags in the HTML page that includes the SWF file, with allowFullScreenInteractive set to "true", as shown in the following example:

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

These restrictions are not present for SWF content running in the stand-alone Flash Player or in AIR.

When entering full-screen mode, the Flash runtime briefly displays a notification over the SWF content to inform the users they are in full-screen mode and that they can press the Escape key to end full-screen mode.

When entering full-screen interactive mode, Flash Player displays a confirmation prompt over the SWF content, enabling users to allow access to extended keyboard input (including printing keys) and informing users that they can press the Escape key to end full-screen interactive mode. You should not make assumptions about the appearance/location of the confirmation prompt. You can determine if users have allowed access to extended keyboard input by listening for the FullScreenEvent.FULL_SCREEN_INTERACTIVE_ACCEPTED event.

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.FULL_SCREEN or StageDisplayState.FULL_SCREEN_INTERACTIVE is an asynchronous operation.

More examples

Related API Elements

package {
    import flash.display.Sprite;
    import flash.display.Stage;
    import flash.events.*;
    import flash.net.NetConnection;
    import flash.net.NetStream;
    import flash.media.Video;
    
    public class FullScreenExample extends Sprite
    {
        private var videoURL:String = "testVideo.flv";
        private var connection:NetConnection;
        private var stream:NetStream;
        private var video:Video;        
        
        public function FullScreenExample() {
            connection = new NetConnection();
            connection.addEventListener(NetStatusEvent.NET_STATUS, netStatusHandler);
            connection.addEventListener(SecurityErrorEvent.SECURITY_ERROR, securityErrorHandler);
            connection.connect(null);
            
            loaderInfo.addEventListener(Event.INIT, createMouseListener);            
        }

        private function createMouseListener(event:Event):void {
            stage.addEventListener(MouseEvent.CLICK,toggleFullScreen);
        }        
        
        private function toggleFullScreen(event:MouseEvent):void {
            switch(stage.displayState) {
                case "normal":
                    stage.displayState = "fullScreen";    
                    break;
                case "fullScreen":
                default:
                    stage.displayState = "normal";    
                    break;
            }
        }    
        
        // Video related:
        private function netStatusHandler(event:NetStatusEvent):void {
            switch (event.info.code) {
                case "NetConnection.Connect.Success":
                    connectStream();
                    break;
                case "NetStream.Play.StreamNotFound":
                    trace("Unable to locate video: " + videoURL);
                    break;
            }
        }
        private function connectStream():void {
            var stream:NetStream = new NetStream(connection);
            stream.addEventListener(NetStatusEvent.NET_STATUS, netStatusHandler);
            stream.addEventListener(AsyncErrorEvent.ASYNC_ERROR, asyncErrorHandler);

            video = new Video(stage.stageWidth,stage.stageHeight);
            video.attachNetStream(stream);
            stream.play(videoURL);
            addChild(video);
        }
        private function securityErrorHandler(event:SecurityErrorEvent):void {
            trace("securityErrorHandler: " + event);
        }
        private function asyncErrorHandler(event:AsyncErrorEvent):void {
            // ignore AsyncErrorEvent events.
        }            
    }
}

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 myTF:TextField = new TextField();
myTF.border =true;
myTF.type = TextFieldType.INPUT;

addChild(myTF);
stage.focus= myTF;

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

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.TOP_LEFT and Stage.scaleMode is set to StageScaleMode.NO_SCALE.

Related API Elements

import flash.display.Sprite;
import flash.display.Stage;
import flash.display.StageDisplayState;
import flash.events.MouseEvent;
import flash.geom.Rectangle;
 
// cover the stage with a green rectangle
var greenRect:Sprite = new Sprite();
greenRect.graphics.beginFill(0x00FF00);
greenRect.graphics.drawRect(0, 0, stage.stageWidth, stage.stageHeight);
addChild(greenRect);
 
// create red square on stage, turn it into a button for going to full screen
var redSquare:Sprite = new Sprite();
redSquare.graphics.beginFill(0xFF0000);
redSquare.graphics.drawRect(0, 0, 300, 300);
redSquare.x = 50;
redSquare.y = 50;
redSquare.addEventListener(MouseEvent.CLICK, enterFullScreen);
redSquare.buttonMode = true;
addChild(redSquare);
 
function enterFullScreen(e:MouseEvent):void
{
    // we will go to full screen zoomed in on the red square
    var redSquare:Sprite = e.target as Sprite;
    var fullScreenRect:Rectangle = new Rectangle(redSquare.x, redSquare.y, redSquare.width, redSquare.height);
 
    // calculate aspect ratio of the red square
    var rectAspectRatio:Number = fullScreenRect.width / fullScreenRect.height;
 
    // calculate aspect ratio of the screen
    var screenAspectRatio:Number = stage.fullScreenWidth / stage.fullScreenHeight;
  
    // change the fullScreenRect so that it covers the entire screen, keeping it centered on the redSquare
    // try commenting out this section to see what happens if you do not fix the aspect ratio.
    if (rectAspectRatio > screenAspectRatio) {
         var newHeight:Number = fullScreenRect.width / screenAspectRatio;
         fullScreenRect.y -= ((newHeight - fullScreenRect.height) / 2);
        fullScreenRect.height = newHeight;
    } else if (rectAspectRatio < screenAspectRatio) {
        var newWidth:Number = fullScreenRect.height * screenAspectRatio;
        fullScreenRect.x -= ((newWidth - fullScreenRect.width) / 2);
        fullScreenRect.width = newWidth;
    }
 
    // go to full screen
    stage.fullScreenSourceRect = fullScreenRect;
    stage.displayState = StageDisplayState.FULL_SCREEN;
}

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. Note: In Flash Player 15 and later, this property can be set even when the Flash runtime is in full-screen mode.

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

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

To disable scaling, set the fullScreenSourceRect=null in ActionScript 3.0, and undefined in ActionScript 2.0.

     stage.fullScreenSourceRect = null;
     

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 www.adobe.com/go/display_settings.

Related API Elements

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

package {
    import flash.display.Sprite;
    import flash.display.StageDisplayState;
    import flash.media.Video;
    import flash.net.NetConnection;
    import flash.net.NetStream;
    import flash.events.NetStatusEvent;
    import flash.events.AsyncErrorEvent;
    import flash.events.SecurityErrorEvent;
    import flash.events.MouseEvent;
    import flash.events.Event;
    import flash.geom.Rectangle;
    
    public class Stage_fullScreenSourceRectExample2 extends Sprite {
        private var videoURL:String = "testVideo1.flv";
        private var connection:NetConnection;
        private var stream:NetStream;
        private var myVideo:Video;        
        private    var savedWidth:uint;
        private    var savedHeight:uint;
 
        public function Stage_fullScreenSourceRectExample2() {
    
            connection = new NetConnection();
             connection.addEventListener(NetStatusEvent.NET_STATUS, netStatusHandler);    
            connection.addEventListener(SecurityErrorEvent.SECURITY_ERROR, securityErrorHandler);
            connection.connect(null);

            loaderInfo.addEventListener(Event.INIT, createMouseListener);            
        }

        private function createMouseListener(event:Event):void {
            stage.addEventListener(MouseEvent.CLICK, toggleFullScreen);
        }        

        private function toggleFullScreen(event:MouseEvent):void {

            if(stage.displayState == StageDisplayState.NORMAL) {
                myVideo.width = myVideo.videoWidth;
                  myVideo.height = myVideo.videoHeight;

                try {
                    stage.fullScreenSourceRect = new Rectangle(myVideo.x, myVideo.y, 
                                                           myVideo.width, myVideo.height);
                     stage.displayState = StageDisplayState.FULL_SCREEN;

                 } catch (e:SecurityError) {
                     trace ("A security error occurred while switching to full screen: " + event);
                    myVideo.width = savedWidth;
                    myVideo.height = savedHeight;
                 }

            }else {
                myVideo.width = savedWidth;
                myVideo.height = savedHeight;
                stage.displayState = StageDisplayState.NORMAL;
            }
        }    

       private function netStatusHandler(event:NetStatusEvent):void {
            switch (event.info.code) {
                case "NetConnection.Connect.Success":
                    connectStream();
                    break;
                case "NetStream.Play.StreamNotFound":
                    trace ("Unable to locate video: " + videoURL);
                    break;
            }
        }

       private function connectStream():void {
            var stream:NetStream = new NetStream(connection);
            stream.addEventListener(NetStatusEvent.NET_STATUS, netStatusHandler);
            stream.addEventListener(AsyncErrorEvent.ASYNC_ERROR, asyncErrorHandler);     

             myVideo = new Video();
            myVideo.attachNetStream(stream);
            stream.play(videoURL);

            savedWidth = myVideo.width;
            savedHeight = myVideo.height;

            addChild(myVideo);
        }
       
        private function securityErrorHandler(event:SecurityErrorEvent):void {
            trace("securityErrorHandler: " + event);    
        }
        
        private function asyncErrorHandler(event:AsyncErrorEvent):void {
            
        }            
    }
}

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.TOP_LEFT and Stage.scaleMode is set to StageScaleMode.NO_SCALE.

Related API Elements

import flash.display.Sprite;
import flash.display.Stage;
import flash.display.StageDisplayState;
import flash.events.MouseEvent;
import flash.geom.Rectangle;
 
// cover the stage with a green rectangle
var greenRect:Sprite = new Sprite();
greenRect.graphics.beginFill(0x00FF00);
greenRect.graphics.drawRect(0, 0, stage.stageWidth, stage.stageHeight);
addChild(greenRect);
 
// create red square on stage, turn it into a button for going to full screen
var redSquare:Sprite = new Sprite();
redSquare.graphics.beginFill(0xFF0000);
redSquare.graphics.drawRect(0, 0, 300, 300);
redSquare.x = 50;
redSquare.y = 50;
redSquare.addEventListener(MouseEvent.CLICK, enterFullScreen);
redSquare.buttonMode = true;
addChild(redSquare);
 
function enterFullScreen(e:MouseEvent):void
{
    // we will go to full screen zoomed in on the red square
    var redSquare:Sprite = e.target as Sprite;
    var fullScreenRect:Rectangle = new Rectangle(redSquare.x, redSquare.y, redSquare.width, redSquare.height);
 
    // calculate aspect ratio of the red square
    var rectAspectRatio:Number = fullScreenRect.width / fullScreenRect.height;
 
    // calculate aspect ratio of the screen
    var screenAspectRatio:Number = stage.fullScreenWidth / stage.fullScreenHeight;
  
    // change the fullScreenRect so that it covers the entire screen, keeping it centered on the redSquare
    // try commenting out this section to see what happens if you do not fix the aspect ratio.
    if (rectAspectRatio > screenAspectRatio) {
         var newHeight:Number = fullScreenRect.width / screenAspectRatio;
         fullScreenRect.y -= ((newHeight - fullScreenRect.height) / 2);
        fullScreenRect.height = newHeight;
    } else if (rectAspectRatio < screenAspectRatio) {
        var newWidth:Number = fullScreenRect.height * screenAspectRatio;
        fullScreenRect.x -= ((newWidth - fullScreenRect.width) / 2);
        fullScreenRect.width = newWidth;
    }
 
    // go to full screen
    stage.fullScreenSourceRect = fullScreenRect;
    stage.displayState = StageDisplayState.FULL_SCREEN;
}

Indicates the height of the display object, in pixels. The height is calculated based on the bounds of the content of the display object. When you set the height property, the scaleY property is adjusted accordingly, as shown in the following code:

    var rect:Shape = new Shape();
    rect.graphics.beginFill(0xFF0000);
    rect.graphics.drawRect(0, 0, 100, 100);
    trace(rect.scaleY) // 1;
    rect.height = 200;
    trace(rect.scaleY) // 2;

Except for TextField and Video objects, a display object with no content (such as an empty sprite) has a height of 0, even if you try to set height to a different value.

Determines whether or not the children of the object are mouse, or user input device, enabled. If an object is enabled, a user can interact with it by using a mouse or user input device. The default is true.

This property is useful when you create a button with an instance of the Sprite class (instead of using the SimpleButton class). When you use a Sprite instance to create a button, you can choose to decorate the button by using the addChild() method to add additional Sprite instances. This process can cause unexpected behavior with mouse events because the Sprite instances you add as children can become the target object of a mouse event when you expect the parent instance to be the target object. To ensure that the parent instance serves as the target objects for mouse events, you can set the mouseChildren property of the parent instance to false.

No event is dispatched by setting this property. You must use the addEventListener() method to create interactive functionality.

Set to true to enable mouse locking. Enabling mouse locking turns off the cursor, and allows mouse movement with no bounds. You can only enable mouse locking in full-screen mode for desktop applications. Setting it on applications not in full-screen mode, or for applications on mobile devices, throws an exception.

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

• The user exits full-screen mode by using the Esc key (all platforms), Control-W (Windows), Command-W (Mac), or Alt-F4 (Windows).
• The application window loses focus.
• Any settings UI is visible, including all privacy dialog boxes.
• A native dialog box is shown, such as a file upload dialog box.

When exiting full screen mode, this property is automatically set to false.

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.

Note: When the application is in full-screen mode, mouse event listeners attached to display objects other than the Stage are not dispatched. Therefore, to receive mouse deltas and any other mouse events when mouseLock is true, attach the mouse event listeners to the Stage object.

Related API Elements

A reference to the NativeWindow object containing this Stage.

The window represents the native operating system window; the Stage represents the content contained by the window. This property is only valid for content running in AIR on platforms that support the NativeWindow class. On other platforms, this property will be null. In Flash Player (content running in a browser), this property will also be null.

Returns the number of children of this object.

The current orientation of the stage. This property is set to one of four values, defined as constants in the StageOrientation class:

To set the stage orientation, use the setOrientation() method.

Important: orientation property is supported on Android devices from 2.6 namespace onwards.

Learn more

Related API Elements

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.

The BitmapData.draw() method uses the value of the Stage.quality property. Alternatively, you can use the BitmapData.drawWithQuality() method, which lets you specify the quality parameter to the method, ignoring the current value of Stage.quality.

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

Related API Elements

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

• StageScaleMode.EXACT_FIT—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.SHOW_ALL—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.NO_BORDER—The entire application fills the specified area, without distortion but possibly with some cropping, while maintaining the original aspect ratio of the application.
• StageScaleMode.NO_SCALE—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.

More examples

Related API Elements

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.

A Rectangle specifying the area of the stage that is currently covered by a soft keyboard. The Rect's components are (0,0,0,0) when the soft keyboard isn't raised.

Related API Elements

A list of Stage3D objects available for displaying 3-dimensional content.

You can use only a limited number of Stage3D objects at a time. The number of available Stage3D objects depends on the platform and on the available hardware.

A Stage3D object draws in front of a StageVideo object and behind the Flash display list.

Related API Elements

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

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.NO_SCALE 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 AC_FL_RunContent() method must be set to a percentage, too. This percentage is applied to the stageHeight value.

Related API Elements

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. The StageVideo object at index 1 is displayed in front of the StageVideo object at index 0.
3. The StageVideo object at index 2 is displayed in front of the StageVideo object at index 1.

Use the StageVideo.depth property to change this ordering.

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

Related API Elements

 
var stageVideo:StageVideo;

if ( stage.stageVideos.length >= 1 ) {
    stageVideo = stage.stageVideos[0];
}

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.NO_SCALE 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 AC_FL_RunContent() method must be set to a percentage, too. This percentage is applied to the stageWidth value.

Related API Elements

The orientations supported by the current device.

You can use the orientation strings included in this list as parameters for the setOrientation() method. Setting an unsupported orientation fails without error.

The possible orientations include:

Related API Elements

Whether the application supports changes in the stage orientation (and device rotation). Currently, this property is only true in AIR applications running on mobile devices.

Related API Elements

Determines whether the children of the object are tab enabled. Enables or disables tabbing for the children of the object. The default is true.

Note: Do not use the tabChildren property with Flex. Instead, use the mx.core.UIComponent.hasFocusableChildren property.

Returns a TextSnapshot object for this DisplayObjectContainer instance.

Indicates the width of the display object, in pixels. The width is calculated based on the bounds of the content of the display object. When you set the width property, the scaleX property is adjusted accordingly, as shown in the following code:

    var rect:Shape = new Shape();
    rect.graphics.beginFill(0xFF0000);
    rect.graphics.drawRect(0, 0, 100, 100);
    trace(rect.scaleX) // 1;
    rect.width = 200;
    trace(rect.scaleX) // 2;

Except for TextField and Video objects, a display object with no content (such as an empty sprite) has a width of 0, even if you try to set width to a different value.

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

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.

Related API Elements

mySprite.addEventListener(EXIT_FRAME, exithandler):

function exithandler(exiteventobject:Event):void {
                trace(stage.wmodeGPU);
}

Adds a child DisplayObject instance to this DisplayObjectContainer instance. The child is added to the front (top) of all other children in this DisplayObjectContainer instance. (To add a child to a specific index position, use the addChildAt() method.)

If you add a child object that already has a different display object container as a parent, the object is removed from the child list of the other display object container.

Note: The command stage.addChild() can cause problems with a published SWF file, including security problems and conflicts with other loaded SWF files. There is only one Stage within a Flash runtime instance, no matter how many SWF files you load into the runtime. So, generally, objects should not be added to the Stage, directly, at all. The only object the Stage should contain is the root object. Create a DisplayObjectContainer to contain all of the items on the display list. Then, if necessary, add that DisplayObjectContainer instance to the Stage.

Parameters

More examples

Learn more

Adds a child DisplayObject instance to this DisplayObjectContainer instance. The child is added at the index position specified. An index of 0 represents the back (bottom) of the display list for this DisplayObjectContainer object.

For example, the following example shows three display objects, labeled a, b, and c, at index positions 0, 2, and 1, respectively:

If you add a child object that already has a different display object container as a parent, the object is removed from the child list of the other display object container.

Parameters

More examples

Learn more

Registers an event listener object with an EventDispatcher object so that the listener receives notification of an event. You can register event listeners on all nodes in the display list for a specific type of event, phase, and priority.

After you successfully register an event listener, you cannot change its priority through additional calls to addEventListener(). To change a listener's priority, you must first call removeListener(). Then you can register the listener again with the new priority level.

Keep in mind that after the listener is registered, subsequent calls to addEventListener() with a different type or useCapture value result in the creation of a separate listener registration. For example, if you first register a listener with useCapture set to true, it listens only during the capture phase. If you call addEventListener() again using the same listener object, but with useCapture set to false, you have two separate listeners: one that listens during the capture phase and another that listens during the target and bubbling phases.

You cannot register an event listener for only the target phase or the bubbling phase. Those phases are coupled during registration because bubbling applies only to the ancestors of the target node.

If you no longer need an event listener, remove it by calling removeEventListener(), or memory problems could result. Event listeners are not automatically removed from memory because the garbage collector does not remove the listener as long as the dispatching object exists (unless the useWeakReference parameter is set to true).

Copying an EventDispatcher instance does not copy the event listeners attached to it. (If your newly created node needs an event listener, you must attach the listener after creating the node.) However, if you move an EventDispatcher instance, the event listeners attached to it move along with it.

If the event listener is being registered on a node while an event is being processed on this node, the event listener is not triggered during the current phase but can be triggered during a later phase in the event flow, such as the bubbling phase.

If an event listener is removed from a node while an event is being processed on the node, it is still triggered by the current actions. After it is removed, the event listener is never invoked again (unless registered again for future processing).

Parameters

function(evt:Event):void

Learn more

Sets keyboard focus to the interactive object specified by objectToFocus, with the focus direction specified by the direction parameter.

The concept of focus direction must be defined by the application (or application framework). No intrinsic focus sorting of interactive objects exists, although you could use other available properties to establish an ordering principle. For example, you could sort interactive objects according to their positions on the Stage or in the display list. Calling assignFocus() is equivalent to setting the Stage.focus property, with the additional ability to indicate the direction from which the focus is being set.

The objectToFocus will dispatch a focusIn event on receiving focus. The direction property of the FocusEvent object will report the setting of the direction parameter.

If you assign an HTMLLoader object to the objectToFocus parameter, the HTMLLoader object selects the appropriate focusable object in the HTML DOM, based on the direction parameter value. If it is FocusDirection.BOTTOM, the focusable object in the HTML DOM at the end of the reading order is given focus. If it is FocusDirection.TOP, the focusable object in the HTML DOM at the beginning of the reading order is given focus. If it is NONE, the HTMLLoader object receives focus without changing its current focused element.

Parameters

Related API Elements

Dispatches an event into the event flow. The event target is the EventDispatcher object upon which the dispatchEvent() method is called.

Parameters

Checks whether the EventDispatcher object has any listeners registered for a specific type of event. This allows you to determine where an EventDispatcher object has altered handling of an event type in the event flow hierarchy. To determine whether a specific event type actually triggers an event listener, use willTrigger().

The difference between hasEventListener() and willTrigger() is that hasEventListener() examines only the object to which it belongs, whereas willTrigger() examines the entire event flow for the event specified by the type parameter.

When hasEventListener() is called from a LoaderInfo object, only the listeners that the caller can access are considered.

Parameters

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.

Related API Elements

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.

Removes a child DisplayObject from the specified index position in the child list of the DisplayObjectContainer. The parent property of the removed child is set to null, and the object is garbage collected if no other references to the child exist. The index positions of any display objects above the child in the DisplayObjectContainer are decreased by 1.

The garbage collector reallocates unused memory space. When a variable or object is no longer actively referenced or stored somewhere, the garbage collector sweeps through and wipes out the memory space it used to occupy if no other references to it exist.

Parameters

Sets the stage to an orientation with the specified aspect ratio.

If the stage orientation changes as a result of the method call, the Stage object dispatches an orientationChange event.

To check whether device orientation is supported, check the value of the Stage.supportsOrientantionChange property.

AIR profile support: This feature is supported on mobile devices, but it is not supported on desktop operating systems or AIR for TV devices. You can test for support at run time using the Stage.supportsOrientantionChange property. See AIR Profile Support for more information regarding API support across multiple profiles.

Parameters

Related API Elements

Changes the position of an existing child in the display object container. This affects the layering of child objects. For example, the following example shows three display objects, labeled a, b, and c, at index positions 0, 1, and 2, respectively:

When you use the setChildIndex() method and specify an index position that is already occupied, the only positions that change are those in between the display object's former and new position. All others will stay the same. If a child is moved to an index LOWER than its current index, all children in between will INCREASE by 1 for their index reference. If a child is moved to an index HIGHER than its current index, all children in between will DECREASE by 1 for their index reference. For example, if the display object container in the previous example is named container, you can swap the position of the display objects labeled a and b by calling the following code:

container.setChildIndex(container.getChildAt(1), 0);

This code results in the following arrangement of objects:

Parameters

Sets the stage to the specified orientation.

Set the newOrientation parameter to one of the following four values defined as constants in the StageOrientation class:

Do not set the parameter to StageOrientation.UNKNOWN or any string value other than those listed in the table.

To check whether changing device orientation is supported, check the value of the Stage.supportsOrientantionChange property. Check the list provided by the supportedOrientations property to determine which orientations are supported by the current device.

Setting the orientation is an asynchronous operation. It is not guaranteed to be complete immediately after you call the setOrientation() method. Add an event listener for the orientationChange event to determine when the orientation change is complete.

Important: The setOrientation() method was not supported on Android devices before AIR 2.6.

Parameters

Related API Elements

Swaps the z-order (front-to-back order) of the child objects at the two specified index positions in the child list. All other child objects in the display object container remain in the same index positions.

Parameters

Checks whether an event listener is registered with this EventDispatcher object or any of its ancestors for the specified event type. This method returns true if an event listener is triggered during any phase of the event flow when an event of the specified type is dispatched to this EventDispatcher object or any of its descendants.

The difference between the hasEventListener() and the willTrigger() methods is that hasEventListener() examines only the object to which it belongs, whereas the willTrigger() method examines the entire event flow for the event specified by the type parameter.

When willTrigger() is called from a LoaderInfo object, only the listeners that the caller can access are considered.

Parameters

Dispatched when the browserZoomFactor property of the Stage object is changed.

This event has the following properties:

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.

This event has the following properties:

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.

This event has the following properties:

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.

Learn more

Dispatched by the Stage object when the stage orientation begins changing.

Important: orientationChanging events are not dispatched on Android devices.

Notes:

• 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.
• When you set the orientation programatically with the setOrientation() method, the orientationChanging event is not dispatched.

Important: ORIENTATION_CHANGING events are not dispatched on Android devices.

Learn more

Dispatched when the scaleMode property of the Stage object is set to StageScaleMode.NO_SCALE and the SWF file is resized. Also dispatched when screen orientation changes while in full screen mode in Flash Player 15 and later.

This event has the following properties:

Dispatched by the Stage object when the state of the stageVideos property changes.

This event has the following properties:

1. The class constructor first sets the Flash application to be fixed, regardless of the size of the Flash Player window and then adds two event listeners with the activateHandler() and resizeHandler() methods.
2. The activateHandler() method runs when the left mouse button is clicked.
3. The resizeHandler() method runs when the stage is resized.

package {
    import flash.display.Sprite;
    import flash.display.StageAlign;
    import flash.display.StageScaleMode;
    import flash.events.Event;

    public class StageExample extends Sprite {

        public function StageExample() {
            stage.scaleMode = StageScaleMode.NO_SCALE;
            stage.align = StageAlign.TOP_LEFT;
            stage.addEventListener(Event.ACTIVATE, activateHandler);
            stage.addEventListener(Event.RESIZE, resizeHandler);
        }

        private function activateHandler(event:Event):void {
            trace("activateHandler: " + event);
        }

        private function resizeHandler(event:Event):void {
            trace("resizeHandler: " + event);
            trace("stageWidth: " + stage.stageWidth + " stageHeight: " + stage.stageHeight);
        }
    }
}