nme.display.MovieClip

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.

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

Specifies the button mode of this sprite. If true, this sprite behaves as a button, which means that it triggers the display of the hand cursor when the pointer passes over the sprite and can receive a click event if the enter or space keys are pressed when the sprite has focus. You can suppress the display of the hand cursor by setting the useHandCursor property to false, in which case the pointer is displayed.

Although it is better to use the SimpleButton class to create buttons, you can use the buttonMode property to give a sprite some button-like functionality. To include a sprite in the tab order, set the tabEnabled property(inherited from the InteractiveObject class and false by default) to true. Additionally, consider whether you want the children of your sprite to be user input enabled. Most buttons do not enable user input interactivity for their child objects because it confuses the event flow. To disable user input interactivity for all child objects, you must set the mouseChildren property(inherited from the DisplayObjectContainer class) to false.

If you use the buttonMode property with the MovieClip class(which is a subclass of the Sprite class), your button might have some added functionality. If you include frames labeled _up, _over, and _down, Flash Player provides automatic state changes(functionality similar to that provided in previous versions of ActionScript for movie clips used as buttons). These automatic state changes are not available for sprites, which have no timeline, and thus no frames to label.

If set to 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 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).

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.

Specifies the display object over which the sprite is being dragged, or on which the sprite was dropped.

An indexed array that contains each filter object currently associated with the display object. The nme.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: myFilters0.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 nme.filters package includes classes for filters. For example, to create a DropShadow filter, you would write:

Specifies whether this object displays a focus rectangle. It can take one of three values: 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.

Specifies the Graphics object that belongs to this sprite where vector drawing commands can occur.

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.

Designates another sprite to serve as the hit area for a sprite. If the hitArea property does not exist or the value is null or undefined, the sprite itself is used as the hit area. The value of the hitArea property can be a reference to a Sprite object.

You can change the hitArea property at any time; the modified sprite immediately uses the new hit area behavior. The sprite designated as the hit area does not need to be visible; its graphical shape, although not visible, is still detected as the hit area.

Note: You must set to false the mouseEnabled property of the sprite designated as the hit area. Otherwise, your sprite button might not work because the sprite designated as the hit area receives the user input events instead of your sprite button.

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

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.

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.

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 nme.display.DisplayObjectContainer.mouseChildren.

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

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.

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.

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.

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.

Returns the number of children of this object.

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.

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:

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.

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.

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.

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.

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.

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.

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.

Defines the area that should remain on-screen when a soft keyboard is displayed.

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.

Controls sound within this sprite.

Note: This property does not affect HTML content in an HTMLControl object(in Adobe AIR).

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.

Lets the user drag the specified sprite on a touch-enabled device. The sprite remains draggable until explicitly stopped through a call to the Sprite.stopTouchDrag() method, or until another sprite is made draggable. Only one sprite is draggable at a time.

Three-dimensional display objects follow the pointer and Sprite.startTouchDrag() moves the object within the three-dimensional plane defined by the display object. Or, if the display object is a two-dimensional object and the child of a three-dimensional object, the two-dimensional object moves within the three dimensional plane defined by the three-dimensional parent object.

Ends the startTouchDrag() method, for use with touch-enabled devices. A sprite that was made draggable with the startTouchDrag() method remains draggable until a stopTouchDrag() method is added, or until another sprite becomes draggable. Only one sprite is draggable at a time.

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.

Specifies whether this object is in the tab order. If this object is in the tab order, the value is true; otherwise, the value is false. By default, the value is false, except for the following:

• For a SimpleButton object, the value is true.
• For a TextField object with type = "input", the value is true.
• For a Sprite object or MovieClip object with buttonMode = true, the value is true.

Specifies the tab ordering of objects in a SWF file. The 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; 

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.

A Boolean value that indicates whether the pointing hand(hand cursor) appears when the pointer rolls over a sprite in which the buttonMode property is set to true. The default value of the useHandCursor property is true. If useHandCursor is set to true, the pointing hand used for buttons appears when the pointer rolls over a button sprite. If useHandCursor is false, the arrow pointer is used instead.

You can change the useHandCursor property at any time; the modified sprite immediately takes on the new cursor appearance.

Note: In Flex or Flash Builder, if your sprite has child sprites, you might want to set the mouseChildren property to false. For example, if you want a hand cursor to appear over a Flex control, set the useHandCursor and buttonMode properties to true, and the mouseChildren property to false.

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.

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.

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.

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.