class Stage

package openfl.display

extends DisplayObjectContainer › InteractiveObject › DisplayObject › EventDispatcher

implements IModule

Available on all platforms

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.

@event 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.

@event 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.

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

@event orientationChanging Dispatched by the Stage object when the stage

                          orientation begins changing.

                          **Important:** orientationChanging
                          events are not dispatched on Android
                          devices.

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

@event resize Dispatched when the scaleMode

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

@event stageVideoAvailability Dispatched by the Stage object when the state

                          of the stageVideos property changes.

Constructor

new (window:Window, ?color:Int)

Available on Neko, Android, iOS, macOS, Linux, HTML5, Windows

Variables

align:StageAlign

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

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.

read onlyallowsFullScreen:Bool

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

read onlyallowsFullScreenInteractive:Bool

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

read onlyapplication:Application

read onlywrite onlycolor:UInt

The window background color.

read onlycontentsScaleFactor:Float

read onlywrite onlydisplayState:StageDisplayState

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

  • 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:
  • 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. 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.

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

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.

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.

read onlywrite onlyfocus: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.

Throws:

Error

Throws an error if focus cannot be set to the target.

read onlywrite onlyframeRate:Float

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

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.

read onlywrite onlyfullScreenHeight:UInt

read onlywrite onlyfullScreenWidth:UInt

quality:StageQuality

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.

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.

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.

scaleMode:StageScaleMode

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.

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.

showDefaultContextMenu:Bool

read onlystage3Ds:Vector<Stage3D>

stageFocusRect:Bool

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

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.

read onlystageHeight:Int

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.

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.

read onlystageWidth:Int

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.

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.

read onlywindow:Window

Methods

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

Inherited Variables

Defined by DisplayObjectContainer

mouseChildren:Bool

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.

read onlywrite onlynumChildren:Int

Returns the number of children of this object.

tabChildren:Bool

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.

Throws:

IllegalOperationError

Calling this property of the Stage object throws an exception. The Stage object does not implement this property.

Defined by InteractiveObject

doubleClickEnabled:Bool

Specifies whether the object receives 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.

focusRect:Null<Bool>

mouseEnabled:Bool

Specifies whether this object receives mouse, or other user input, messages. The default value is 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 openfl.display.DisplayObjectContainer.mouseChildren.

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

needsSoftKeyboard:Bool

Specifies whether a virtual keyboard(an on-screen, software keyboard) should display when this InteractiveObject instance receives focus.

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.

softKeyboardInputAreaOfInterest:Rectangle

read onlywrite onlytabEnabled:Bool

read onlywrite onlytabIndex:Int

Defined by DisplayObject

read onlywrite onlyalpha:Float

Indicates the alpha transparency value of the object specified. Valid values are 0(fully transparent) to 1(fully opaque). The default value is 1. Display objects with alpha set to 0 are active, even though they are invisible.

read onlyblendMode:BlendMode

A value from the BlendMode class that specifies which blend mode to use. A bitmap can be drawn internally in two ways. If you have a blend mode enabled or an external clipping mask, the bitmap is drawn by adding a bitmap-filled square shape to the vector render. If you attempt to set this property to an invalid value, Flash runtimes set the value to 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).

read onlywrite onlycacheAsBitmap:Bool

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 bitmap is too large. In AIR 1.5 and Flash Player 10, the maximum size for a bitmap image is 8,191 pixels in width or height, and the total number of pixels cannot exceed 16,777,215 pixels.(So, if a bitmap image is 8,191 pixels wide, it can only be 2,048 pixels high.) In Flash Player 9 and earlier, the limitation is is 2880 pixels in height and 2,880 pixels in width.
  • The bitmap fails to allocate(out of memory error).

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

read onlywrite onlyfilters:Array<BitmapFilter>

An indexed array that contains each filter object currently associated with the display object. The openfl.filters package contains several classes that define specific filters you can use.

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

  1. Create a new filter object by using the constructor method of your chosen filter class.
  2. Assign the value of the myDisplayObject.filters array to a temporary array, such as one named myFilters.
  3. Add the new filter object to the myFilters temporary array.
  4. Assign the value of the temporary array to the 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:

  1. Assign the value of the filters array to a temporary array, such as one named myFilters.
  2. Modify the property by using the temporary array, myFilters. For example, to set the quality property of the first filter in the array, you could use the following code: myFilters[0].quality = 1;
  3. Assign the value of the temporary array to the 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 openfl.filters package includes classes for filters. For example, to create a DropShadow filter, you would write:

Throws:

ArgumentError

When filters includes a ShaderFilter and the shader output type is not compatible with this operation(the shader must specify a pixel4 output).

ArgumentError

When filters includes a ShaderFilter and the shader doesn't specify any image input or the first input is not an image4 input.

ArgumentError

When filters includes a ShaderFilter and the shader specifies an image input that isn't provided.

ArgumentError

When filters includes a ShaderFilter, a ByteArray or Vector. instance as a shader input, and the width and height properties aren't specified for the ShaderInput object, or the specified values don't match the amount of data in the input data. See the ShaderInput.input property for more information.

read onlywrite onlyheight:Float

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:

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.

read onlywrite onlyloaderInfo:LoaderInfo

Returns a LoaderInfo object containing information about loading the file to which this display object belongs. The 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).

read onlywrite onlymask:DisplayObject

The calling display object is masked by the specified 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.

read onlywrite onlymouseX:Float

Indicates the x coordinate of the mouse or user input device position, in pixels.

Note: For a DisplayObject that has been rotated, the returned x coordinate will reflect the non-rotated object.

read onlywrite onlymouseY:Float

Indicates the y coordinate of the mouse or user input device position, in pixels.

Note: For a DisplayObject that has been rotated, the returned y coordinate will reflect the non-rotated object.

read onlywrite onlyname:String

Indicates the instance name of the DisplayObject. The object can be identified in the child list of its parent display object container by calling the getChildByName() method of the display object container.

Throws:

IllegalOperationError

If you are attempting to set this property on an object that was placed on the timeline in the Flash authoring tool.

opaqueBackground:Null<UInt>

Specifies whether the display object is opaque with a certain background color. A transparent bitmap contains alpha channel data and is drawn transparently. An opaque bitmap has no alpha channel(and renders faster than a transparent bitmap). If the bitmap is opaque, you specify its own background color to use.

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.

read onlyparent:DisplayObjectContainer

Indicates the DisplayObjectContainer object that contains this display object. Use the 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:

Throws:

SecurityError

The parent display object belongs to a security sandbox to which you do not have access. You can avoid this situation by having the parent movie call the Security.allowDomain() method.

read onlywrite onlyroot:DisplayObject

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

read onlywrite onlyrotation:Float

Indicates the rotation of the DisplayObject instance, in degrees, from its original orientation. Values from 0 to 180 represent clockwise rotation; values from 0 to -180 represent counterclockwise rotation. Values outside this range are added to or subtracted from 360 to obtain a value within the range. For example, the statement my_video.rotation = 450 is the same as my_video.rotation = 90.

scale9Grid:Rectangle

The current scaling grid that is in effect. If set to 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:

  • The upper-left corner outside of the rectangle
  • The area above the rectangle
  • The upper-right corner outside of the rectangle
  • The area to the left of the rectangle
  • The area to the right of the rectangle
  • The lower-left corner outside of the rectangle
  • The area below the rectangle
  • The lower-right corner outside of the rectangle

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:

  • Content in the center region is scaled normally.
  • Content in the corners is not scaled.
  • Content in the top and bottom regions is scaled horizontally only. Content in the left and right regions is scaled vertically only.
  • All fills(including bitmaps, video, and gradients) are stretched to fit their shapes.

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.

Throws:

ArgumentError

If you pass an invalid argument to the method.

read onlywrite onlyscaleX:Float

Indicates the horizontal scale(percentage) of the object as applied from the registration point. The default registration point is(0,0). 1.0 equals 100% scale.

Scaling the local coordinate system changes the x and y property values, which are defined in whole pixels.

read onlywrite onlyscaleY:Float

Indicates the vertical scale(percentage) of an object as applied from the registration point of the object. The default registration point is(0,0). 1.0 is 100% scale.

Scaling the local coordinate system changes the x and y property values, which are defined in whole pixels.

read onlywrite onlyscrollRect:Rectangle

The scroll rectangle bounds of the display object. The display object is cropped to the size defined by the rectangle, and it scrolls within the rectangle when you change the 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.

read onlystage:Stage

The Stage of the display object. A Flash runtime application has only one Stage object. For example, you can create and load multiple display objects into the display list, and the 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.

read onlywrite onlytransform:Transform

An object with properties pertaining to a display object's matrix, color transform, and pixel bounds. The specific properties - matrix, colorTransform, and three read-only properties (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.

read onlywrite onlyvisible:Bool

Whether or not the display object is visible. Display objects that are not visible are disabled. For example, if visible=false for an InteractiveObject instance, it cannot be clicked.

read onlywrite onlywidth:Float

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:

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.

read onlywrite onlyx:Float

Indicates the x coordinate of the DisplayObject instance relative to the local coordinates of the parent DisplayObjectContainer. If the object is inside a DisplayObjectContainer that has transformations, it is in the local coordinate system of the enclosing DisplayObjectContainer. Thus, for a DisplayObjectContainer rotated 90° counterclockwise, the DisplayObjectContainer's children inherit a coordinate system that is rotated 90° counterclockwise. The object's coordinates refer to the registration point position.

read onlywrite onlyy:Float

Indicates the y coordinate of the DisplayObject instance relative to the local coordinates of the parent DisplayObjectContainer. If the object is inside a DisplayObjectContainer that has transformations, it is in the local coordinate system of the enclosing DisplayObjectContainer. Thus, for a DisplayObjectContainer rotated 90° counterclockwise, the DisplayObjectContainer's children inherit a coordinate system that is rotated 90° counterclockwise. The object's coordinates refer to the registration point position.

Inherited Methods

Defined by DisplayObjectContainer

addChild (child:DisplayObject):DisplayObject

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.

@event added Dispatched when a display object is added to the display

         list.

Parameters:

child

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

Throws:

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.

Returns:

The DisplayObject instance that you pass in the child parameter.

addChildAt (child:DisplayObject, index:Int):DisplayObject

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.

@event added Dispatched when a display object is added to the display

         list.

Parameters:

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.

Throws:

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.

Returns:

The DisplayObject instance that you pass in the child parameter.

areInaccessibleObjectsUnderPoint (point:Point):Bool

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

Parameters:

point

The point under which to look.

Returns:

true if the point contains child display objects with security restrictions.

contains (child:DisplayObject):Bool

Determines whether the specified display object is a child of the DisplayObjectContainer instance or the instance itself. The search includes the entire display list including this DisplayObjectContainer instance. Grandchildren, great-grandchildren, and so on each return true.

Parameters:

child

The child object to test.

Returns:

true if the child object is a child of the DisplayObjectContainer or the container itself; otherwise false.

getChildAt (index:Int):DisplayObject

Returns the child display object instance that exists at the specified index.

Parameters:

index

The index position of the child object.

Throws:

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

Returns:

The child display object at the specified index position.

getChildByName (name:String):DisplayObject

Returns the child display object that exists with the specified name. If more that one child display object has the specified name, the method returns the first object in the child list.

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.

Parameters:

name

The name of the child to return.

Throws:

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.

Returns:

The child display object with the specified name.

getChildIndex (child:DisplayObject):Int

Returns the index position of a child DisplayObject instance.

Parameters:

child

The DisplayObject instance to identify.

Throws:

ArgumentError

Throws if the child parameter is not a child of this object.

Returns:

The index position of the child display object to identify.

getObjectsUnderPoint (point:Point):Array<DisplayObject>

Returns an array of objects that lie under the specified point and are children(or grandchildren, and so on) of this DisplayObjectContainer instance. Any child objects that are inaccessible for security reasons are omitted from the returned array. To determine whether this security restriction affects the returned array, call the 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.

Parameters:

point

The point under which to look.

Returns:

An array of objects that lie under the specified point and are children(or grandchildren, and so on) of this DisplayObjectContainer instance.

removeChild (child:DisplayObject):DisplayObject

Removes the specified 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.

Parameters:

child

The DisplayObject instance to remove.

Throws:

ArgumentError

Throws if the child parameter is not a child of this object.

Returns:

The DisplayObject instance that you pass in the child parameter.

removeChildAt (index:Int):DisplayObject

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

The child index of the DisplayObject to remove.

Throws:

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.

Returns:

The DisplayObject instance that was removed.

removeChildren (beginIndex:Int = 0, endIndex:Int = 0x7FFFFFFF):Void

setChildIndex (child:DisplayObject, index:Int):Void

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:

This code results in the following arrangement of objects:

Parameters:

child

The child DisplayObject instance for which you want to change the index number.

index

The resulting index number for the child display object.

Throws:

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.

stopAllMovieClips ():Void

swapChildren (child1:DisplayObject, child2:DisplayObject):Void

Swaps the z-order(front-to-back order) of the two specified child objects. All other child objects in the display object container remain in the same index positions.

Parameters:

child1

The first child object.

child2

The second child object.

Throws:

ArgumentError

Throws if either child parameter is not a child of this object.

swapChildrenAt (index1:Int, index2:Int):Void

Swaps the z-order(front-to-back order) of the child objects at the two specified index positions in the child list. All other child objects in the display object container remain in the same index positions.

Parameters:

index1

The index position of the first child object.

index2

The index position of the second child object.

Throws:

RangeError

If either index does not exist in the child list.

Defined by InteractiveObject

requestSoftKeyboard ():Bool

Raises a virtual keyboard.

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.

Returns:

A value of true means that the soft keyboard request was granted; false means that the soft keyboard was not raised.

Defined by DisplayObject

getBounds (targetCoordinateSpace:DisplayObject):Rectangle

Returns a rectangle that defines the area of the display object relative to the coordinate system of the 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.

Parameters:

targetCoordinateSpace

The display object that defines the coordinate system to use.

Returns:

The rectangle that defines the area of the display object relative to the targetCoordinateSpace object's coordinate system.

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

Parameters:

targetCoordinateSpace

The display object that defines the coordinate system to use.

Returns:

The rectangle that defines the area of the display object relative to the targetCoordinateSpace object's coordinate system.

globalToLocal (pos:Point):Point

Converts the 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.

Parameters:

point

An object created with the Point class. The Point object specifies the x and y coordinates as properties.

Returns:

A Point object with coordinates relative to the display object.

hitTestObject (obj:DisplayObject):Bool

Evaluates the bounding box of the display object to see if it overlaps or intersects with the bounding box of the obj display object.

Parameters:

obj

The display object to test against.

Returns:

true if the bounding boxes of the display objects intersect; false if not.

hitTestPoint (x:Float, y:Float, shapeFlag:Bool = false):Bool

Evaluates the display object to see if it overlaps or intersects with the point specified by the 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).

Parameters:

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

Returns:

true if the display object overlaps or intersects with the specified point; false otherwise.

localToGlobal (point:Point):Point

Converts the 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.

Parameters:

point

The name or identifier of a point created with the Point class, specifying the x and y coordinates as properties.

Returns:

A Point object with coordinates relative to the Stage.

Defined by EventDispatcher

addEventListener (type:String, listener:Dynamic ‑> Void, useCapture:Bool = false, priority:Int = 0, useWeakReference:Bool = false):Void

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

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.

Throws:

ArgumentError

The listener specified is not a function.

dispatchEvent (event:Event):Bool

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

Parameters:

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.

Throws:

Error

The event dispatch recursion limit has been reached.

Returns:

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

hasEventListener (type:String):Bool

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

The type of event.

Returns:

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

removeEventListener (type:String, listener:Dynamic ‑> Void, useCapture:Bool = false):Void

Removes a listener from the EventDispatcher object. If there is no matching listener registered with the EventDispatcher object, a call to this method has no effect.

Parameters:

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.

toString ():String

willTrigger (type:String):Bool

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

The type of event.

Returns:

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