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.
accessibilityPropertiesalphablendModecacheAsBitmapcontextMenufiltersfocusRectloaderInfomaskmouseEnablednameopaqueBackgroundrotationscale9GridscaleXscaleYscrollRecttabEnabledtabIndextransformvisiblexySome 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.
alpha set to 0 are active,
even though they are invisible.BlendMode.NORMAL.
The blendMode property affects each pixel of the display
object. Each pixel is composed of three constituent colors(red, green,
and blue), and each constituent color has a value between 0x00 and 0xFF.
Flash Player or Adobe AIR compares each constituent color of one pixel in
the movie clip with the corresponding color of the pixel in the
background. For example, if blendMode is set to
BlendMode.LIGHTEN, Flash Player or Adobe AIR compares the red
value of the display object with the red value of the background, and uses
the lighter of the two as the value for the red component of the displayed
color.
The following table describes the blendMode settings. The
BlendMode class defines string values you can use. The illustrations in
the table show blendMode values applied to a circular display
object(2) superimposed on another display object(1).
true, NME will use the software renderer to cache
an internal bitmap representation of the display object. For native targets,
this is often much slower than the default hardware renderer. When you
are using the Flash target, this caching may increase performance for display
objects that contain complex vector content.
All vector data for a display object that has a cached bitmap is drawn
to the bitmap instead of the main display. If
cacheAsBitmapMatrix is null or unsupported, the bitmap is
then copied to the main display as unstretched, unrotated pixels snapped
to the nearest pixel boundaries. Pixels are mapped 1 to 1 with the parent
object. If the bounds of the bitmap change, the bitmap is recreated
instead of being stretched.
If cacheAsBitmapMatrix is non-null and supported, the
object is drawn to the off-screen bitmap using that matrix and the
stretched and/or rotated results of that rendering are used to draw the
object to the main display.
No internal bitmap is created unless the cacheAsBitmap
property is set to true.
After you set the cacheAsBitmap property to
true, the rendering does not change, however the display
object performs pixel snapping automatically. The animation speed can be
significantly faster depending on the complexity of the vector content.
The cacheAsBitmap property is automatically set to
true whenever you apply a filter to a display object(when
its filter array is not empty), and if a display object has a
filter applied to it, cacheAsBitmap is reported as
true for that display object, even if you set the property to
false. If you clear all filters for a display object, the
cacheAsBitmap setting changes to what it was last set to.
A display object does not use a bitmap even if the
cacheAsBitmap property is set to true and
instead renders from vector data in the following cases:
The cacheAsBitmap property is best used with movie clips
that have mostly static content and that do not scale and rotate
frequently. With such movie clips, cacheAsBitmap can lead to
performance increases when the movie clip is translated(when its x
and y position is changed).
The three possible values are strings with corresponding constants in the nme.display.ColorCorrectionSupport class:
"unsupported": Color correction is not available."defaultOn": Always performs color correction."defaultOff": Never performs color correction.StageDisplayState.FULL_SCREEN Sets AIR application or
Flash runtime to expand the stage over the user's entire screen, with
keyboard input disabled.StageDisplayState.FULL_SCREEN_INTERACTIVE Sets the AIR
application to expand the stage over the user's entire screen, with
keyboard input allowed.(Not available for content running in Flash
Player.)StageDisplayState.NORMAL Sets the Flash runtime 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 not running in the AIR runtime):
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: 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. Keyboard shortcuts that terminate full-screen mode are: Escape
(Windows, Linux, and Mac), Control+W(Windows), Command+W(Mac), and
Alt+F4.
A Flash runtime dialog box appears over the movie when users enter full-screen mode to inform the users they are in full-screen mode and that they can press the Escape key to end full-screen mode.
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.These restrictions are not present for SWF content running in the stand-alone Flash Player or in AIR. AIR supports an interactive full-screen mode which allows keyboard input.
For AIR content running in full-screen mode, the system screen saver and power saving options are disabled while video content is playing and until 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.
doubleClick events. The
default value is false, which means that by default an
InteractiveObject instance does not receive doubleClick
events. If the doubleClickEnabled property is set to
true, the instance receives doubleClick events
within its bounds. The mouseEnabled property of the
InteractiveObject instance must also be set to true for the
object to receive doubleClick events.
No event is dispatched by setting this property. You must use the
addEventListener() method to add an event listener for the
doubleClick event.
Filters can be applied in Flash Professional at design time, or at run
time by using ActionScript code. To apply a filter by using ActionScript,
you must make a temporary copy of the entire filters array,
modify the temporary array, then assign the value of the temporary array
back to the filters array. You cannot directly add a new
filter object to the filters array.
To add a filter by using ActionScript, perform the following steps
(assume that the target display object is named
myDisplayObject):
myDisplayObject.filters array
to a temporary array, such as one named myFilters.myFilters temporary
array.myDisplayObject.filters array.If the filters array is undefined, you do not need to use
a temporary array. Instead, you can directly assign an array literal that
contains one or more filter objects that you create. The first example in
the Examples section adds a drop shadow filter by using code that handles
both defined and undefined filters arrays.
To modify an existing filter object, you must use the technique of
modifying a copy of the filters array:
filters array to a temporary
array, such as one named myFilters.myFilters. For example, to set the quality property of the
first filter in the array, you could use the following code:
myFilters0.quality = 1;filters
array.At load time, if a display object has an associated filter, it is marked to cache itself as a transparent bitmap. From this point forward, as long as the display object has a valid filter list, the player caches the display object as a bitmap. This source bitmap is used as a source image for the filter effects. Each display object usually has two bitmaps: one with the original unfiltered source display object and another for the final image after filtering. The final image is used when rendering. As long as the display object does not change, the final image does not need updating.
The nme.filters package includes classes for filters. For example, to create a DropShadow filter, you would write:
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.
true, false, or
null. Values of true and false work
as expected, specifying whether or not the focus rectangle appears. A
value of null indicates that this object obeys the
stageFocusRect property of the Stage.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).
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.
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.
To enable scaling, set the fullScreenSourceRect property
to a rectangle object:
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.
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.
height property, the scaleY property
is adjusted accordingly, as shown in the following code:
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.
loaderInfo property
is defined only for the root display object of a SWF file or for a loaded
Bitmap(not for a Bitmap that is drawn with ActionScript). To find the
loaderInfo object associated with the SWF file that contains
a display object named myDisplayObject, use
myDisplayObject.root.loaderInfo.
A large SWF file can monitor its download by calling
this.root.loaderInfo.addEventListener(Event.COMPLETE,
func).
mask
object. To ensure that masking works when the Stage is scaled, the
mask display object must be in an active part of the display
list. The mask object itself is not drawn. Set
mask to null to remove the mask.
To be able to scale a mask object, it must be on the display list. To
be able to drag a mask Sprite object(by calling its
startDrag() method), it must be on the display list. To call
the startDrag() method for a mask sprite based on a
mouseDown event being dispatched by the sprite, set the
sprite's buttonMode property to true.
When display objects are cached by setting the
cacheAsBitmap property to true an the
cacheAsBitmapMatrix property to a Matrix object, both the
mask and the display object being masked must be part of the same cached
bitmap. Thus, if the display object is cached, then the mask must be a
child of the display object. If an ancestor of the display object on the
display list is cached, then the mask must be a child of that ancestor or
one of its descendents. If more than one ancestor of the masked object is
cached, then the mask must be a descendent of the cached container closest
to the masked object in the display list.
Note: A single mask object cannot be used to mask
more than one calling display object. When the mask is
assigned to a second display object, it is removed as the mask of the
first object, and that object's mask property becomes
null.
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.
true, which means that by
default any InteractiveObject instance that is on the display list
receives mouse events or other user input events. If
mouseEnabled is set to false, the instance does
not receive any mouse events(or other user input events like keyboard
events). Any children of this instance on the display list are not
affected. To change the mouseEnabled behavior for all
children of an object on the display list, use
nme.display.DisplayObjectContainer.mouseChildren.
No event is dispatched by setting this property. You must use the
addEventListener() method to create interactive
functionality.
Note: For a DisplayObject that has been rotated, the returned x coordinate will reflect the non-rotated object.
Note: For a DisplayObject that has been rotated, the returned y coordinate will reflect the non-rotated object.
getChildByName() method of the display object
container.
By default, the value is false and focusing an
InteractiveObject instance does not raise a soft keyboard. If the
needsSoftKeyboard property is set to true, the
runtime raises a soft keyboard when the InteractiveObject instance is
ready to accept user input. An InteractiveObject instance is ready to
accept user input after a programmatic call to set the Stage
focus property or a user interaction, such as a "tap." If the
client system has a hardware keyboard available or does not support
virtual keyboards, then the soft keyboard is not raised.
The InteractiveObject instance dispatches
softKeyboardActivating, softKeyboardActivate,
and softKeyboardDeactivate events when the soft keyboard
raises and lowers.
Note: This property is not supported in AIR applications on iOS.
If set to a number value, the surface is opaque(not transparent) with
the RGB background color that the number specifies. If set to
null(the default value), the display object has a
transparent background.
The opaqueBackground property is intended mainly for use
with the cacheAsBitmap property, for rendering optimization.
For display objects in which the cacheAsBitmap property is
set to true, setting opaqueBackground can improve rendering
performance.
The opaque background region is not matched when calling the
hitTestPoint() method with the shapeFlag
parameter set to true.
The opaque background region does not respond to mouse events.
parent property to specify a relative path to
display objects that are above the current display object in the display
list hierarchy.
You can use parent to move up multiple levels in the
display list as in the following:
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.
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).
quality property.
Calling this method focuses the InteractiveObject instance and raises
the soft keyboard, if necessary. The needsSoftKeyboard must
also be true. A keyboard is not raised if a hardware keyboard
is available, or if the client system does not support virtual
keyboards.
Note: This method is not supported in AIR applications on iOS.
root property
is the top-most display object in the portion of the display list's tree
structure represented by that SWF file. For a Bitmap object representing a
loaded image file, the root property is the Bitmap object
itself. For the instance of the main class of the first SWF file loaded,
the root property is the display object itself. The
root property of the Stage object is the Stage object itself.
The root property is set to null for any display
object that has not been added to the display list, unless it has been
added to a display object container that is off the display list but that
is a child of the top-most display object in a loaded SWF file.
For example, if you create a new Sprite object by calling the
Sprite() constructor method, its root property
is null until you add it to the display list(or to a display
object container that is off the display list but that is a child of the
top-most display object in a SWF file).
For a loaded SWF file, even though the Loader object used to load the
file may not be on the display list, the top-most display object in the
SWF file has its root property set to itself. The Loader
object does not have its root property set until it is added
as a child of a display object for which the root property is
set.
my_video.rotation = 450
is the same as my_video.rotation = 90.null,
the entire display object is scaled normally when any scale transformation
is applied.
When you define the scale9Grid property, the display
object is divided into a grid with nine regions based on the
scale9Grid rectangle, which defines the center region of the
grid. The eight other regions of the grid are the following areas:
You can think of the eight regions outside of the center(defined by the rectangle) as being like a picture frame that has special rules applied to it when scaled.
When the scale9Grid property is set and a display object
is scaled, all text and gradients are scaled normally; however, for other
types of objects the following rules apply:
If a display object is rotated, all subsequent scaling is normal(and
the scale9Grid property is ignored).
For example, consider the following display object and a rectangle that
is applied as the display object's scale9Grid:
A common use for setting scale9Grid is to set up a display
object to be used as a component, in which edge regions retain the same
width when the component is scaled.
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. Scaling the local coordinate system changes the x and
y property values, which are defined in whole pixels.
Scaling the local coordinate system changes the x and
y property values, which are defined in whole pixels.
x and y properties
of the scrollRect object.
The properties of the scrollRect Rectangle object use the
display object's coordinate space and are scaled just like the overall
display object. The corner bounds of the cropped window on the scrolling
display object are the origin of the display object(0,0) and the point
defined by the width and height of the rectangle. They are not centered
around the origin, but use the origin to define the upper-left corner of
the area. A scrolled display object always scrolls in whole pixel
increments.
You can scroll an object left and right by setting the x
property of the scrollRect Rectangle object. You can scroll
an object up and down by setting the y property of the
scrollRect Rectangle object. If the display object is rotated
90° and you scroll it left and right, the display object actually scrolls
up and down.
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.
If the needsSoftKeyboard property of this
InteractiveObject is true, then the runtime adjusts the
display as needed to keep the object in view while the user types.
Ordinarily, the runtime uses the object bounds obtained from the
DisplayObject.getBounds() method. You can specify a different
area using this softKeyboardInputAreaOfInterest property.
Specify the softKeyboardInputAreaOfInterest in stage
coordinates.
Note: On Android, the
softKeyboardInputAreaOfInterest is not respected in landscape
orientations.
The area has a size of zero(0,0,0,0) when the soft keyboard is not visible.
When the keyboard opens, the softKeyboardRect is set at
the time the softKeyboardActivate event is dispatched. If the keyboard
changes size while open, the runtime updates the
softKeyboardRect property and dispatches an additional
softKeyboardActivate event.
Note: On Android, the area covered by the keyboard is estimated
when the operating system does not provide the information necessary to
determine the exact area. This problem occurs in fullscreen mode and also
when the keyboard opens in response to an InteractiveObject receiving
focus or invoking the requestSoftKeyboard() method.
stage property of each
display object refers to the same Stage object(even if the display object
belongs to a loaded SWF file).
If a display object is not added to the display list, its
stage property is set to null.
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.
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.
true.
Note: Do not use the tabChildren property with
Flex. Instead, use the
mx.core.UIComponent.hasFocusableChildren property.
true; otherwise, the value is
false. By default, the value is false, except
for the following:
true.type = "input", the value
is true.buttonMode =
true, the value is true.tabIndex property is -1 by default, meaning no tab index is
set for the object.
If any currently displayed object in the SWF file contains a
tabIndex property, automatic tab ordering is disabled, and
the tab ordering is calculated from the tabIndex properties
of objects in the SWF file. The custom tab ordering includes only objects
that have tabIndex properties.
The tabIndex property can be a non-negative integer. The
objects are ordered according to their tabIndex properties,
in ascending order. An object with a tabIndex value of 1
precedes an object with a tabIndex value of 2. Do not use the
same tabIndex value for multiple objects.
The custom tab ordering that the tabIndex property defines
is flat. This means that no attention is paid to the hierarchical
relationships of objects in the SWF file. All objects in the SWF file with
tabIndex properties are placed in the tab order, and the tab
order is determined by the order of the tabIndex values.
Note: To set the tab order for TLFTextField instances, cast the
display object child of the TLFTextField as an InteractiveObject, then set
the tabIndex property. For example:
InteractiveObject(tlfInstance.getChildAt(1)).tabIndex = 3;To reverse the tab order from the default setting for three instances of a TLFTextField object(
tlfInstance1, tlfInstance2
and tlfInstance3), use: InteractiveObject(tlfInstance1.getChildAt(1)).tabIndex = 3; InteractiveObject(tlfInstance2.getChildAt(1)).tabIndex = 2; InteractiveObject(tlfInstance3.getChildAt(1)).tabIndex = 1;
concatenatedMatrix, concatenatedColorTransform,
and pixelBounds) - are described in the entry for the
Transform class.
Each of the transform object's properties is itself an object. This concept is important because the only way to set new values for the matrix or colorTransform objects is to create a new object and copy that object into the transform.matrix or transform.colorTransform property.
For example, to increase the tx value of a display
object's matrix, you must make a copy of the entire matrix object, then
copy the new object into the matrix property of the transform object:
var myMatrix:Matrix =
myDisplayObject.transform.matrix; myMatrix.tx += 10;
myDisplayObject.transform.matrix = myMatrix; You cannot directly set the tx property. The following
code has no effect on myDisplayObject:
myDisplayObject.transform.matrix.tx +=
10; You can also copy an entire transform object and assign it to another
display object's transform property. For example, the following code
copies the entire transform object from myOldDisplayObj to
myNewDisplayObj:
myNewDisplayObj.transform = myOldDisplayObj.transform;
The resulting display object, myNewDisplayObj, now has the
same values for its matrix, color transform, and pixel bounds as the old
display object, myOldDisplayObj.
Note that AIR for TV devices use hardware acceleration, if it is available, for color transforms.
visible=false for an
InteractiveObject instance, it cannot be clicked.width property, the scaleX property
is adjusted accordingly, as shown in the following code:
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.
wmodeGPU value is true only when all
three of the following conditions exist:
Specifically, the wmodeGPU property indicates one of the
following:
wmodeGPU property value is false.wmodeGPU property value is true.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.
child The DisplayObject instance to add as a child of this DisplayObjectContainer instance.child parameter.ArgumentError Throws if the child is the same as the parent. Also throws if the caller is a child(or grandchild etc.) of the child being added.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.
child The DisplayObject instance to add as a child of this DisplayObjectContainer instance.index 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.child parameter.ArgumentError Throws if the child is the same as the parent. Also throws if the caller is a child(or grandchild etc.) of the child being added.RangeError Throws if the index position does not exist in the child list.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.
type The type of event.useCapture 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 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 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.
ArgumentError The listener specified is not a function.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).
point The point under which to look.true if the point contains child display objects with security restrictions.DisplayObjectContainer.getObjectsUnderPoint() method with the
specified point point. By default, content from one domain
cannot access objects from another domain unless they are permitted to do
so with a call to the Security.allowDomain() method. For more
information, related to security, see the Flash Player Developer Center
Topic: Security.
The point parameter is in the coordinate space of the
Stage, which may differ from the coordinate space of the display object
container(unless the display object container is the Stage). You can use
the globalToLocal() and the localToGlobal()
methods to convert points between these coordinate spaces.
child The child object to test.true if the child object is a child of the DisplayObjectContainer or the container itself; otherwise false.true.
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.true if the event was successfully dispatched. A value of false indicates failure or that preventDefault() was called on the event.Error The event dispatch recursion limit has been reached.dispatchEvent() method
is called.
targetCoordinateSpace The display object that defines the coordinate system to use.targetCoordinateSpace object's coordinate system.targetCoordinateSpace object.
Consider the following code, which shows how the rectangle returned can
vary depending on the targetCoordinateSpace parameter that
you pass to the method:
Note: Use the localToGlobal() and
globalToLocal() methods to convert the display object's local
coordinates to display coordinates, or display coordinates to local
coordinates, respectively.
The getBounds() method is similar to the
getRect() method; however, the Rectangle returned by the
getBounds() method includes any strokes on shapes, whereas
the Rectangle returned by the getRect() method does not. For
an example, see the description of the getRect() method.
index The index position of the child object.RangeError Throws if the index does not exist in the child list.SecurityError This child display object belongs to a sandbox to which you do not have access. You can avoid this situation by having the child movie call Security.allowDomain().name The name of the child to return.SecurityError This child display object belongs to a sandbox to which you do not have access. You can avoid this situation by having the child movie call the Security.allowDomain() method.The getChildAt() method is faster than the
getChildByName() method. The getChildAt() method
accesses a child from a cached array, whereas the
getChildByName() method has to traverse a linked list to
access a child.
child The DisplayObject instance to identify.ArgumentError Throws if the child parameter is not a child of this object.child DisplayObject instance.
point The point under which to look.areInaccessibleObjectsUnderPoint() method.
The point parameter is in the coordinate space of the
Stage, which may differ from the coordinate space of the display object
container(unless the display object container is the Stage). You can use
the globalToLocal() and the localToGlobal()
methods to convert points between these coordinate spaces.
targetCoordinateSpace The display object that defines the coordinate system to use.targetCoordinateSpace object's coordinate system.targetCoordinateSpace
parameter, excluding any strokes on shapes. The values that the
getRect() method returns are the same or smaller than those
returned by the getBounds() method.
Note: Use localToGlobal() and
globalToLocal() methods to convert the display object's local
coordinates to Stage coordinates, or Stage coordinates to local
coordinates, respectively.
point An object created with the Point class. The Point object specifies the x and y coordinates as properties.point object from the Stage(global) coordinates
to the display object's(local) coordinates.
To use this method, first create an instance of the Point class. The
x and y values that you assign represent global coordinates
because they relate to the origin(0,0) of the main display area. Then
pass the Point instance as the parameter to the
globalToLocal() method. The method returns a new Point object
with x and y values that relate to the origin of the display
object instead of the origin of the Stage.
type The type of event.true if a listener of the specified type is registered; false otherwise.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.
obj The display object to test against.true if the bounding boxes of the display objects intersect; false if not.obj display object.
x The x coordinate to test against this object.y The y coordinate to test against this object.shapeFlag Whether to check against the actual pixels of the object (true) or the bounding box (false).true if the display object overlaps or intersects with the specified point; false otherwise.x and y parameters. The
x and y parameters specify a point in the
coordinate space of the Stage, not the display object container that
contains the display object(unless that display object container is the
Stage).
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.
true if the object that has focus belongs to a security sandbox to which the SWF file does not have access.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.
point The name or identifier of a point created with the Point class, specifying the x and y coordinates as properties.point object from the display object's(local)
coordinates to the Stage(global) coordinates.
This method allows you to convert any given x and y coordinates from values that are relative to the origin(0,0) of a specific display object(local coordinates) to values that are relative to the origin of the Stage(global coordinates).
To use this method, first create an instance of the Point class. The x and y values that you assign represent local coordinates because they relate to the origin of the display object.
You then pass the Point instance that you created as the parameter to
the localToGlobal() method. The method returns a new Point
object with x and y values that relate to the origin of the
Stage instead of the origin of the display object.
child The DisplayObject instance to remove.child parameter.ArgumentError Throws if the child parameter is not a child of this object.child DisplayObject instance from the
child list of the DisplayObjectContainer instance. 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.
index The child index of the DisplayObject to remove.RangeError Throws if the index does not exist in the child list.SecurityError This child display object belongs to a sandbox to which the calling object does not have access. You can avoid this situation by having the child movie call the Security.allowDomain() method.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.
type The type of event.useCapture Specifies whether the listener was registered for the capture phase or the target and bubbling phases. If the listener was registered for both the capture phase and the target and bubbling phases, two calls to removeEventListener() are required to remove both, one call with useCapture() set to true, and another call with useCapture() set to false.child The child DisplayObject instance for which you want to change the index number.index The resulting index number for the child display object.ArgumentError Throws if the child parameter is not a child of this object.RangeError Throws if the index does not exist in the child list.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:
This code results in the following arrangement of objects:
child1 The first child object.child2 The second child object.ArgumentError Throws if either child parameter is not a child of this object.index1 The index position of the first child object.index2 The index position of the second child object.RangeError If either index does not exist in the child list.type The type of event.true if a listener of the specified type will be triggered; false otherwise.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.
The
alignproperty 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 theSecurity.allowDomain()method or theSecurity.alowInsecureDomain()method. For more information, see the "Security" chapter in the ActionScript 3.0 Developer's Guide.