flash.display

# Stage - AS3

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

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

The Stage class represents the main drawing area.

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

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

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

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

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

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

View the examples

More examples

Adding display objects to the display list
Traversing the display list
Controlling Stage scaling
Working with full-screen mode

Learn more

The event flow
Display programming
Basics of display programming
Core display classes
Working with display objects
Setting Stage properties
Handling events for display objects
Stage orientation

Related API Elements

flash.display.DisplayObject

Public Properties
Hide Inherited Public Properties
Show Inherited Public Properties

| Property | Defined By
--- | --- | ---
|  | accessibilityImplementation : AccessibilityImplementation The current accessibility implementation (AccessibilityImplementation) for this InteractiveObject instance. | InteractiveObject
|  | 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
|  | allowsFullScreen : Boolean [read-only] Specifies whether this stage allows the use of the full screen mode | Stage
|  | allowsFullScreenInteractive : Boolean [read-only] Specifies whether this stage allows the use of the full screen with text input mode | Stage
|  | alpha : Number Indicates the alpha transparency value of the object specified. | DisplayObject
|  | autoOrients : Boolean Specifies whether the stage automatically changes orientation when the device orientation changes. | Stage
|  | blendMode : String A value from the BlendMode class that specifies which blend mode to use. | DisplayObject
|  | blendShader : Shader [write-only] Sets a shader that is used for blending the foreground and background. | DisplayObject
|  | browserZoomFactor : Number [read-only] Specifies the browser zoom factor. | Stage
|  | cacheAsBitmap : Boolean If set to true, Flash runtimes cache an internal bitmap representation of the display object. | DisplayObject
|  | cacheAsBitmapMatrix : Matrix If non-null, this Matrix object defines how a display object is rendered when cacheAsBitmap is set to true. | DisplayObject
|  | color : uint The SWF background color. | Stage
|  | colorCorrection : String Controls Flash runtime color correction for displays. | Stage
|  | colorCorrectionSupport : String [read-only] Specifies whether the Flash runtime is running on an operating system that supports color correction and whether the color profile of the main (primary) monitor can be read and understood by the Flash runtime. | Stage
|  | constructor : * | Stage
|  | contentsScaleFactor : Number [read-only] Specifies the effective pixel scaling factor of the stage. | Stage
|  | contextMenu : NativeMenu Specifies the context menu associated with this object. | InteractiveObject
|  | deviceOrientation : String [read-only] The physical orientation of the device. | Stage
|  | 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
|  | 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 the Flash runtime 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 [override] 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
|  | metaData : Object Obtains the meta data object of the DisplayObject instance if meta data was stored alongside the the instance of this DisplayObject in the SWF file through a PlaceObject4 tag. | DisplayObject
|  | mouseChildren : Boolean [override] Determines whether or not the children of the object are mouse, or user input device, enabled. | Stage
|  | mouseEnabled : Boolean Specifies whether this object receives mouse, or other user input, messages. | InteractiveObject
|  | mouseLock : Boolean Set to true to enable mouse locking. | Stage
|  | mouseX : Number [read-only] Indicates the x coordinate of the mouse or user input device position, in pixels. | DisplayObject
|  | mouseY : Number [read-only] Indicates the y coordinate of the mouse or user input device position, in pixels. | DisplayObject
|  | name : String Indicates the instance name of the DisplayObject. | DisplayObject
|  | nativeWindow : NativeWindow [read-only] A reference to the NativeWindow object containing this Stage. | Stage
|  | needsSoftKeyboard : Boolean Specifies whether a virtual keyboard (an on-screen, software keyboard) should display when this InteractiveObject instance receives focus. | InteractiveObject
|  | numChildren : int [override] [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
|  | orientation : String [read-only] The current orientation of the stage. | Stage
|  | parent : DisplayObjectContainer [read-only] Indicates the DisplayObjectContainer object that contains this display object. | DisplayObject
|  | quality : String A value from the StageQuality class that specifies which rendering quality is used. | 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
|  | rotationX : Number Indicates the x-axis rotation of the DisplayObject instance, in degrees, from its original orientation relative to the 3D parent container. | DisplayObject
|  | rotationY : Number Indicates the y-axis rotation of the DisplayObject instance, in degrees, from its original orientation relative to the 3D parent container. | DisplayObject
|  | rotationZ : Number Indicates the z-axis rotation of the DisplayObject instance, in degrees, from its original orientation relative to the 3D parent container. | 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
|  | scaleZ : Number Indicates the depth 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 runtime context menu. | Stage
|  | softKeyboard : String Controls the appearance of the soft keyboard. | InteractiveObject
|  | softKeyboardInputAreaOfInterest : Rectangle Defines the area that should remain on-screen when a soft keyboard is displayed (not available on iOS). | InteractiveObject
|  | softKeyboardRect : Rectangle [read-only] A Rectangle specifying the area of the stage that is currently covered by a soft keyboard. | Stage
|  | stage : Stage [read-only] The Stage of the display object. | DisplayObject
|  | stage3Ds : Vector.<Stage3D> [read-only] A list of Stage3D objects available for displaying 3-dimensional content. | Stage
|  | 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
|  | stageVideos : Vector.<StageVideo> [read-only] A list of StageVideo objects available for playing external videos. | Stage
|  | stageWidth : int Specifies the current width, in pixels, of the Stage. | Stage
|  | supportedOrientations : Vector.<String> [read-only] The orientations supported by the current device. | Stage
|  | supportsOrientationChange : Boolean [static] [read-only] Whether the application supports changes in the stage orientation (and device rotation). | Stage
|  | tabChildren : Boolean [override] 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 : flash.text:TextSnapshot [override] [read-only] Returns a TextSnapshot object for this DisplayObjectContainer instance. | Stage
|  | transform : flash.geom: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 [override] Indicates the width of the display object, in pixels. | Stage
|  | wmodeGPU : Boolean [read-only] Indicates whether GPU compositing is available and in use. | 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
|  | z : Number Indicates the z coordinate position along the z-axis of the DisplayObject instance relative to the 3D parent container. | DisplayObject

Public Methods
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined By
--- | --- | ---
|  | addChild(child:DisplayObject):DisplayObject [override] Adds a child DisplayObject instance to this DisplayObjectContainer instance. | Stage
|  | addChildAt(child:DisplayObject, index:int):DisplayObject [override] 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 [override] 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
|  | 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
|  | 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 [override] 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
|  | globalToLocal3D(point:Point):Vector3D Converts a two-dimensional point from the Stage (global) coordinates to a three-dimensional display object's (local) coordinates. | DisplayObject
|  | hasEventListener(type:String):Boolean [override] 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 bounding box of the display object to see if it overlaps or intersects with the bounding box of 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 runtimes to alert display objects on the next opportunity it has to render the display list (for example, when the playhead advances to a new frame). | 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
|  | local3DToGlobal(point3d:Vector3D):Point Converts a three-dimensional point of the three-dimensional display object's (local) coordinates to a two-dimensional point in the Stage (global) coordinates. | DisplayObject
|  | 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 [override] Removes a child DisplayObject from the specified index position in the child list of the DisplayObjectContainer. | Stage
|  | removeChildren(beginIndex:int = 0, endIndex:int = 0x7fffffff):void Removes all child DisplayObject instances from the child list of the DisplayObjectContainer instance. | DisplayObjectContainer
|  | removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void Removes a listener from the EventDispatcher object. | EventDispatcher
|  | requestSoftKeyboard():Boolean Raises a virtual keyboard. | InteractiveObject
|  | setAspectRatio(newAspectRatio:String):void Sets the stage to an orientation with the specified aspect ratio. | Stage
|  | setChildIndex(child:DisplayObject, index:int):void [override] Changes the position of an existing child in the display object container. | Stage
|  | setOrientation(newOrientation:String):void Sets the stage to the specified orientation. | Stage
|  | setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void Sets the availability of a dynamic property for loop operations. | Object
|  | stopAllMovieClips():void Recursively stops the timeline execution of all MovieClips rooted at this object. | DisplayObjectContainer
|  | 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 [override] Swaps the z-order (front-to-back order) of the child objects at the two specified index positions in the child list. | Stage
|  | toLocaleString():String Returns the string representation of this object, formatted according to locale-specific conventions. | Object
|  | 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 [override] Checks whether an event listener is registered with this EventDispatcher object or any of its ancestors for the specified event type. | Stage

Events
Click for more information on events
Hide Inherited Events
Show Inherited Events

| Event | Summary | Defined By
--- | --- | --- | ---
|  | activate | [broadcast event] Dispatched when the Flash Player or AIR application 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
|  | browserZoomChange | Dispatched when the browserZoomFactor property of the Stage object is changed. | Stage
|  | 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
|  | contextMenu | Dispatched when a user gesture triggers the context menu associated with this interactive object in an AIR application. | 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 | [broadcast event] Dispatched when the Flash Player or AIR application operating loses 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 | [broadcast event] Dispatched when the playhead is entering a new frame. | DisplayObject
|  | exitFrame | [broadcast event] 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 | [broadcast event] Dispatched after the constructors of frame display objects have run but before frame scripts have run. | DisplayObject
|  | fullScreen | Dispatched when the Stage object enters, or leaves, full-screen mode. | Stage
|  | gestureDirectionalTap | Dispatched when the user creates a point of contact along the edge of the touch surface with an InteractiveObject instance, (such as tapping along the edge of the touch surface on Siri Remote for Apple TV) Some devices might also interpret this contact as a combination of several touch events, as well. | InteractiveObject
|  | gestureLongPress | Dispatched when the user presses two points of contact over the same InteractiveObject instance on a touch-enabled device (such as presses and releases two fingers over a display object on a mobile phone or tablet with a touch screen). | InteractiveObject
|  | gesturePan | Dispatched when the user moves a point of contact over the InteractiveObject instance on a touch-enabled device (such as moving a finger from left to right over a display object on a mobile phone or tablet with a touch screen). | InteractiveObject
|  | gestureRotate | Dispatched when the user performs a rotation gesture at a point of contact with an InteractiveObject instance (such as touching two fingers and rotating them over a display object on a mobile phone or tablet with a touch screen). | InteractiveObject
|  | gestureSwipe | Dispatched when the user performs a swipe gesture at a point of contact with an InteractiveObject instance (such as touching three fingers to a screen and then moving them in parallel over a display object on a mobile phone or tablet with a touch screen). | InteractiveObject
|  | gestureTap | Dispatched when the user creates a point of contact with an InteractiveObject instance, then taps on a touch-enabled device (such as placing several fingers over a display object to open a menu and then taps one finger to select a menu item on a mobile phone or tablet with a touch screen). | InteractiveObject
|  | gestureZoom | Dispatched when the user performs a zoom gesture at a point of contact with an InteractiveObject instance (such as touching two fingers to a screen and then quickly spreading the fingers apart over a display object on a mobile phone or tablet with a touch screen). | InteractiveObject
|  | imeStartComposition | This event is dispatched to any client app that supports inline input with an IME | InteractiveObject
|  | 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
|  | middleClick | Dispatched when a user presses and releases the middle button of the user's pointing device over the same InteractiveObject. | InteractiveObject
|  | middleMouseDown | Dispatched when a user presses the middle pointing device button over an InteractiveObject instance. | InteractiveObject
|  | middleMouseUp | Dispatched when a user releases the pointing device button over an InteractiveObject instance. | InteractiveObject
|  | mouseDown | Dispatched when a user presses the pointing device button over an InteractiveObject instance. | InteractiveObject
|  | mouseFocusChange | Dispatched when the user attempts to change focus by using a pointer device. | InteractiveObject
|  | mouseLeave | Dispatched by the Stage object when the pointer moves out of the stage 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. | InteractiveObject
|  | mouseUp | Dispatched when a user releases the pointing device button over an InteractiveObject instance. | InteractiveObject
|  | mouseWheel | Dispatched when a mouse wheel is spun over an InteractiveObject instance. | InteractiveObject
|  | nativeDragComplete | Dispatched by the drag initiator InteractiveObject when the user releases the drag gesture. | InteractiveObject
|  | nativeDragDrop | Dispatched 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
|  | nativeDragEnter | Dispatched by an InteractiveObject when a drag gesture enters its boundary. | InteractiveObject
|  | nativeDragExit | Dispatched by an InteractiveObject when a drag gesture leaves its boundary. | InteractiveObject
|  | nativeDragOver | Dispatched by an InteractiveObject continually while a drag gesture remains within its boundary. | InteractiveObject
|  | nativeDragStart | Dispatched at the beginning of a drag operation by the InteractiveObject that is specified as the drag initiator in the DragManager.doDrag() call. | InteractiveObject
|  | nativeDragUpdate | Dispatched during a drag operation by the InteractiveObject that is specified as the drag initiator in the DragManager.doDrag() call. | InteractiveObject
|  | orientationChange | Dispatched by the Stage object when the stage orientation changes. | Stage
|  | orientationChanging | Dispatched by the Stage object when the stage orientation begins changing. | Stage
|  | 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
|  | proximityBegin | Dispatched when the user lowers an active stylus past the proximity detection threshold of the screen. | InteractiveObject
|  | proximityEnd | Dispatched when the user lifts an active stylus above the proximity detection threshold of the screen. | InteractiveObject
|  | proximityMove | Dispatched when the user moves an active stylus over the screen while remaining within the proximity detection threshold. | InteractiveObject
|  | proximityOut | Dispatched when the user moves an active stylus away from this InteractiveObject while remaining within the proximity detection threshold of the screen. | InteractiveObject
|  | proximityOver | Dispatched when the user moves an active stylus directly above this InteractiveObject while remaining within the proximity detection threshold of the screen. | InteractiveObject
|  | proximityRollOut | Dispatched when the user moves an active stylus away from this InteractiveObject and any of its children while remaining within the proximity detection threshold of the screen. | InteractiveObject
|  | proximityRollOver | Dispatched when the user moves an active stylus over this InteractiveObject from outside the object's tree of descendents in the display list (while remaining within the proximity detection threshold of the screen). | InteractiveObject
|  | releaseOutside | Dispatched when a user releases the button on the pointing device after the user first pressed the button over an InteractiveObject instance and then moved the pointing device off of the InteractiveObject instance. | 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 | [broadcast event] 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
|  | rightClick | Dispatched when a user presses and releases the right button of the user's pointing device over the same InteractiveObject. | InteractiveObject
|  | rightMouseDown | Dispatched when a user presses the pointing device button over an InteractiveObject instance. | InteractiveObject
|  | rightMouseUp | Dispatched when a user releases the pointing device button over an InteractiveObject instance. | InteractiveObject
|  | 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
|  | softKeyboardActivate | Dispatched immediately after the soft keyboard is raised. | InteractiveObject
|  | softKeyboardActivating | Dispatched immediately before the soft keyboard is raised. | InteractiveObject
|  | softKeyboardDeactivate | Dispatched immediately after the soft keyboard is lowered. | InteractiveObject
|  | stageVideoAvailability | Dispatched by the Stage object when the state of the stageVideos property changes. | Stage
|  | 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
|  | textInput | Dispatched when a user enters one or more characters of text. | InteractiveObject
|  | touchBegin | Dispatched when the user first contacts a touch-enabled device (such as touches a finger to a mobile phone or tablet with a touch screen). | InteractiveObject
|  | touchEnd | Dispatched when the user removes contact with a touch-enabled device (such as lifts a finger off a mobile phone or tablet with a touch screen). | InteractiveObject
|  | touchMove | Dispatched when the user touches the device, and is continuously dispatched until the point of contact is removed. | InteractiveObject
|  | touchOut | Dispatched when the user moves the point of contact away from InteractiveObject instance on a touch-enabled device (such as drags a finger from one display object to another on a mobile phone or tablet with a touch screen). | InteractiveObject
|  | touchOver | Dispatched when the user moves the point of contact over an InteractiveObject instance on a touch-enabled device (such as drags a finger from a point outside a display object to a point over a display object on a mobile phone or tablet with a touch screen). | InteractiveObject
|  | touchRollOut | Dispatched when the user moves the point of contact away from an InteractiveObject instance on a touch-enabled device (such as drags a finger from over a display object to a point outside the display object on a mobile phone or tablet with a touch screen). | InteractiveObject
|  | touchRollOver | Dispatched when the user moves the point of contact over an InteractiveObject instance on a touch-enabled device (such as drags a finger from a point outside a display object to a point over a display object on a mobile phone or tablet with a touch screen). | InteractiveObject
|  | touchTap | Dispatched when the user lifts the point of contact over the same InteractiveObject instance on which the contact was initiated on a touch-enabled device (such as presses and releases a finger from a single point over a display object on a mobile phone or tablet with a touch screen). | InteractiveObject

Property Detail

### align

property

`align:String`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

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 the ActionScript 3.0 Developer's Guide.

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

Related API Elements

flash.display.StageAlign

### allowsFullScreen

property

`allowsFullScreen:Boolean` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 10.2

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

Implementation
`public function get allowsFullScreen():Boolean`

### allowsFullScreenInteractive

property

`allowsFullScreenInteractive:Boolean` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 11.3, AIR 1.0

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

Implementation
`public function get allowsFullScreenInteractive():Boolean`

### autoOrients

property

`autoOrients:Boolean`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2

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

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

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

Implementation
`public function get autoOrients():Boolean`
`public function set autoOrients(value:Boolean):void`

Learn more

Automatic orientation

Related API Elements

deviceOrientation
supportsOrientationChange

### browserZoomFactor

property

`browserZoomFactor:Number` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 15

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

Implementation
`public function get browserZoomFactor():Number`

### color

property

`color:uint`

Runtime Versions: | Flash Player 10.2, AIR 2.5

The SWF background color.

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

Implementation
`public function get color():uint`
`public function set color(value:uint):void`

### colorCorrection

property

`colorCorrection:String`

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 10, AIR 1.5

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

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

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

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

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

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

Implementation
`public function get colorCorrection():String`
`public function set colorCorrection(value:String):void`

Related API Elements

flash.display.ColorCorrection
colorCorrectionSupport
Example ( How to use this example )
The following example shows an event handler that toggles color correction in the current SWF file and populates a text field with the current state of color correction. If the `Stage.colorCorrection` value is not a value from the ColorCorrection class, then the handler reports an error.
Copy

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

### colorCorrectionSupport

property

`colorCorrectionSupport:String` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 10, AIR 1.5

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

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

- `"unsupported"`: Color correction is not available.
- `"defaultOn"`: Always performs color correction.
- `"defaultOff"`: Never performs color correction.

Implementation
`public function get colorCorrectionSupport():String`

Related API Elements

flash.display.ColorCorrectionSupport
colorCorrection
Example ( How to use this example )
The following example shows an event handler that populates a text field with the current environment's ability to support color correction or not. First, it checks the value of `stage.colorCorrectionSupport` to see if it is `DEFAULT_ON` or `DEFAULT_OFF`, values from the ColorCorrectionSupport class. If the property is either value, then the text field displays the current value. Otherwise, if the value is neither `DEFAULT_ON` nor `DEFAULT_OFF`, the text field displays "unsupported".
Copy

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

### constructor

property

`constructor:*`

Implementation
`public function get constructor():*`
`public function set constructor(value:any):void`

### contentsScaleFactor

property

`contentsScaleFactor:Number` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 11.5

Specifies the effective pixel scaling factor of the stage. This value is 1 on standard screens and HiDPI (Retina display) screens. When the stage is rendered on HiDPI screens the pixel resolution is doubled; even if the stage scaling mode is set to StageScaleMode.NO_SCALE. Stage.stageWidth and Stage.stageHeight continue to be reported in classic pixel units.

Implementation
`public function get contentsScaleFactor():Number`

### deviceOrientation

property

`deviceOrientation:String` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2

The physical orientation of the device.

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

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

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

Implementation
`public function get deviceOrientation():String`

Learn more

Getting the current Stage orientation and aspect ratio

Related API Elements

autoOrients
StageOrientation

### displayState

property

`displayState:String`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9.0.28.0, Flash Lite 4

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

- `StageDisplayState.FULL_SCREEN` Sets AIR application or content in Flash Player to expand the stage over the user's entire screen. Keyboard input is disabled, with the exception of a limited set of non-printing keys.
- `StageDisplayState.FULL_SCREEN_INTERACTIVE` Sets the application to expand the stage over the user's entire screen, with keyboard input allowed. (Available in AIR and Flash Player, beginning with Flash Player 11.3.)
- `StageDisplayState.NORMAL` Sets the stage back to the standard stage display mode.

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

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

- To enable full-screen mode, add the `allowFullScreen` parameter to the `object` and `embed` tags in the HTML page that includes the SWF file, with `allowFullScreen` set to `"true"`, as shown in the following example:
  Copy

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

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

  Copy

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

- Full-screen mode is initiated in response to a mouse click or key press by the user; the movie cannot change `Stage.displayState` without user input. Flash runtimes restrict keyboard input in full-screen mode. Acceptable keys include keyboard shortcuts that terminate full-screen mode and non-printing keys such as arrows, space, Shift, and Tab keys. (Use full-screen interactive mode to support input from additional keys.) Keyboard shortcuts that terminate full-screen mode are: Escape (Windows, Linux, and Mac), Control+W (Windows), Command+W (Mac), and Alt+F4.
- Starting with Flash Player 9.0.115.0, full-screen works the same in windowless mode as it does in window mode. If you set the Window Mode (`wmode` in the HTML) to Opaque Windowless (`opaque`) or Transparent Windowless (`transparent`), full-screen can be initiated, but the full-screen window will always be opaque.
- To enable full-screen interactive mode, which supports keyboard interactivity, add the `allowFullScreenInteractive` parameter to the `object` and `embed` tags in the HTML page that includes the SWF file, with `allowFullScreenInteractive` set to `"true"`, as shown in the following example:
  Copy

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

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

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

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

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

On Linux, setting `displayState` to `StageDisplayState.FULL_SCREEN` or `StageDisplayState.FULL_SCREEN_INTERACTIVE` is an asynchronous operation.

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 the ActionScript 3.0 Developer's Guide. 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.

More examples

Working with full-screen mode

Related API Elements

flash.display.StageDisplayState
Stage.scaleMode
flash.events.FullScreenEvent
flash.events.Event.RESIZE
Example ( How to use this 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.

Copy

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

### focus

property

`focus:InteractiveObject`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

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.

Example ( How to use this example )
The following sets the initial focus to the text field `myTF` so the user can start typing without having to click anything. If you test this code within the authoring tool interface, you can only have access to a few keys because the host (browser or tool) interprets most key presses first. To see this example work as intended, compile it and run the SWF file.
Copy

    var myTF:TextField = new TextField();
    myTF.border =true;
    myTF.type = TextFieldType.INPUT;

    addChild(myTF);
    stage.focus= myTF;

### frameRate

property

`frameRate:Number`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

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 the ActionScript 3.0 Developer's Guide.

### fullScreenHeight

property

`fullScreenHeight:uint` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9.0.115.0, Flash Lite 4

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`

Related API Elements

displayState
fullScreenSourceRect
fullScreenWidth
scaleMode
StageDisplayState
flash.events.Event.RESIZE
flash.events.FullScreenEvent
Example ( How to use this 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.

Copy

    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`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9.0.115.0, Flash Lite 4

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

When this property is set to a valid rectangle and the `displayState` property is set to full-screen mode, the Flash runtime scales the specified area. The actual Stage size in pixels within ActionScript does not change. The Flash runtime enforces a minimum limit for the size of the rectangle to accommodate the standard "Press Esc to exit full-screen mode" message. This limit is usually around 260 by 30 pixels but can vary on platform and Flash runtime version.

This property can only be set when the Flash runtime is not in full-screen mode. To use this property correctly, set this property first, then set the `displayState` property to full-screen mode, as shown in the code examples. Note: In Flash Player 15 and later, this property can be set even when the Flash runtime is in full-screen mode.

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

Copy

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

Copy

         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`

Related API Elements

flash.display.StageDisplayState
Stage.displayState
Stage.scaleMode
flash.events.FullScreenEvent
flash.events.Event.RESIZE
Example ( How to use this 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:
Copy

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

Copy

    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

Runtime Versions: | AIR 1.0, Flash Player 9.0.115.0, Flash Lite 4

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`

Related API Elements

displayState
fullScreenHeight
fullScreenSourceRect
scaleMode
StageDisplayState
flash.events.Event.RESIZE
flash.events.FullScreenEvent
Example ( How to use this 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.

Copy

    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`[override]

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

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:

Copy

        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
`override public function get height():Number`
`override 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 the ActionScript 3.0 Developer's Guide.
| `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`[override]

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

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

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

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

Implementation
`override public function get mouseChildren():Boolean`
`override 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 the ActionScript 3.0 Developer's Guide.

### mouseLock

property

`mouseLock:Boolean`

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 11.2, AIR 3.2

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

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

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

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

Events associated with mouse movement, such as the `mouseMove` event, use the MouseEvent class to represent the event object. When mouse locking is disabled, use the `MouseEvent.localX` and `MouseEvent.localY` properties to determine the location of the mouse. When mouse locking is enabled, use the `MouseEvent.movementX` and `MouseEvent.movementY` properties to determine the location of the mouse. The `movementX` and `movementY` properties contain changes in the position of the mouse since the last event, instead of absolute coordinates of the mouse location.

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

Implementation
`public function get mouseLock():Boolean`
`public function set mouseLock(value:Boolean):void`

Related API Elements

flash.events.MouseEvent.movementX
flash.events.MouseEvent.movementY

### nativeWindow

property

`nativeWindow:NativeWindow` [read-only]

Runtime Versions: | AIR 1.0, Flash Lite 4

A reference to the NativeWindow object containing this Stage.

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

Implementation
`public function get nativeWindow():NativeWindow`

### numChildren

property

`numChildren:int` [read-only] [override]

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

Returns the number of children of this object.

Implementation
`override 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 the ActionScript 3.0 Developer's Guide.

### orientation

property

`orientation:String` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2

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

StageOrientation constant | Stage orientation
--- | ---
`StageOrientation.DEFAULT` | The screen is in the default orientation (right-side up).
`StageOrientation.ROTATED_RIGHT` | The screen is rotated right.
`StageOrientation.ROTATED_LEFT` | The screen is rotated left.
`StageOrientation.UPSIDE_DOWN` | The screen is rotated upside down.
`StageOrientation.UNKNOWN` | The application has not yet determined the initial orientation of the screen. You can add an event listener for the `orientationChange` event

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

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

Implementation
`public function get orientation():String`

Learn more

Getting the current Stage orientation and aspect ratio

Related API Elements

StageOrientation
autoOrients
deviceOrientation
supportsOrientationChange

### quality

property

`quality:String`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

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

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

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

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

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

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

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 the ActionScript 3.0 Developer's Guide.

Related API Elements

flash.display.StageQuality
flash.display.Bitmap.smoothing

### scaleMode

property

`scaleMode:String`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

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

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

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 the ActionScript 3.0 Developer's Guide.

More examples

Controlling Stage scaling

Related API Elements

flash.display.StageScaleMode

### showDefaultContextMenu

property

`showDefaultContextMenu:Boolean`

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 runtime context menu.

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

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 the ActionScript 3.0 Developer's Guide.

### softKeyboardRect

property

`softKeyboardRect:Rectangle` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2.6, Flash Player 10.2

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

Implementation
`public function get softKeyboardRect():Rectangle`

Related API Elements

flash.events.SoftKeyboardEvent
flash.geom.Rectangle

### stage3Ds

property

`stage3Ds:Vector.<Stage3D>` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 11, AIR 3

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

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

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

Implementation
`public function get stage3Ds():Vector.<Stage3D>`

Related API Elements

Stage3D

### stageFocusRect

property

`stageFocusRect:Boolean`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

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 the ActionScript 3.0 Developer's Guide.

### stageHeight

property

`stageHeight:int`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

The current height, in pixels, of the Stage.

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

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

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

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 the ActionScript 3.0 Developer's Guide.

Related API Elements

flash.display.StageScaleMode

### stageVideos

property

`stageVideos:Vector.<StageVideo>` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2.5, Flash Player 10.2

A list of StageVideo objects available for playing external videos.

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

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

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

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

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

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

Implementation
`public function get stageVideos():Vector.<StageVideo>`

Related API Elements

flash.media.StageVideo
flash.events.StageVideoEvent
Example ( How to use this example )
The following code illustrates how to get a StageVideo object:
Copy

    var stageVideo:StageVideo;

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

### stageWidth

property

`stageWidth:int`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

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

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

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

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

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 the ActionScript 3.0 Developer's Guide.

Related API Elements

flash.display.StageScaleMode

### supportedOrientations

property

`supportedOrientations:Vector.<String>` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2.6

The orientations supported by the current device.

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

The possible orientations include:

StageOrientation constant | Stage orientation
--- | ---
`StageOrientation.DEFAULT` | Set the stage orientation to the default orientation (right-side up).
`StageOrientation.ROTATED_RIGHT` | Set the stage orientation to be rotated right.
`StageOrientation.ROTATED_LEFT` | Set the stage orientation to be rotated left.
`StageOrientation.UPSIDE_DOWN` | Set the stage orientation to be rotated upside down.

Implementation
`public function get supportedOrientations():Vector.<String>`

Related API Elements

StageOrientation
autoOrients
setOrientation()
orientation

### supportsOrientationChange

property

`supportsOrientationChange:Boolean` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2

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

Implementation
`public static function get supportsOrientationChange():Boolean`

Related API Elements

autoOrients
deviceOrientation
supportsOrientationChange

### tabChildren

property

`tabChildren:Boolean`[override]

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

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

Implementation
`override public function get tabChildren():Boolean`
`override 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 the ActionScript 3.0 Developer's Guide.

### textSnapshot

property

`textSnapshot:flash.text:TextSnapshot` [read-only] [override]

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9

Returns a TextSnapshot object for this DisplayObjectContainer instance.

Implementation
`override public function get textSnapshot():flash.text: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`[override]

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

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:

Copy

        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
`override public function get width():Number`
`override 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 the ActionScript 3.0 Developer's Guide.
| `IllegalOperationError` — It is always illegal to set the `width` property of a Stage object, even if you are the Stage owner.

### wmodeGPU

property

`wmodeGPU:Boolean` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 10.0.32, AIR 1.5.2, Flash Lite 4

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

- GPU compositing has been requested.
- GPU compositing is available.
- GPU compositing is in use.

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

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

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

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

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

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

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

Implementation
`public function get wmodeGPU():Boolean`

Related API Elements

DisplayObject exitFrame event
Example ( How to use this example )
The following example examines the `wmodeGPU` property after the display object mySprite is rendered, so you can get an accurate value.
Copy

    mySprite.addEventListener(EXIT_FRAME, exithandler):

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

Method Detail

### addChild

()
method

`override public function addChild(child:DisplayObject):DisplayObject`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

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

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

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

Parameters

| `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 the ActionScript 3.0 Developer's Guide.

More examples

Adding display objects to the display list

Learn more

Working with display objects

### addChildAt

()
method

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

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

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 the ActionScript 3.0 Developer's Guide.

More examples

Adding display objects to the display list

Learn more

Working with display objects

### 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, Flash Lite 4

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

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

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

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

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

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

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

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

Parameters

| `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: Copy
    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 `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 the ActionScript 3.0 Developer's Guide.

Learn more

Working with display objects
Handling events for display objects

### 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 receiving focus. The `direction` property of the FocusEvent object will report the setting of the `direction` parameter.

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

Parameters

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

Related API Elements

flash.display.Stage.focus
flash.display.FocusDirection
flash.events.FocusEvent

### dispatchEvent

()
method

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

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

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 the ActionScript 3.0 Developer's Guide.

### hasEventListener

()
method

`override public function hasEventListener(type:String):Boolean`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

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 the ActionScript 3.0 Developer's Guide.

### invalidate

()
method

`public function invalidate():void`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

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

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

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

Related API Elements

flash.events.Event.RENDER

### isFocusInaccessible

()
method

`public function isFocusInaccessible():Boolean`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

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`

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

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 the ActionScript 3.0 Developer's Guide.

### setAspectRatio

()
method

`public function setAspectRatio(newAspectRatio:String):void`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2

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

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

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

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

Parameters

| `newAspectRatio:String` — The type code for the desired aspect ratio (`StageAspectRatio.PORTRAIT`, `StageAspectRatio.LANDSCAPE`, or `StageAspectRatio.ANY`).

Throws

| `ArgumentError` — The value passed as the `newAspectRatio` parameter is not valid. The value must match one of the constants defined in the StageAspectRatio class.

Related API Elements

StageAspectRatio
supportsOrientationChange

### setChildIndex

()
method

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

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

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:

Copy

    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 the ActionScript 3.0 Developer's Guide.

### setOrientation

()
method

`public function setOrientation(newOrientation:String):void`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2

Sets the stage to the specified orientation.

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

StageOrientation constant | Stage orientation
--- | ---
`StageOrientation.DEFAULT` | Set the stage orientation to the default orientation (right-side up).
`StageOrientation.ROTATED_RIGHT` | Set the stage orientation to be rotated right.
`StageOrientation.ROTATED_LEFT` | Set the stage orientation to be rotated left.
`StageOrientation.UPSIDE_DOWN` | Set the stage orientation to be rotated upside down.

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

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

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

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

Note: The `setOrientation()` method does not cause an `orientationChanging` event to be dispatched.

Parameters

| `newOrientation:String` — The new orientation of the stage.

Events

| `orientationChange:`StageOrientationEvent`` — The stage has resized as a result of the call to the `setOrientation()` method.

Throws

| `ArgumentError` — The value passed as the `newOrientation` parameter is not valid. The value must match one of the constants defined in the StageOriention class, except for the `StageOrientation.UNKNOWN` constant.

Related API Elements

autoOrients
supportsOrientationChange
StageOrientationEvent
StageOrientation

### swapChildrenAt

()
method

`override public function swapChildrenAt(index1:int, index2:int):void`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

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 the ActionScript 3.0 Developer's Guide.

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

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 the ActionScript 3.0 Developer's Guide.

Event Detail

### browserZoomChange

Event

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

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 15

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

The `Event.BROWSER_ZOOM_CHANGE` constant defines the value of the `type` property of an `browserZoomChange` 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 instance.

### fullScreen

Event

Event Object Type: `flash.events.FullScreenEvent`
property FullScreenEvent.type = `flash.events.FullScreenEvent.FULL_SCREEN`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9.0.28.0, Flash Lite 4

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:

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`
property Event.type = `flash.events.Event.MOUSE_LEAVE`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

Dispatched by the Stage object when the pointer moves out of the stage area. If the mouse button is pressed, the event is not dispatched.

The `Event.MOUSE_LEAVE` constant 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.

### orientationChange

Event

Event Object Type: `flash.events.StageOrientationEvent`
property StageOrientationEvent.type = `flash.events.StageOrientationEvent.ORIENTATION_CHANGE`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2.0

Dispatched by the Stage object when the stage orientation changes.

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

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

The `ORIENTATION_CHANGE` constant defines the value of the `type` property of a `orientationChange` event object. This event has the following properties:

Properties | Values
--- | ---
`afterOrientation` | The new orientation of the stage.
`beforeOrientation` | The old orientation of the stage.
`target` | The Stage object that dispatched the orientation change.
`bubbles` | `true`
`currentTarget` | Indicates the object that is actively processing the Event object with an event listener.
`cancelable` | `false`; it is too late to cancel the change.

Learn more

Automatic orientation

### orientationChanging

Event

Event Object Type: `flash.events.StageOrientationEvent`
property StageOrientationEvent.type = `flash.events.StageOrientationEvent.ORIENTATION_CHANGING`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2.0

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

Important: orientationChanging events are not dispatched on Android devices.

Notes:

- If the `autoOrients` property is `false`, then the stage orientation does not change when a device is rotated. Thus, StageOrientationEvents are only dispatched for device rotation when `autoOrients` is `true`.
- When you set the orientation programatically with the `setOrientation()` method, the `orientationChanging` event is not dispatched.

The `ORIENTATION_CHANGING` constant defines the value of the `type` property of a `orientationChanging` event object.

Important: ORIENTATION_CHANGING events are not dispatched on Android devices.

This event has the following properties:

Properties | Values
--- | ---
`afterOrientation` | The new orientation of the stage.
`beforeOrientation` | The old orientation of the stage.
`target` | The Stage object that dispatched the orientation change.
`bubbles` | `true`
`currentTarget` | Indicates the object that is actively processing the Event object with an event listener.
`cancelable` | `true`.

Learn more

Automatic orientation

### resize

Event

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

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

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

The `Event.RESIZE` constant 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.

### stageVideoAvailability

Event

Event Object Type: `flash.events.StageVideoAvailabilityEvent`
property StageVideoAvailabilityEvent.type = `flash.events.StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 10.2

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

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

This event has the following properties:

Property | Value
--- | ---
`availability` | The status reported by the event.
`bubbles` | `false`
`cancelable` | `false`; there is no default behavior to cancel.
`currentTarget` | The object that is actively processing the event.
`target` | The Stage object reporting on the availability of stage video.

Examples How to use this example
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.

Copy

    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);
            }
        }
    }

© 2015 Adobe Systems Incorporated. All rights reserved.
Mon Apr 10 2017, 12:28 PM -07:00