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 mouse 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 mouse enabled. Most buttons do not enable mouse interactivity for their child objects because it confuses the event flow. To disable mouse 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.

Containers use an internal content pane to control scrolling. The creatingContentPane is true while the container is creating the content pane so that some events can be ignored or blocked.

The Button control designated as the default button for the container. When controls in the container have focus, pressing the Enter key is the same as clicking this Button control.

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.

Gets the FocusManager that controls focus for this component and its peers. Each popup has its own focus loop and therefore its own instance of a FocusManager. To make sure you're talking to the right one, use this method.

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.

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 mouse events instead of your sprite button.

The current position of the horizontal scroll bar. This is equal to the distance in pixels between the left edge of the scrollable surface and the leftmost piece of the surface that is currently visible.

Determines whether or not the children of the object are mouse enabled. If an object is mouse enabled, a user can interact with it by using a mouse. 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 messages. The default value is true, which means that by default any InteractiveObject instance that is on the display list receives mouse events. If mouseEnabled is set to false, the instance does not receive any mouse 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 flash.display.DisplayObjectContainer.mouseChildren.

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

Returns the number of children of this object.

Controls sound within this sprite.

Determines whether the children of the object are tab enabled.

Note: Do not use this property with Flex. Instead, use the UIComponent.hasFocusableChildren property.

See also

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.

Returns a TextSnapshot object for this DisplayObjectContainer instance.

A Boolean value that indicates whether the pointing hand (hand cursor) appears when the mouse 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 mouse 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: 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 <mx:Label> control, set the useHandCursor and buttonMode properties to true, and the mouseChildren property to false.

The current position of the vertical scroll bar. This is equal to the distance in pixels between the top edge of the scrollable surface and the topmost piece of the surface that is currently visible.

Returns an object that has four properties: left, top, right, and bottom. The value of each property equals the thickness of the chrome (visual elements) around the edge of the container.

The chrome includes the border thickness. If the horizontalScrollPolicy or verticalScrollPolicy property value is ScrollPolicy.ON, the chrome also includes the thickness of the corresponding scroll bar. If a scroll policy is ScrollPolicy.AUTO, the chrome measurement does not include the scroll bar thickness, even if a scroll bar is displayed.

Subclasses of Container should override this method, so that they include other chrome to be taken into account when positioning the Container's children. For example, the viewMetrics property for the Panel class should return an object whose top property includes the thickness of the Panel container's title bar.

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.

Parameters

Adds a child DisplayObject instance to this DisplayObjectContainer instance. The child is added at the index position specified. An index of 0 represents the back (bottom) of the display list for this DisplayObjectContainer object.

For example, the following example shows three display objects, labeled a, b, and c, at index positions 0, 2, and 1, respectively:

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

Parameters

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, see the following:

• The security chapter in the Programming ActionScript 3.0 book and the latest comments on LiveDocs
• The security chapter in the Programming ActionScript 3.0 book and the latest comments on LiveDocs
• 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

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

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

Parameters

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

Returns the index position of a child DisplayObject instance.

Parameters

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

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

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

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:

container.setChildIndex(container.getChildAt(1), 0);

This code results in the following arrangement of objects:

Parameters

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

Three-dimensional display objects follow the mouse and Sprite.startDrag() 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.

Parameters

Ends the startDrag() method. A sprite that was made draggable with the startDrag() method remains draggable until a stopDrag() method is added, or until another sprite becomes draggable. Only one sprite is draggable at a time.

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

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