Packageflash.display
Classpublic class Stage
InheritanceStage Inheritance DisplayObjectContainer Inheritance InteractiveObject Inheritance DisplayObject Inheritance EventDispatcher Inheritance Object

Language Version : ActionScript 3.0
Runtime Versions : AIR 1.0, Flash Player 9

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

In JavaScript, you can access the stage property of the window containing an HTML page by getting the runtime.nativeWindow.stage property. This property is only available to content running in the application security sandbox.

Many Stage properties and methods pertain to Stage objects running in SWF files (which use the ActionScript 3.0 display list). These properties and methods are not as useful to JavaScript code running in HTML-based AIR applications. For details on these properties and methods, see the ActionScript 3.0 Language Reference.

The following Stage properties are most useful in HTML-based AIR applications:

View the examples



Public Properties
 PropertyDefined By
 InheritedaccessibilityProperties : AccessibilityProperties
The current accessibility options for this display object.
DisplayObject
  align : String
A value from the StageAlign class that specifies the alignment of the stage in Flash Player or the browser.
Stage
 Inheritedalpha : Number
Indicates the alpha transparency value of the object specified.
DisplayObject
 InheritedblendMode : String
A value from the BlendMode class that specifies which blend mode to use.
DisplayObject
 InheritedcacheAsBitmap : Boolean
If set to true, Flash Player or Adobe AIR caches an internal bitmap representation of the display object.
DisplayObject
 Inheritedconstructor : Object
A reference to the class object or constructor function for a given object instance.
Object
 InheritedcontextMenu : NativeMenu
Specifies the context menu associated with this object.
InteractiveObject
  displayState : String
A value from the StageDisplayState class that specifies which display state to use.
Stage
 InheriteddoubleClickEnabled : Boolean
Specifies whether the object receives doubleClick events.
InteractiveObject
 Inheritedfilters : Array
An indexed array that contains each filter object currently associated with the display object.
DisplayObject
  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.
Stage
 InheritedfocusRect : Object
Specifies whether this object displays a focus rectangle.
InteractiveObject
  frameRate : Number
Gets and sets the frame rate of the stage.
Stage
  fullScreenHeight : uint
[read-only] Returns the height of the monitor that will be used when going to full screen size, if that state is entered immediately.
Stage
  fullScreenSourceRect : Rectangle
Sets Flash Player to scale a specific region of the stage to full-screen mode.
Stage
  fullScreenWidth : uint
[read-only] Returns the width of the monitor that will be used when going to full screen size, if that state is entered immediately.
Stage
  height : Number
Indicates the height of the display object, in pixels.
Stage
 InheritedloaderInfo : LoaderInfo
[read-only] Returns a LoaderInfo object containing information about loading the file to which this display object belongs.
DisplayObject
 Inheritedmask : DisplayObject
The calling display object is masked by the specified mask object.
DisplayObject
  mouseChildren : Boolean
Determines whether or not the children of the object are mouse enabled.
Stage
 InheritedmouseEnabled : Boolean
Specifies whether this object receives mouse messages.
InteractiveObject
 InheritedmouseX : Number
[read-only] Indicates the x coordinate of the mouse position, in pixels.
DisplayObject
 InheritedmouseY : Number
[read-only] Indicates the y coordinate of the mouse position, in pixels.
DisplayObject
 Inheritedname : String
Indicates the instance name of the DisplayObject.
DisplayObject
  AIR-only nativeWindow : NativeWindow
[read-only] A reference to the NativeWindow object containing this Stage.
Stage
  numChildren : int
[read-only] Returns the number of children of this object.
Stage
 InheritedopaqueBackground : Object
Specifies whether the display object is opaque with a certain background color.
DisplayObject
 Inheritedparent : DisplayObjectContainer
[read-only] Indicates the DisplayObjectContainer object that contains this display object.
DisplayObject
 Inheritedprototype : Object
[static] A reference to the prototype object of a class or function object.
Object
  quality : String
A value from the StageQuality class that specifies which rendering quality is used.
Stage
 Inheritedroot : DisplayObject
[read-only] For a display object in a loaded SWF file, the root property is the top-most display object in the portion of the display list's tree structure represented by that SWF file.
DisplayObject
 Inheritedrotation : Number
Indicates the rotation of the DisplayObject instance, in degrees, from its original orientation.
DisplayObject
 Inheritedscale9Grid : Rectangle
The current scaling grid that is in effect.
DisplayObject
  scaleMode : String
A value from the StageScaleMode class that specifies which scale mode to use.
Stage
 InheritedscaleX : Number
Indicates the horizontal scale (percentage) of the object as applied from the registration point.
DisplayObject
 InheritedscaleY : Number
Indicates the vertical scale (percentage) of an object as applied from the registration point of the object.
DisplayObject
 InheritedscrollRect : Rectangle
The scroll rectangle bounds of the display object.
DisplayObject
  showDefaultContextMenu : Boolean
Specifies whether to show or hide the default items in the Flash Player context menu.
Stage
 Inheritedstage : Stage
[read-only] The Stage of the display object.
DisplayObject
  stageFocusRect : Boolean
Specifies whether or not objects display a glowing border when they have focus.
Stage
  stageHeight : int
The current height, in pixels, of the Stage.
Stage
  stageWidth : int
Specifies the current width, in pixels, of the Stage.
Stage
  tabChildren : Boolean
Determines whether the children of the object are tab enabled.
Stage
 InheritedtabEnabled : Boolean
Specifies whether this object is in the tab order.
InteractiveObject
 InheritedtabIndex : int
Specifies the tab ordering of objects in a SWF file.
InteractiveObject
  textSnapshot : TextSnapshot
[read-only] Returns a TextSnapshot object for this DisplayObjectContainer instance.
Stage
 Inheritedtransform : Transform
An object with properties pertaining to a display object's matrix, color transform, and pixel bounds.
DisplayObject
 Inheritedvisible : Boolean
Whether or not the display object is visible.
DisplayObject
  width : Number
Indicates the width of the display object, in pixels.
Stage
 Inheritedx : Number
Indicates the x coordinate of the DisplayObject instance relative to the local coordinates of the parent DisplayObjectContainer.
DisplayObject
 Inheritedy : Number
Indicates the y coordinate of the DisplayObject instance relative to the local coordinates of the parent DisplayObjectContainer.
DisplayObject
Public Methods
 MethodDefined By
  
Adds a child DisplayObject instance to this DisplayObjectContainer instance.
Stage
  
Adds a child DisplayObject instance to this DisplayObjectContainer instance.
Stage
  
addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void
Registers an event listener object with an EventDispatcher object so that the listener receives notification of an event.
Stage
 Inherited
Indicates whether the security restrictions would cause any display objects to be omitted from the list returned by calling the DisplayObjectContainer.getObjectsUnderPoint() method with the specified point point.
DisplayObjectContainer
  
AIR-only assignFocus(objectToFocus:InteractiveObject, direction:String):void
Sets keyboard focus to the interactive object specified by objectToFocus, with the focus direction specified by the direction parameter.
Stage
 Inherited
Determines whether the specified display object is a child of the DisplayObjectContainer instance or the instance itself.
DisplayObjectContainer
  
Dispatches an event into the event flow.
Stage
 Inherited
getBounds(targetCoordinateSpace:DisplayObject):Rectangle
Returns a rectangle that defines the area of the display object relative to the coordinate system of the targetCoordinateSpace object.
DisplayObject
 Inherited
Returns the child display object instance that exists at the specified index.
DisplayObjectContainer
 Inherited
Returns the child display object that exists with the specified name.
DisplayObjectContainer
 Inherited
Returns the index position of a child DisplayObject instance.
DisplayObjectContainer
 Inherited
Returns an array of objects that lie under the specified point and are children (or grandchildren, and so on) of this DisplayObjectContainer instance.
DisplayObjectContainer
 Inherited
getRect(targetCoordinateSpace:DisplayObject):Rectangle
Returns a rectangle that defines the boundary of the display object, based on the coordinate system defined by the targetCoordinateSpace parameter, excluding any strokes on shapes.
DisplayObject
 Inherited
Converts the point object from the Stage (global) coordinates to the display object's (local) coordinates.
DisplayObject
  
Checks whether the EventDispatcher object has any listeners registered for a specific type of event.
Stage
 Inherited
Indicates whether an object has a specified property defined.
Object
 Inherited
Evaluates the display object to see if it overlaps or intersects with the obj display object.
DisplayObject
 Inherited
hitTestPoint(x:Number, y:Number, shapeFlag:Boolean = false):Boolean
Evaluates the display object to see if it overlaps or intersects with the point specified by the x and y parameters.
DisplayObject
  
Calling the invalidate() method signals Flash Player 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).
Stage
  
Determines whether the Stage.focus property returns null for security reasons.
Stage
 Inherited
Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter.
Object
 Inherited
Converts the point object from the display object's (local) coordinates to the Stage (global) coordinates.
DisplayObject
 Inherited
Indicates whether the specified property exists and is enumerable.
Object
 Inherited
Removes the specified child DisplayObject instance from the child list of the DisplayObjectContainer instance.
DisplayObjectContainer
  
Removes a child DisplayObject from the specified index position in the child list of the DisplayObjectContainer.
Stage
 Inherited
removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void
Removes a listener from the EventDispatcher object.
EventDispatcher
  
Changes the position of an existing child in the display object container.
Stage
 Inherited
Sets the availability of a dynamic property for loop operations.
Object
 Inherited
Swaps the z-order (front-to-back order) of the two specified child objects.
DisplayObjectContainer
  
swapChildrenAt(index1:int, index2:int):void
Swaps the z-order (front-to-back order) of the child objects at the two specified index positions in the child list.
Stage
 Inherited
Returns the string representation of the specified object.
Object
 Inherited
Returns the primitive value of the specified object.
Object
  
Checks whether an event listener is registered with this EventDispatcher object or any of its ancestors for the specified event type.
Stage
Events
 Event Summary Defined By
 InheritedDispatched when Flash Player or an AIR application gains operating system focus and becomes active.EventDispatcher
 InheritedDispatched when a display object is added to the display list.DisplayObject
 InheritedDispatched when a display object is added to the on stage display list, either directly or through the addition of a sub tree in which the display object is contained.DisplayObject
 InheritedDispatched when a user presses and releases the main button of the user's pointing device over the same InteractiveObject.InteractiveObject
 InheritedDispatched when the user selects the context menu associated with this interactive object in an AIR application.InteractiveObject
 InheritedDispatched when Flash Player or an AIR application loses operating system focus and is becoming inactive.EventDispatcher
 InheritedDispatched when a user presses and releases the main button of a pointing device twice in rapid succession over the same InteractiveObject when that object's doubleClickEnabled flag is set to true.InteractiveObject
 InheritedDispatched when the playhead is entering a new frame.DisplayObject
 InheritedDispatched after a display object gains focus.InteractiveObject
 InheritedDispatched after a display object loses focus.InteractiveObject
  Dispatched when the Stage object enters, or leaves, full-screen mode.Stage
 InheritedDispatched when the user presses a key.InteractiveObject
 InheritedDispatched when the user attempts to change focus by using keyboard navigation.InteractiveObject
 InheritedDispatched when the user releases a key.InteractiveObject
 InheritedDispatched when a user presses and releases the middle button of the user's pointing device over the same InteractiveObject.InteractiveObject
 InheritedDispatched when a user presses the middle pointing device button over an InteractiveObject instance.InteractiveObject
 InheritedDispatched when a user releases the pointing device button over an InteractiveObject instance.InteractiveObject
 InheritedDispatched when a user presses the pointing device button over an InteractiveObject instance.InteractiveObject
 InheritedDispatched when the user attempts to change focus by using a pointer device.InteractiveObject
  Dispatched by the Stage object when the mouse pointer moves out of the stage area.Stage
 InheritedDispatched when a user moves the pointing device while it is over an InteractiveObject.InteractiveObject
 InheritedDispatched when the user moves a pointing device away from an InteractiveObject instance.InteractiveObject
 InheritedDispatched when the user moves a pointing device over an InteractiveObject instance.InteractiveObject
 InheritedDispatched when a user releases the pointing device button over an InteractiveObject instance.InteractiveObject
 InheritedDispatched when a mouse wheel is spun over an InteractiveObject instance.InteractiveObject
 InheritedDispatched by the drag initiator InteractiveObject when the user releases the drag gesture.InteractiveObject
 InheritedDispatched by the target InteractiveObject when a dragged object is dropped on it and the drop has been accepted with a call to DragManager.acceptDragDrop().InteractiveObject
 InheritedDispatched by an InteractiveObject when a drag gesture enters its boundary.InteractiveObject
 InheritedDispatched by an InteractiveObject when a drag gesture leaves its boundary.InteractiveObject
 InheritedDispatched by an InteractiveObject continually while a drag gesture remains within its boundary.InteractiveObject
 InheritedDispatched at the beginning of a drag operation by the InteractiveObject that is specified as the drag initiator in the DragManager.doDrag() call.InteractiveObject
 InheritedDispatched during a drag operation by the InteractiveObject that is specified as the drag initiator in the DragManager.doDrag() call.InteractiveObject
 InheritedDispatched when a display object is about to be removed from the display list.DisplayObject
 InheritedDispatched when a display object is about to be removed from the display list, either directly or through the removal of a sub tree in which the display object is contained.DisplayObject
 InheritedDispatched when the display list is about to be updated and rendered.DisplayObject
  Dispatched when the scaleMode property of the Stage object is set to StageScaleMode.NO_SCALE and the SWF file is resized.Stage
 InheritedDispatched when a user presses and releases the right button of the user's pointing device over the same InteractiveObject.InteractiveObject
 InheritedDispatched when a user presses the pointing device button over an InteractiveObject instance.InteractiveObject
 InheritedDispatched when a user releases the pointing device button over an InteractiveObject instance.InteractiveObject
 InheritedDispatched when the user moves a pointing device away from an InteractiveObject instance.InteractiveObject
 InheritedDispatched when the user moves a pointing device over an InteractiveObject instance.InteractiveObject
 InheritedDispatched when the value of the object's tabChildren flag changes.InteractiveObject
 InheritedDispatched when the object's tabEnabled flag changes.InteractiveObject
 InheritedDispatched when the value of the object's tabIndex property changes.InteractiveObject
Property Detail
alignproperty
align:String  [read-write]

Language Version : ActionScript 3.0
Runtime Versions : AIR 1.0, Flash Player 9

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

ValueVertical AlignmentHorizontal
StageAlign.TOPTopCenter
StageAlign.BOTTOMBottomCenter
StageAlign.LEFTCenterLeft
StageAlign.RIGHTCenterRight
StageAlign.TOP_LEFTTopLeft
StageAlign.TOP_RIGHTTopRight
StageAlign.BOTTOM_LEFTBottomLeft
StageAlign.BOTTOM_RIGHTBottomRight

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 Programming ActionScript 3.0.


Implementation
    public function get align():String
    public function set align(value:String):void

See also

displayStateproperty 
displayState:String  [read-write]

Language Version : ActionScript 3.0
Runtime Versions : AIR 1.0, Flash Player 9.0.28.0

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

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 the 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):

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 until either the video stops or full-screen mode is exited.


Implementation
    public function get displayState():String
    public function set displayState(value:String):void

Throws
SecurityError — Calling the displayState property of a Stage object throws an exception for any caller that is not 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 caller by calling the Security.allowDomain() method or the Security.allowInsecureDomain() method. For more information, see the "Security" chapter in Programming ActionScript 3.0. Trying to set the displayState property while the settings dialog is displayed, without a user response, or if the param or embed HTML tag's allowFullScreen attribute is not set to true throws a security error.

See also


Example
The following example creates an interactive demonstration of how to create a fullscreen experience by modifying the displayState property.

Note: Fullscreen can only be triggered in certain situations, such as if the user has clicked or pressed a key, due to security restrictions. When run in a browser, the allowFullScreen property must be set to true.

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.
        }            
    }
}
focusproperty 
focus:InteractiveObject  [read-write]

Language Version : ActionScript 3.0
Runtime Versions : AIR 1.0, Flash Player 9

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.


Implementation
    public function get focus():InteractiveObject
    public function set focus(value:InteractiveObject):void

Throws
Error — Throws an error if focus cannot be set to the target.
frameRateproperty 
frameRate:Number  [read-write]

Language Version : ActionScript 3.0
Runtime Versions : AIR 1.0, Flash Player 9

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


Implementation
    public function get frameRate():Number
    public function set frameRate(value:Number):void

Throws
SecurityError — Calling the frameRate property of a Stage object throws an exception for any caller that is not 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 caller by calling the Security.allowDomain() method or the Security.allowInsecureDomain() method. For more information, see the "Security" chapter in Programming ActionScript 3.0.
fullScreenHeightproperty 
fullScreenHeight:uint  [read-only]

Language Version : ActionScript 3.0
Runtime Versions : AIR 1.0, Flash Player 9.0.115.0

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.


Implementation
    public function get fullScreenHeight():uint

See also


Example
This example creates a green rectangle the size of the stage and places a red square on it that it activates as a button. Clicking the red square triggers the enterFullScreen() event handler, which sets the fullScreenSourceRect property and enters full screen mode. To set the fullScreenSourceRect property, the event handler starts with the location and dimensions of the red square. It then compares the aspect ratio (width divided by height) of the red square to the aspect ratio of the stage at full screen width and height so that it can expand the rectangle (fullScreenSourceRect) to match the screen's aspect ratio. The result is that the red square occupies the entire height of the monitor with the green background visible on each side. If the aspect ratio was not matched, the stage background color, which is white by default, would show on each side instead of the green background.

Note: Test this example in the browser. In the Flash Publish Settings dialog, on the HTML tab, select the template Flash Only - Allow Full Screen. Specify the Flash Player version 9.0.115.0, and make sure the Flash and HTML formats are selected on the Formats tab. Then publish and open the resulting HTML file in the browser.


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;
}
fullScreenSourceRectproperty 
fullScreenSourceRect:Rectangle  [read-write]

Language Version : ActionScript 3.0
Runtime Versions : AIR 1.0, Flash Player 9.0.115.0

Sets Flash Player to scale a specific region of the stage to full-screen mode. If available, Flash Player 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, Flash Player scales the specified area. The actual Stage size in pixels within ActionScript does not change. Flash Player 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 Player version.

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

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


Implementation
    public function get fullScreenSourceRect():Rectangle
    public function set fullScreenSourceRect(value:Rectangle):void

See also


Example
To take advantage of hardware scaling, you set the whole stage or part of the stage to full-screen mode. The following ActionScript 3.0 code sets the whole stage to full-screen mode:
 
import flash.geom.*; 
{
  stage.fullScreenSourceRect = new Rectangle(0,0,320,240);
  stage.displayState = StageDisplayState.FULL_SCREEN;
}
In the following example, the user can switch between playing a video in full or normal screen mode by clicking on the stage. If the SWF for this example is running in Flash Player 9.0.115.0 or later, then it will use hardware acceleration to improve the full-screen scaling of the display.

Before using the full-screen mode with hardware scaling, the following conditions must be met:

  1. Flash Player version 9.0.115.0 or later is needed, as well as an authoring tool that supports it.
  2. HTML templates need to be modified to support full screen. The allowFullScreen attribute must be set to true for the object and embed tag. (The scripts that generate SWF-embedding tags must also allow for full screen.) For sample of files that can be used for Flex Builder, see the article, Exploring full-screen mode in Flash Player 9.
  3. Your application must have permission and access to an FLV video file. In this example, it is assumed that Flash Video (FLV) file is in the same directory as the SWF file.
  4. The user must allow access to full screen.
  5. For additional information on hardware scaling, see the article Exploring Flash Player support for high-definition H.264 video and AAC audio for Flash Player.

An FLV file is loaded using NetConnection and NetStream objects. Since the FLV file is in the same directory as the SWF file and will connect via HTTP, the NetConnection.connect() method's parameter is set to null. The connect NetConnection object reports its status by dispatching a netStatus event which invokes the netStatusHandler() method. The netStatusHandler() method checks if the connection was successful and invokes connectStream() method, which creates a NetStream object that takes the NetConnection object as a parameter. It also creates a video object and attached the NetStream object to the video object. The video object then is added to the display list and the stream is set to play. Since the FLV video file does not contain metadata or cue point information, an AsyncError event will be dispatched. A listener must be set up to handle the event. Here the listener is set up and it ignores the event. Another listener for netStatus event is also set up for the NetStream object. It will display an error message if the stream was not found. (Note that netStatusHandler() could be used to handle any number of different status information reported for the stream or connection.)

When the properties and methods of a loaded SWF file are accessible, the createMouseListener() method is invoked. It sets up an event listener for when the mouse is clicked on the stage. The toggleFullScreen() method checks if the display state is in the full or normal screen mode. If it is normal, the size of the video object is set to the size of the video stream. The fullScreenSourceRect property is set to a rectangle matching the dimensions of the video object. Then the Stage.displayMode property is set to full screen, which causes the video in the source rectangle to expand to fill the full screen area. If system requirements are met, the machine's graphics hardware will be used to improve the performance of the full-screen video rendering and the display state is set to full-screen mode. In order to catch any security error that may occur while switching to the full-screen mode, a try...catch is used. (Note that the display state must be set to full-screen mode after the fullScreenSourceRect property is set.) Before switching to the normal-screen mode, the video object's width and height are set back to the saved original video object's width and height. Otherwise, the changes made to the video object for the full-screen mode will determine the width and height.

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 {
            
        }            
    }
}
fullScreenWidthproperty 
fullScreenWidth:uint  [read-only]

Language Version : ActionScript 3.0
Runtime Versions : AIR 1.0, Flash Player 9.0.115.0

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.


Implementation
    public function get fullScreenWidth():uint

See also


Example
This example creates a green rectangle the size of the stage and places a red square on it that it activates as a button. Clicking the red square triggers the enterFullScreen() event handler, which sets the fullScreenSourceRect property and enters full screen mode. To set the fullScreenSourceRect property, the event handler starts with the location and dimensions of the red square. It then compares the aspect ratio (width divided by height) of the red square to the aspect ratio of the stage at full screen width and height so that it can expand the rectangle (fullScreenSourceRect) to match the screen's aspect ratio. The result is that the red square occupies the entire height of the monitor with the green background visible on each side. If the aspect ratio was not matched, the stage background color, which is white by default, would show on each side instead of the green background.

Note: Test this example in the browser. In the Flash Publish Settings dialog, on the HTML tab, select the template Flash Only - Allow Full Screen. Specify the Flash Player version 9.0.115.0, and make sure the Flash and HTML formats are selected on the Formats tab. Then publish and open the resulting HTML file in the browser.


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;
}
heightproperty 
height:Number  [read-write]

Language Version : ActionScript 3.0
Runtime Versions : AIR 1.0, Flash Player 9

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.


Implementation
    public function get height():Number
    public function set height(value:Number):void

Throws
SecurityError — Referencing the height property of a Stage object throws an exception for any caller that is not 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 caller by calling the Security.allowDomain() method or the Security.allowInsecureDomain() method. For more information, see the "Security" chapter in Programming ActionScript 3.0.
 
IllegalOperationError — It is always illegal to set the height property of a Stage object, even if the calling object is the Stage owner (the main SWF file).
mouseChildrenproperty 
mouseChildren:Boolean  [read-write]

Language Version : ActionScript 3.0
Runtime Versions : AIR 1.0, Flash Player 9

Determines whether or not the children of the object are mouse enabled. If an object is mouse enabled, a user can interact with it by using a mouse. 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.


Implementation
    public function get mouseChildren():Boolean
    public function set mouseChildren(value:Boolean):void

Throws
SecurityError — Referencing the mouseChildren property of a Stage object throws an exception for any caller that is not 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 caller by calling the Security.allowDomain() method or the Security.allowInsecureDomain() method. For more information, see the "Security" chapter in Programming ActionScript 3.0.
AIR-only nativeWindowproperty 
nativeWindow:NativeWindow  [read-only]

Runtime Versions : AIR 1.0

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. In Flash Player (content running in a browser), this property will be null.


Implementation
    public function get nativeWindow():NativeWindow
numChildrenproperty 
numChildren:int  [read-only]

Language Version : ActionScript 3.0
Runtime Versions : AIR 1.0, Flash Player 9

Returns the number of children of this object.


Implementation
    public function get numChildren():int

Throws
SecurityError — Referencing the numChildren property of a Stage object throws an exception for any caller that is not 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 caller by calling the Security.allowDomain() method or the Security.allowInsecureDomain() method. For more information, see the "Security" chapter in Programming ActionScript 3.0.
qualityproperty 
quality:String  [read-write]

Language Version : ActionScript 3.0
Runtime Versions : AIR 1.0, Flash Player 9

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

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.

For content running in 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).

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.


Implementation
    public function get quality():String
    public function set quality(value:String):void

Throws
SecurityError — Calling the quality property of a Stage object throws an exception for any caller that is not 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 caller by calling the Security.allowDomain() method or the Security.allowInsecureDomain() method. For more information, see the "Security" chapter in Programming ActionScript 3.0.

See also

scaleModeproperty 
scaleMode:String  [read-write]

Language Version : ActionScript 3.0
Runtime Versions : AIR 1.0, Flash Player 9

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


Implementation
    public function get scaleMode():String
    public function set scaleMode(value:String):void

Throws
SecurityError — Calling the scaleMode property of a Stage object throws an exception for any caller that is not 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 caller by calling the Security.allowDomain() method or the Security.allowInsecureDomain() method. For more information, see the "Security" chapter in Programming ActionScript 3.0.

See also

showDefaultContextMenuproperty 
showDefaultContextMenu:Boolean  [read-write]

Language Version : ActionScript 3.0
Runtime Versions : AIR 1.0, Flash Player 9

Specifies whether to show or hide the default items in the Flash Player 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 Adobe Flash Player menu items appear.


Implementation
    public function get showDefaultContextMenu():Boolean
    public function set showDefaultContextMenu(value:Boolean):void

Throws
SecurityError — Calling the showDefaultContextMenu property of a Stage object throws an exception for any caller that is not 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 caller by calling the Security.allowDomain() method or the Security.allowInsecureDomain() method. For more information, see the "Security" chapter in Programming ActionScript 3.0.
stageFocusRectproperty 
stageFocusRect:Boolean  [read-write]

Language Version : ActionScript 3.0
Runtime Versions : AIR 1.0, Flash Player 9

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


Implementation
    public function get stageFocusRect():Boolean
    public function set stageFocusRect(value:Boolean):void

Throws
SecurityError — Calling the stageFocusRect property of a Stage object throws an exception for any caller that is not 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 caller by calling the Security.allowDomain() method or the Security.allowInsecureDomain() method. For more information, see the "Security" chapter in Programming ActionScript 3.0.
stageHeightproperty 
stageHeight:int  [read-write]

Language Version : ActionScript 3.0
Runtime Versions : AIR 1.0, Flash Player 9

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 Player window. The event listener allows you to control how the screen content adjusts when the user resizes the window.

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.


Implementation
    public function get stageHeight():int
    public function set stageHeight(value:int):void

Throws
SecurityError — Calling the stageHeight property of a Stage object throws an exception for any caller that is not 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 caller by calling the Security.allowDomain() method or the Security.allowInsecureDomain() method. For more information, see the "Security" chapter in Programming ActionScript 3.0.

See also

stageWidthproperty 
stageWidth:int  [read-write]

Language Version : ActionScript 3.0
Runtime Versions : AIR 1.0, Flash Player 9

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 Player window. The event listener allows you to control how the screen content adjusts when the user resizes the window.

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.


Implementation
    public function get stageWidth():int
    public function set stageWidth(value:int):void

Throws
SecurityError — Calling the stageWidth property of a Stage object throws an exception for any caller that is not 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 caller by calling the Security.allowDomain() method or the Security.allowInsecureDomain() method. For more information, see the "Security" chapter in Programming ActionScript 3.0.

See also

tabChildrenproperty 
tabChildren:Boolean  [read-write]

Language Version : ActionScript 3.0
Runtime Versions : AIR 1.0, Flash Player 9

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


Implementation
    public function get tabChildren():Boolean
    public function set tabChildren(value:Boolean):void

Throws
SecurityError — Referencing the tabChildren property of a Stage object throws an exception for any caller that is not 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 caller by calling the Security.allowDomain() method or the Security.allowInsecureDomain() method. For more information, see the "Security" chapter in Programming ActionScript 3.0.
textSnapshotproperty 
textSnapshot:TextSnapshot  [read-only]

Language Version : ActionScript 3.0
Runtime Versions : AIR 1.0, Flash Player 9

Returns a TextSnapshot object for this DisplayObjectContainer instance.


Implementation
    public function get textSnapshot():TextSnapshot

Throws
IllegalOperationError — Referencing the textSnapshot property of a Stage object throws an exception because the Stage class does not implement this property. To avoid this, call the textSnapshot property of a display object container other than the Stage object.
widthproperty 
width:Number  [read-write]

Language Version : ActionScript 3.0
Runtime Versions : AIR 1.0, Flash Player 9

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.


Implementation
    public function get width():Number
    public function set width(value:Number):void

Throws
SecurityError — Referencing the width property of a Stage object throws an exception for any caller that is not 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 caller by calling the Security.allowDomain() method or the Security.allowInsecureDomain() method. For more information, see the "Security" chapter in Programming ActionScript 3.0.
 
IllegalOperationError — It is always illegal to set the width property of a Stage object, even if you are the Stage owner.
Method Detail
addChild()method
override public function addChild(child:DisplayObject):DisplayObject

Language Version : ActionScript 3.0
Runtime Versions : AIR 1.0, Flash Player 9

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.

Parameters

child:DisplayObject — The DisplayObject instance to add as a child of this DisplayObjectContainer instance.

Returns
DisplayObject — The DisplayObject instance that you pass in the child parameter.

Throws
SecurityError — Calling the addChild() method of a Stage object throws an exception for any caller that is not 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 caller by calling the Security.allowDomain() method or the Security.allowInsecureDomain() method. For more information, see the "Security" chapter in Programming ActionScript 3.0.
addChildAt()method 
override public function addChildAt(child:DisplayObject, index:int):DisplayObject

Language Version : ActionScript 3.0
Runtime Versions : AIR 1.0, Flash Player 9

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:

b over c over a

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

child:DisplayObject — The DisplayObject instance to add as a child of this DisplayObjectContainer instance.
 
index:int — The index position to which the child is added. If you specify a currently occupied index position, the child object that exists at that position and all higher positions are moved up one position in the child list.

Returns
DisplayObject — The DisplayObject instance that you pass in the child parameter.

Throws
SecurityError — Calling the addChildAt() method of a Stage object throws an exception for any caller that is not 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 caller by calling the Security.allowDomain() method or the Security.allowInsecureDomain() method. For more information, see the "Security" chapter in Programming ActionScript 3.0.
addEventListener()method 
override public function addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void

Language Version : ActionScript 3.0
Runtime Versions : AIR 1.0, Flash Player 9

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.

JavaScript code in the AIR runtime uses this method to register event listeners for events defined by the AIR APIs. For other JavaScript events (such as the onload event of the DOM body object), you can use standard event handling techniques, as you would for content running in the browser.

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. Objects with registered event listeners are not automatically removed from memory because the garbage collector does not remove objects that still have references.

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

type:String — The type of event.
 
listener:Function — The listener function that processes the event. This function must accept an Event object as its only parameter and must return nothing, as this example shows: .
function(evt:Event):void

The function can have any name.

 
useCapture:Boolean (default = false)This parameter applies to display objects in the ActionScript 3.0 display list architecture, used by SWF content. Determines whether the listener works in the capture phase or the target and bubbling phases. If useCapture is set to true, the listener processes the event only during the capture phase and not in the target or bubbling phase. If useCapture is false, the listener processes the event only during the target or bubbling phase. To listen for the event in all three phases, call addEventListener twice, once with useCapture set to true, then again with useCapture set to false.
 
priority:int (default = 0) — The priority level of the event listener. The priority is designated by a signed 32-bit integer. The higher the number, the higher the priority. All listeners with priority n are processed before listeners of priority n-1. If two or more listeners share the same priority, they are processed in the order in which they were added. The default priority is 0.
 
useWeakReference:Boolean (default = false) — Determines whether the reference to the listener is strong or weak. A strong reference (the default) prevents your listener from being garbage-collected. A weak reference does not.

Class-level member functions are not subject to garbage collection, so you can set useWeakReference to true for class-level member functions without subjecting them to garbage collection. If you set useWeakReference to true for a listener that is a nested inner function, the function will be garbage-collected and no longer persistent. If you create references to the inner function (save it in another variable) then it is not garbage-collected and stays persistent.


Throws
SecurityError — Calling the addEventListener method of a Stage object throws an exception for any caller that is not in the same security sandbox as the Stage owner (the main SWF file). To avoid this situation, the Stage owner can grant permission to the domain of the caller by calling the Security.allowDomain() method or the Security.allowInsecureDomain() method. For more information, see the "Security" chapter in Programming ActionScript 3.0.
AIR-only assignFocus()method 
public function assignFocus(objectToFocus:InteractiveObject, direction:String):void

Language Version : ActionScript 3.0
Runtime Versions : AIR 1.0

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 recieving 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

objectToFocus:InteractiveObject — The object to focus, or null to clear the focus from any element on the Stage.
 
direction:String — The direction from which objectToFocus is being focused. Valid values are enumerated as constants in the FocusDirection class.


Throws
Error — If focus cannot be set to the target or direction is not a valid type.

See also

dispatchEvent()method 
override public function dispatchEvent(event:Event):Boolean

Language Version : ActionScript 3.0
Runtime Versions : AIR 1.0, Flash Player 9

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

Parameters

event:Event — The Event object that is dispatched into the event flow. If the event is being redispatched, a clone of the event is created automatically. After an event is dispatched, its target property cannot be changed, so you must create a new copy of the event for redispatching to work.

Returns
Boolean — A value of true if the event was successfully dispatched. A value of false indicates failure or that preventDefault() was called on the event.

Throws
SecurityError — Calling the dispatchEvent() method of a Stage object throws an exception for any caller that is not 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 caller by calling the Security.allowDomain() method or the Security.allowInsecureDomain() method. For more information, see the "Security" chapter in Programming ActionScript 3.0.
hasEventListener()method 
override public function hasEventListener(type:String):Boolean

Language Version : ActionScript 3.0
Runtime Versions : AIR 1.0, Flash Player 9

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. The event flow applies to the ActionScript 3.0 display list, used in SWF content.

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

Parameters

type:String — The type of event.

Returns
Boolean — A value of true if a listener of the specified type is registered; false otherwise.

Throws
SecurityError — Calling the hasEventListener() method of a Stage object throws an exception for any caller that is not 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 caller by calling the Security.allowDomain() method or the Security.allowInsecureDomain() method. For more information, see the "Security" chapter in Programming ActionScript 3.0.
invalidate()method 
public function invalidate():void

Language Version : ActionScript 3.0
Runtime Versions : AIR 1.0, Flash Player 9

Calling the invalidate() method signals Flash Player 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, Flash Player 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 Flash Player 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.

See also

isFocusInaccessible()method 
public function isFocusInaccessible():Boolean

Language Version : ActionScript 3.0
Runtime Versions : AIR 1.0, Flash Player 9

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.

Returns
Booleantrue if the object that has focus belongs to a security sandbox to which the SWF file does not have access.
removeChildAt()method 
override public function removeChildAt(index:int):DisplayObject

Runtime Versions : AIR 1.0, Flash Player 9

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

index:int — The child index of the DisplayObject to remove.

Returns
DisplayObject — The DisplayObject instance that was removed.

Throws
SecurityError — Calling the removeChildAt() method of a Stage object throws an exception for any caller that is not in the same security sandbox as the object to be removed. To avoid this, the owner of that object can grant permission to the domain of the caller by calling the Security.allowDomain() method or the Security.allowInsecureDomain() method. For more information, see the "Security" chapter in Programming ActionScript 3.0.
setChildIndex()method 
override public function setChildIndex(child:DisplayObject, index:int):void

Language Version : ActionScript 3.0
Runtime Versions : AIR 1.0, Flash Player 9

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:

c over b over a

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:

c over a over b

Parameters

child:DisplayObject — The child DisplayObject instance for which you want to change the index number.
 
index:int — The resulting index number for the child display object.


Throws
SecurityError — Calling the setChildIndex() method of a Stage object throws an exception for any caller that is not 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 caller by calling the Security.allowDomain() method or the Security.allowInsecureDomain() method. For more information, see the "Security" chapter in Programming ActionScript 3.0.
swapChildrenAt()method 
override public function swapChildrenAt(index1:int, index2:int):void

Language Version : ActionScript 3.0
Runtime Versions : AIR 1.0, Flash Player 9

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

index1:int — The index position of the first child object.
 
index2:int — The index position of the second child object.


Throws
SecurityError — Calling the swapChildrenAt() method of a Stage object throws an exception for any caller that is not in the same security sandbox as the owner of either of the objects to be swapped. To avoid this, the object owners can grant permission to the domain of the caller by calling the Security.allowDomain() method or the Security.allowInsecureDomain() method. For more information, see the "Security" chapter in Programming ActionScript 3.0.
willTrigger()method 
override public function willTrigger(type:String):Boolean

Language Version : ActionScript 3.0
Runtime Versions : AIR 1.0, Flash Player 9

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. The event flow applies to the ActionScript 3.0 display list, used in SWF content.

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

Parameters

type:String — The type of event.

Returns
Boolean — A value of true if a listener of the specified type will be triggered; false otherwise.

Throws
SecurityError — Calling the willTrigger() method of a Stage object throws an exception for any caller that is not 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 caller by calling the Security.allowDomain() method or the Security.allowInsecureDomain() method. For more information, see the "Security" chapter in Programming ActionScript 3.0.
Event Detail
fullScreen Event
Event Object Type: flash.events.FullScreenEvent
FullScreenEvent.type property = flash.events.FullScreenEvent.FULL_SCREEN

Language Version : ActionScript 3.0
Runtime Versions : AIR 1.0, Flash Player 9.0.28.0

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.

The FullScreenEvent.FULL_SCREEN constant defines the value of the type property of a fullScreen event object.

This event has the following properties:

PropertyValue
fullScreentrue if the display state is full screen or false if it is normal.
bubblesfalse
cancelablefalse; there is no default behavior to cancel.
currentTargetThe object that is actively processing the Event object with an event listener.
targetThe Stage object.
mouseLeave Event  
Event Object Type: flash.events.Event
Event.type property = flash.events.Event.MOUSE_LEAVE

Language Version : ActionScript 3.0
Runtime Versions : AIR 1.0, Flash Player 9

Dispatched by the Stage object when the mouse pointer moves out of the stage area.

The Event.MOUSE_LEAVE constant defines the value of the type property of a mouseLeave event object.

This event has the following properties:

PropertyValue
bubblesfalse
cancelablefalse; there is no default behavior to cancel.
currentTargetThe object that is actively processing the Event object with an event listener.
targetThe Stage object. The target is not always the object in the display list that registered the event listener. Use the currentTarget property to access the object in the display list that is currently processing the event.
resize Event  
Event Object Type: flash.events.Event
Event.type property = flash.events.Event.RESIZE

Language Version : ActionScript 3.0
Runtime Versions : AIR 1.0, Flash Player 9

Dispatched when the scaleMode property of the Stage object is set to StageScaleMode.NO_SCALE and the SWF file is resized.

The Event.RESIZE constant defines the value of the type property of a resize event object.

This event has the following properties:

PropertyValue
bubblesfalse
cancelablefalse; there is no default behavior to cancel.
currentTargetThe object that is actively processing the Event object with an event listener.
targetThe Stage object.
Examples How to use examples
StageExample.as

The following example uses the StageExample class to dispatch events whenever the stage is activated or resized. This is accomplished by performing the following steps:
  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);
        }
    }
}




 

Send me an e-mail when comments are added to this page | Comment Report

Current page: http://livedocs.adobe.com/livecycle/8.2/programLC/common/langref/flash/display/Stage.html