ActionScript 3.0 Language and Components Reference | All Packages | All Classes | Language Elements | Index | Appendixes | Conventions | Frames No Frames |
Stage

Package | flash.display
Class | public class Stage
Inheritance | Stage DisplayObjectContainer InteractiveObject DisplayObject EventDispatcher Object

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

The Stage class represents the main drawing area. The Stage represents the entire area where Flash® content is shown.

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

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

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

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

View the examples

See also

Core display classes
Setting Stage properties

Public Properties
Hide Inherited Public Properties
Show Inherited Public Properties

| Property | Defined By
--- | --- | ---
|  | accessibilityProperties : 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
|  | alpha : Number Indicates the alpha transparency value of the object specified. | DisplayObject
|  | blendMode : String A value from the BlendMode class that specifies which blend mode to use. | DisplayObject
|  | cacheAsBitmap : Boolean If set to true, Flash Player caches an internal bitmap representation of the display object. | DisplayObject
|  | constructor : Object A reference to the class object or constructor function for a given object instance. | Object
|  | contextMenu : ContextMenu 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
|  | doubleClickEnabled : Boolean Specifies whether the object receives doubleClick events. | InteractiveObject
|  | enableColorCorrection : Boolean Enables Flash Player to display color correction that matches the main (primary) monitor's International Color Consortium (ICC) color profile. | Stage
|  | filters : 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
|  | focusRect : 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
|  | loaderInfo : LoaderInfo [read-only] Returns a LoaderInfo object containing information about loading the file to which this display object belongs. | DisplayObject
|  | mask : 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
|  | mouseEnabled : Boolean Specifies whether this object receives mouse messages. | InteractiveObject
|  | mouseX : Number [read-only] Indicates the x coordinate of the mouse position, in pixels. | DisplayObject
|  | mouseY : Number [read-only] Indicates the y coordinate of the mouse position, in pixels. | DisplayObject
|  | name : String Indicates the instance name of the DisplayObject. | DisplayObject
|  | numChildren : int [read-only] Returns the number of children of this object. | Stage
|  | opaqueBackground : Object Specifies whether the display object is opaque with a certain background color. | DisplayObject
|  | parent : DisplayObjectContainer [read-only] Indicates the DisplayObjectContainer object that contains this display object. | DisplayObject
|  | prototype : 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 Flash Player uses. | Stage
|  | root : 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
|  | rotation : Number Indicates the rotation of the DisplayObject instance, in degrees, from its original orientation. | DisplayObject
|  | scale9Grid : 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
|  | scaleX : Number Indicates the horizontal scale (percentage) of the object as applied from the registration point. | DisplayObject
|  | scaleY : Number Indicates the vertical scale (percentage) of an object as applied from the registration point of the object. | DisplayObject
|  | scrollRect : 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
|  | stage : 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
|  | tabEnabled : Boolean Specifies whether this object is in the tab order. | InteractiveObject
|  | tabIndex : 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
|  | transform : Transform An object with properties pertaining to a display object's matrix, color transform, and pixel bounds. | DisplayObject
|  | visible : Boolean Whether or not the display object is visible. | DisplayObject
|  | width : Number Indicates the width of the display object, in pixels. | Stage
|  | x : Number Indicates the x coordinate of the DisplayObject instance relative to the local coordinates of the parent DisplayObjectContainer. | DisplayObject
|  | y : Number Indicates the y coordinate of the DisplayObject instance relative to the local coordinates of the parent DisplayObjectContainer. | DisplayObject

Public Methods
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined By
--- | --- | ---
|  | addChild(child:DisplayObject):DisplayObject Adds a child DisplayObject instance to this DisplayObjectContainer instance. | Stage
|  | addChildAt(child:DisplayObject, index:int):DisplayObject 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
|  | areInaccessibleObjectsUnderPoint(point:Point):Boolean 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
|  | contains(child:DisplayObject):Boolean Determines whether the specified display object is a child of the DisplayObjectContainer instance or the instance itself. | DisplayObjectContainer
|  | dispatchEvent(event:Event):Boolean Dispatches an event into the event flow. | Stage
|  | 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
|  | getChildAt(index:int):DisplayObject Returns the child display object instance that exists at the specified index. | DisplayObjectContainer
|  | getChildByName(name:String):DisplayObject Returns the child display object that exists with the specified name. | DisplayObjectContainer
|  | getChildIndex(child:DisplayObject):int Returns the index position of a child DisplayObject instance. | DisplayObjectContainer
|  | getObjectsUnderPoint(point:Point):Array Returns an array of objects that lie under the specified point and are children (or grandchildren, and so on) of this DisplayObjectContainer instance. | DisplayObjectContainer
|  | 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
|  | globalToLocal(point:Point):Point Converts the point object from the Stage (global) coordinates to the display object's (local) coordinates. | DisplayObject
|  | hasEventListener(type:String):Boolean Checks whether the EventDispatcher object has any listeners registered for a specific type of event. | Stage
|  | hasOwnProperty(name:String):Boolean Indicates whether an object has a specified property defined. | Object
|  | hitTestObject(obj:DisplayObject):Boolean Evaluates the display object to see if it overlaps or intersects with the obj display object. | DisplayObject
|  | 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
|  | invalidate():void 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
|  | isFocusInaccessible():Boolean Determines whether the Stage.focus property returns null for security reasons. | Stage
|  | isPrototypeOf(theClass:Object):Boolean Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter. | Object
|  | localToGlobal(point:Point):Point Converts the point object from the display object's (local) coordinates to the Stage (global) coordinates. | DisplayObject
|  | propertyIsEnumerable(name:String):Boolean Indicates whether the specified property exists and is enumerable. | Object
|  | removeChild(child:DisplayObject):DisplayObject Removes the specified child DisplayObject instance from the child list of the DisplayObjectContainer instance. | DisplayObjectContainer
|  | removeChildAt(index:int):DisplayObject Removes a child DisplayObject from the specified index position in the child list of the DisplayObjectContainer. | Stage
|  | removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void Removes a listener from the EventDispatcher object. | EventDispatcher
|  | setChildIndex(child:DisplayObject, index:int):void Changes the position of an existing child in the display object container. | Stage
|  | setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void Sets the availability of a dynamic property for loop operations. | Object
|  | swapChildren(child1:DisplayObject, child2:DisplayObject):void 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
|  | toString():String Returns the string representation of the specified object. | Object
|  | valueOf():Object Returns the primitive value of the specified object. | Object
|  | willTrigger(type:String):Boolean Checks whether an event listener is registered with this EventDispatcher object or any of its ancestors for the specified event type. | Stage

Events
Hide Inherited Events
Show Inherited Events

| Event | Summary | Defined By
--- | --- | --- | ---
|  | activate | Dispatched when Flash Player gains operating system focus and becomes active. | EventDispatcher
|  | added | Dispatched when a display object is added to the display list. | DisplayObject
|  | addedToStage | Dispatched 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
|  | clear | Dispatched when the user selects 'Clear' (or 'Delete') from the text context menu. | InteractiveObject
|  | click | Dispatched when a user presses and releases the main button of the user's pointing device over the same InteractiveObject. | InteractiveObject
|  | copy | Dispatched when the user activates the platform specific accelerator key combination for a copy operation or selects 'Copy' from the text context menu. | InteractiveObject
|  | cut | Dispatched when the user activates the platform specific accelerator key combination for a cut operation or selects 'Cut' from the text context menu. | InteractiveObject
|  | deactivate | Dispatched when Flash Player loses operating system focus and is becoming inactive. | EventDispatcher
|  | doubleClick | Dispatched 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
|  | enterFrame | Dispatched when the playhead is entering a new frame. | DisplayObject
|  | exitFrame | Dispatched when the playhead is exiting the current frame. | DisplayObject
|  | focusIn | Dispatched after a display object gains focus. | InteractiveObject
|  | focusOut | Dispatched after a display object loses focus. | InteractiveObject
|  | frameConstructed | Dispatched after the constructors of frame display objects have run but before frame scripts have run. | DisplayObject
|  | fullScreen | Dispatched by Flash Player when the Stage object enters, or leaves, full-screen mode. | Stage
|  | keyDown | Dispatched when the user presses a key. | InteractiveObject
|  | keyFocusChange | Dispatched when the user attempts to change focus by using keyboard navigation. | InteractiveObject
|  | keyUp | Dispatched when the user releases a key. | InteractiveObject
|  | mouseDown | Dispatched when a user presses the pointing device button over an InteractiveObject instance in the Flash Player window. | InteractiveObject
|  | mouseFocusChange | Dispatched when the user attempts to change focus by using a pointer device. | InteractiveObject
|  | mouseLeave | Dispatched by the Stage object when the mouse pointer moves out of the Flash Player window area. | Stage
|  | mouseMove | Dispatched when a user moves the pointing device while it is over an InteractiveObject. | InteractiveObject
|  | mouseOut | Dispatched when the user moves a pointing device away from an InteractiveObject instance. | InteractiveObject
|  | mouseOver | Dispatched when the user moves a pointing device over an InteractiveObject instance in the Flash Player window. | InteractiveObject
|  | mouseUp | Dispatched when a user releases the pointing device button over an InteractiveObject instance in the Flash Player window. | InteractiveObject
|  | mouseWheel | Dispatched when a mouse wheel is spun over an InteractiveObject instance in the Flash Player window. | InteractiveObject
|  | paste | Dispatched when the user activates the platform specific accelerator key combination for a paste operation or selects 'Paste' from the text context menu. | InteractiveObject
|  | removed | Dispatched when a display object is about to be removed from the display list. | DisplayObject
|  | removedFromStage | Dispatched 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
|  | render | Dispatched when the display list is about to be updated and rendered. | DisplayObject
|  | resize | Dispatched when the scaleMode property of the Stage object is set to StageScaleMode.NO_SCALE and the SWF file is resized. | Stage
|  | rollOut | Dispatched when the user moves a pointing device away from an InteractiveObject instance. | InteractiveObject
|  | rollOver | Dispatched when the user moves a pointing device over an InteractiveObject instance. | InteractiveObject
|  | selectAll | Dispatched when the user activates the platform specific accelerator key combination for a select all operation or selects 'Select All' from the text context menu. | InteractiveObject
|  | tabChildrenChange | Dispatched when the value of the object's tabChildren flag changes. | InteractiveObject
|  | tabEnabledChange | Dispatched when the object's tabEnabled flag changes. | InteractiveObject
|  | tabIndexChange | Dispatched when the value of the object's tabIndex property changes. | InteractiveObject

Property Detail

align | property

`align:String` [read-write]

Language Version : | ActionScript 3.0

Player Version : | 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:

Value | Vertical Alignment | Horizontal
--- | --- | ---
`StageAlign.TOP` | Top | Center
`StageAlign.BOTTOM` | Bottom | Center
`StageAlign.LEFT` | Center | Left
`StageAlign.RIGHT` | Center | Right
`StageAlign.TOP_LEFT` | Top | Left
`StageAlign.TOP_RIGHT` | Top | Right
`StageAlign.BOTTOM_LEFT` | Bottom | Left
`StageAlign.BOTTOM_RIGHT` | Bottom | Right

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

flash.display.StageAlign

displayState | property |

`displayState:String` [read-write]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9.0.28.0

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

- `StageDisplayState.FULL_SCREEN` Sets Flash Player to expand the stage over the user's entire screen.
- `StageDisplayState.NORMAL` Sets the player 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 Flash Player transitions to full-screen mode, the Stage `width` and `height` properties are updated, and Flash Player dispatches the `Stage.resize` event.

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

- 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 and Flex 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. While Flash Player is in full-screen mode, all keyboard input is disabled (except keyboard shortcuts that take the user out of full-screen mode). A Flash Player dialog box appears over the movie when users enter full-screen mode to inform the users they are in full-screen mode and that they can press the Escape key to end full-screen mode.
- Starting with Flash Player 9.0.115.0, full-screen works the same in windowless mode as it does in window mode. If you set the Window Mode (`wmode` in the HTML) to Opaque Windowless (`opaque`) or Transparent Windowless (`transparent`), full-screen can be initiated, but the full-screen window will always be opaque.

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

flash.display.StageDisplayState
Stage.scaleMode
flash.events.FullScreenEvent
flash.events.Event.RESIZE
Flash Player security
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.
            }
        }
    }

enableColorCorrection | property |

`enableColorCorrection:Boolean` [read-write]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

Enables Flash Player to display color correction that matches the main (primary) monitor's International Color Consortium (ICC) color profile. Color correction works only if the main monitor is assigned a valid ICC color profile, which specifies the device's particular color attributes.

Use the `flash.system.capabilities.hasColorCorrection` property to determine if color correction is available on the current system. 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 to 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 Flash Player performance. Flash Player's color correction is a document style color correction because all SWF movies are considered documents with implicit sRGB profiles. Use the `enableColorCorrection` property to tell Flash Player to correct colors as best as it can when displaying the SWF (document) to the display color space. Flash Player only compensates for differences between monitors, not for differences between input devices (camera/scanner/etc.).

Implementation
`flash10 function get enableColorCorrection():Boolean`
`flash10 function set enableColorCorrection(value:Boolean):void`

See also

flash.system.Capabilities.hasColorCorrection

focus | property |

`focus:InteractiveObject` [read-write]

Language Version : | ActionScript 3.0

Player Version : | 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.

frameRate | property |

`frameRate:Number` [read-write]

Language Version : | ActionScript 3.0

Player Version : | 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:` Flash Player 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.

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.

fullScreenHeight | property |

`fullScreenHeight:uint` [read-only]

Language Version : | ActionScript 3.0

Player Version : | 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

displayState
fullScreenSourceRect
fullScreenWidth
scaleMode
StageDisplayState
flash.events.Event.RESIZE
flash.events.FullScreenEvent
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;
    }

fullScreenSourceRect | property |

`fullScreenSourceRect:Rectangle` [read-write]

Language Version : | ActionScript 3.0

Player Version : | 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

flash.display.StageDisplayState
Stage.displayState
Stage.scaleMode
flash.events.FullScreenEvent
flash.events.Event.RESIZE
fl.video.FLVPlayback.enterFullScreenDisplayState()
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 version 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, 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 {

            }
        }
    }

fullScreenWidth | property |

`fullScreenWidth:uint` [read-only]

Language Version : | ActionScript 3.0

Player Version : | 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

displayState
fullScreenHeight
fullScreenSourceRect
scaleMode
StageDisplayState
flash.events.Event.RESIZE
flash.events.FullScreenEvent
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;
    }

height | property |

`height:Number` [read-write]

Language Version : | ActionScript 3.0

Player Version : | 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).

mouseChildren | property |

`mouseChildren:Boolean` [read-write]

Language Version : | ActionScript 3.0

Player Version : | 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.

numChildren | property |

`numChildren:int` [read-only]

Language Version : | ActionScript 3.0

Player Version : | 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.

quality | property |

`quality:String` [read-write]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

A value from the StageQuality class that specifies which rendering quality Flash Player uses. The following are valid values:

- `StageQuality.LOW`—Low rendering quality. Graphics are not anti-aliased, and bitmaps are not smoothed.
- `StageQuality.MEDIUM`—Medium rendering quality. Graphics are anti-aliased using a 2 x 2 pixel grid, but bitmaps are not smoothed. 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 bitmaps are smoothed if the movie is static. 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 and bitmaps are always smoothed.

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

flash.display.StageQuality

scaleMode | property |

`scaleMode:String` [read-write]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

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

- `StageScaleMode.EXACT_FIT`—The entire Flash 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 Flash 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 Flash 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 Flash 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.

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

flash.display.StageScaleMode

showDefaultContextMenu | property |

`showDefaultContextMenu:Boolean` [read-write]

Language Version : | ActionScript 3.0

Player Version : | 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.

stageFocusRect | property |

`stageFocusRect:Boolean` [read-write]

Language Version : | ActionScript 3.0

Player Version : | 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.

stageHeight | property |

`stageHeight:int` [read-write]

Language Version : | ActionScript 3.0

Player Version : | 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

flash.display.StageScaleMode

stageWidth | property |

`stageWidth:int` [read-write]

Language Version : | ActionScript 3.0

Player Version : | 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

flash.display.StageScaleMode

tabChildren | property |

`tabChildren:Boolean` [read-write]

Language Version : | ActionScript 3.0

Player Version : | 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.

textSnapshot | property |

`textSnapshot:TextSnapshot` [read-only]

Language Version : | ActionScript 3.0

Player Version : | 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.

width | property |

`width:Number` [read-write]

Language Version : | ActionScript 3.0

Player Version : | 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

Player Version : | 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.

See also

Adding display objects to the display list

addChildAt | () | method |

`override public function addChildAt(child:DisplayObject, index:int):DisplayObject`

Language Version : | ActionScript 3.0

Player Version : | 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:

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.

See also

Adding display objects to the display list

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

Player Version : | 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.

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`)`` — 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 the `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 garbge-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.

See also

Handling events for display objects

dispatchEvent | () | method |

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

Language Version : | ActionScript 3.0

Player Version : | 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

Player Version : | 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.

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

Player Version : | 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

flash.events.Event.RENDER

isFocusInaccessible | () | method |

`public function isFocusInaccessible():Boolean`

Language Version : | ActionScript 3.0

Player Version : | 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

| `Boolean` — `true` 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`

Language Version : | ActionScript 3.0

Player Version : | 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 is the process by which Flash Player 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

Player Version : | 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:

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

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

Player Version : | 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

Player Version : | 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.

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

Player Version : | Flash Player 9.0.28.0

Dispatched by Flash Player 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:

Property | Value
--- | ---
`fullScreen` | `true` if the display state is full screen or `false` if it is normal.
`bubbles` | `false`
`cancelable` | `false`; there is no default behavior to cancel.
`currentTarget` | The object that is actively processing the Event object with an event listener.
`target` | The Stage object.

mouseLeave | Event |

Event Object Type: `flash.events.Event`
Event.type property = `flash.events.Event.MOUSE_LEAVE`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

Dispatched by the Stage object when the mouse pointer moves out of the Flash Player window area.

Defines the value of the `type` property of a `mouseLeave` event object.

This event has the following properties:

Property | Value
--- | ---
`bubbles` | `false`
`cancelable` | `false`; there is no default behavior to cancel.
`currentTarget` | The object that is actively processing the Event object with an event listener.
`target` | The 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

Player Version : | Flash Player 9

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

Defines the value of the `type` property of a `resize` event object.

This event has the following properties:

Property | Value
--- | ---
`bubbles` | `false`
`cancelable` | `false`; there is no default behavior to cancel.
`currentTarget` | The object that is actively processing the Event object with an event listener.
`target` | The 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);
            }
        }
    }

Submit Feedback on LiveDocs
© 2004-2008 Adobe Systems Incorporated. All rights reserved.
Tue May 20 2008, 04:02 AM -07:00