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.
accessibilityPropertiesalphablendModecacheAsBitmapcontextMenufiltersfocusRectloaderInfomaskmouseEnablednameopaqueBackgroundrotationscale9GridscaleXscaleYscrollRecttabEnabledtabIndextransformvisiblexy
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.
Events:
fullScreen | Dispatched when the Stage object enters, or leaves, full-screen mode. A change in full-screen mode can be initiated through ActionScript, or the user invoking a keyboard shortcut, or if the current focus leaves the full-screen window. |
|---|---|
mouseLeave | Dispatched by the Stage object when the pointer moves out of the stage area. If the mouse button is pressed, the event is not dispatched. |
orientationChange | Dispatched by the Stage object when the
stage orientation changes.
Orientation changes can occur when the user
rotates the device, opens a slide-out
keyboard, or when the Note: If the |
orientationChanging | Dispatched by the Stage object when the stage orientation begins changing. Important: orientationChanging events are not dispatched on Android devices. Note: If the |
resize | Dispatched when the |
stageVideoAvailability | Dispatched by the Stage object when the state of the stageVideos property changes. |
Variables
read onlycontext3D:Context3D
The Context3D object associated with this Stage3D instance.
This property is initially null. To create the Context3D instance for this
Stage3D object, add an event listener for the context3DCreate event and then call
the requestContext3D method. The listener is called once the Context3D object has
been created.
visible:Bool
Specifies whether this Stage3D object is visible.
Use this property to temporarily hide a Stage3D object on the Stage. This property
defaults to true.
x:Float
The horizontal coordinate of the Stage3D display on the stage, in pixels.
This property defaults to zero.
y:Float
The vertical coordinate of the Stage3D display on the stage, in pixels.
This property defaults to zero.
Methods
requestContext3D(context3DRenderMode:Context3DRenderMode = AUTO, profile:Context3DProfile = BASELINE):Void
Request the creation of a Context3D object for this Stage3D instance.
Before calling this function, add an event listener for the context3DCreate
event. If you do not, the runtime throws an exception.
Important note on device loss:
GPU device loss occurs when the GPU hardware becomes unavailable to the application.
The Context3D object is disposed when the GPU device is lost. GPU device loss can
happen for various reasons, such as, when a mobile device runs out of battery power
or a Windows device goes to a "lock screen." When the GPU becomes available again,
the runtime creates a new Context3D instance and dispatches another
context3DCreate event. Your application must reload all assets and reset the
rendering context state whenever device loss occurs.
Design your application logic to handle the possibility of device loss and context
regeneration. Do not remove the context3DCreate event listener. Do not perform
actions in response to the event that should not be repeated in the application.
For example, do not add anonymous functions to handle timer events because they
would be duplicated after device loss. To test your application's handling of
device loss, you can simulate device loss by calling the dispose() method of the
Context3D object.
The following example illustrates how to request a Context3d rendering context:
if( stage.stage3Ds.length > 0 )
{
var stage3D:Stage3D = stage.stage3Ds[0];
stage3D.addEventListener( Event.CONTEXT3D_CREATE, myContext3DHandler );
stage3D.requestContext3D( );
}
function myContext3DHandler ( event : Event ) : void
{
var targetStage3D : Stage3D = cast event.target;
InitAll3DResources( targetStage3D.context3D );
StartRendering( targetStage3D.context3D );
}Parameters:
context3DRenderMode | The type of rendering context to request. The default
is |
|---|---|
profile | (AIR 3.4 and higher) Specifies the extent to which Flash Player
supports lower-level GPUs. The default is |
Throws:
Error | if no listeners for the |
|---|---|
ArgumentError | if this method is called again with a different
|
Events:
context3DCreate | Dispatched when the requested rendering context is successfully completed. |
|---|---|
error | Dispatched when the requested rendering context cannot be created. |
requestContext3DMatchingProfiles(profiles:Vector<Context3DProfile>):Void
Request the creation of a Context3D object for this Stage3D instance.
Before calling this function, add an event listener for the context3DCreate
event. If you do not, the runtime throws an exception.
Important note on device loss:
GPU device loss occurs when the GPU hardware becomes unavailable to the
application. The Context3D object is disposed when the GPU device is lost. GPU
device loss can happen for various reasons, such as, when a mobile device runs out
of battery power or a Windows device goes to a "lock screen." When the GPU becomes
available again, the runtime creates a new Context3D instance and dispatches
another context3DCreate event. Your application must reload all assets and reset
the rendering context state whenever device loss occurs.
Design your application logic to handle the possibility of device loss and context
regeneration. Do not remove the context3DCreate event listener. Do not perform
actions in response to the event that should not be repeated in the application.
For example, do not add anonymous functions to handle timer events because they
would be duplicated after device loss. To test your application's handling of
device loss, you can simulate device loss by calling the dispose() method of the
Context3D object.
The following example illustrates how to request a Context3d rendering context:
if( stage.stage3Ds.length > 0 )
{
var stage3D:Stage3D = stage.stage3Ds[0];
stage3D.addEventListener( Event.CONTEXT3D_CREATE, myContext3DHandler );
stage3D.requestContext3DMatchingProfiles(Vector.<string>([Context3DProfile.BASELINE, Context3DProfile.BASELINE_EXTENDED]));
}
function myContext3DHandler ( event : Event ) : Void
{
var targetStage3D : Stage3D = cast event.target;
if(targetStage3D.context3D.profile.localeCompare(Context3DProfile.BASELINE) == 0)
{
InitAll3DResources( targetStage3D.context3D );
}
StartRendering( targetStage3D.context3D );
}Parameters:
profiles | (AIR 3.4 and higher) a profile arrays that developer want to
use in their flash program. When developer pass profile array to
|
|---|
Throws:
Error | if no listeners for the context3DCreate event have been added to this Stage3D object. |
|---|---|
ArgumentError | if this method is called before the previous call has completed. |
ArgumentError | if the item in array is not openfl.display3D.Context3DProfile. |
Events:
context3DCreate | Dispatched when the requested rendering context is successfully completed. |
|---|---|
error | Dispatched when the requested rendering context cannot be created. If the hardware is not available, it will not create a software context3d. |