ActionScript 3.0 Language and Components Reference | All Packages | All Classes | Language Elements | Index | Appendixes | Conventions | Frames No Frames |
Sprite

Package | flash.display
Class | public class Sprite
Inheritance | Sprite DisplayObjectContainer InteractiveObject DisplayObject EventDispatcher Object
Subclasses | MovieClip

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

The Sprite class is a basic display list building block: a display list node that can display graphics and can also contain children.

A Sprite object is similar to a movie clip, but does not have a timeline. Sprite is an appropriate base class for objects that do not require timelines. For example, Sprite would be a logical base class for user interface (UI) components that typically do not use the timeline.

The Sprite class is new in ActionScript 3.0. It provides an alternative to the functionality of the MovieClip class, which retains all the functionality of previous ActionScript releases to provide backward compatibility.

View the examples

See also

Core display classes

Public Properties
Hide Inherited Public Properties
Show Inherited Public Properties

| Property | Defined By
--- | --- | ---
|  | accessibilityProperties : AccessibilityProperties The current accessibility options for this display object. | DisplayObject
|  | alpha : Number Indicates the alpha transparency value of the object specified. | DisplayObject
|  | blendMode : String A value from the BlendMode class that specifies which blend mode to use. | DisplayObject
|  | buttonMode : Boolean Specifies the button mode of this sprite. | Sprite
|  | cacheAsBitmap : Boolean If set to true, Flash Player caches an internal bitmap representation of the display object. | DisplayObject
|  | constructor : Object A reference to the class object or constructor function for a given object instance. | Object
|  | contextMenu : ContextMenu Specifies the context menu associated with this object. | InteractiveObject
|  | doubleClickEnabled : Boolean Specifies whether the object receives doubleClick events. | InteractiveObject
|  | dropTarget : DisplayObject [read-only] Specifies the display object over which the sprite is being dragged, or on which the sprite was dropped. | Sprite
|  | filters : Array An indexed array that contains each filter object currently associated with the display object. | DisplayObject
|  | focusRect : Object Specifies whether this object displays a focus rectangle. | InteractiveObject
|  | graphics : Graphics [read-only] Specifies the Graphics object that belongs to this sprite where vector drawing commands can occur. | Sprite
|  | height : Number Indicates the height of the display object, in pixels. | DisplayObject
|  | hitArea : Sprite Designates another sprite to serve as the hit area for a sprite. | Sprite
|  | loaderInfo : LoaderInfo [read-only] Returns a LoaderInfo object containing information about loading the file to which this display object belongs. | DisplayObject
|  | mask : DisplayObject The calling display object is masked by the specified mask object. | DisplayObject
|  | mouseChildren : Boolean Determines whether or not the children of the object are mouse enabled. | DisplayObjectContainer
|  | mouseEnabled : Boolean Specifies whether this object receives mouse messages. | InteractiveObject
|  | mouseX : Number [read-only] Indicates the x coordinate of the mouse position, in pixels. | DisplayObject
|  | mouseY : Number [read-only] Indicates the y coordinate of the mouse position, in pixels. | DisplayObject
|  | name : String Indicates the instance name of the DisplayObject. | DisplayObject
|  | numChildren : int [read-only] Returns the number of children of this object. | DisplayObjectContainer
|  | opaqueBackground : Object Specifies whether the display object is opaque with a certain background color. | DisplayObject
|  | parent : DisplayObjectContainer [read-only] Indicates the DisplayObjectContainer object that contains this display object. | DisplayObject
|  | prototype : Object [static] A reference to the prototype object of a class or function object. | Object
|  | root : DisplayObject [read-only] 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. | DisplayObject
|  | rotation : Number Indicates the rotation of the DisplayObject instance, in degrees, from its original orientation. | DisplayObject
|  | scale9Grid : Rectangle The current scaling grid that is in effect. | DisplayObject
|  | scaleX : Number Indicates the horizontal scale (percentage) of the object as applied from the registration point. | DisplayObject
|  | scaleY : Number Indicates the vertical scale (percentage) of an object as applied from the registration point of the object. | DisplayObject
|  | scrollRect : Rectangle The scroll rectangle bounds of the display object. | DisplayObject
|  | soundTransform : SoundTransform Controls sound within this sprite. | Sprite
|  | stage : Stage [read-only] The Stage of the display object. | DisplayObject
|  | tabChildren : Boolean Determines whether the children of the object are tab enabled. | DisplayObjectContainer
|  | tabEnabled : Boolean Specifies whether this object is in the tab order. | InteractiveObject
|  | tabIndex : int Specifies the tab ordering of objects in a SWF file. | InteractiveObject
|  | textSnapshot : TextSnapshot [read-only] Returns a TextSnapshot object for this DisplayObjectContainer instance. | DisplayObjectContainer
|  | transform : Transform An object with properties pertaining to a display object's matrix, color transform, and pixel bounds. | DisplayObject
|  | useHandCursor : Boolean 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. | Sprite
|  | visible : Boolean Whether or not the display object is visible. | DisplayObject
|  | width : Number Indicates the width of the display object, in pixels. | DisplayObject
|  | x : Number Indicates the x coordinate of the DisplayObject instance relative to the local coordinates of the parent DisplayObjectContainer. | DisplayObject
|  | y : Number Indicates the y coordinate of the DisplayObject instance relative to the local coordinates of the parent DisplayObjectContainer. | DisplayObject

Public Methods
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined By
--- | --- | ---
|  | Sprite() Creates a new Sprite instance. | Sprite
|  | addChild(child:DisplayObject):DisplayObject Adds a child DisplayObject instance to this DisplayObjectContainer instance. | DisplayObjectContainer
|  | addChildAt(child:DisplayObject, index:int):DisplayObject Adds a child DisplayObject instance to this DisplayObjectContainer instance. | DisplayObjectContainer
|  | addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void Registers an event listener object with an EventDispatcher object so that the listener receives notification of an event. | EventDispatcher
|  | areInaccessibleObjectsUnderPoint(point:Point):Boolean 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. | DisplayObjectContainer
|  | contains(child:DisplayObject):Boolean Determines whether the specified display object is a child of the DisplayObjectContainer instance or the instance itself. | DisplayObjectContainer
|  | dispatchEvent(event:Event):Boolean Dispatches an event into the event flow. | EventDispatcher
|  | getBounds(targetCoordinateSpace:DisplayObject):Rectangle Returns a rectangle that defines the area of the display object relative to the coordinate system of the targetCoordinateSpace object. | DisplayObject
|  | getChildAt(index:int):DisplayObject Returns the child display object instance that exists at the specified index. | DisplayObjectContainer
|  | getChildByName(name:String):DisplayObject Returns the child display object that exists with the specified name. | DisplayObjectContainer
|  | getChildIndex(child:DisplayObject):int Returns the index position of a child DisplayObject instance. | DisplayObjectContainer
|  | getObjectsUnderPoint(point:Point):Array Returns an array of objects that lie under the specified point and are children (or grandchildren, and so on) of this DisplayObjectContainer instance. | DisplayObjectContainer
|  | 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. | DisplayObject
|  | globalToLocal(point:Point):Point Converts the point object from the Stage (global) coordinates to the display object's (local) coordinates. | DisplayObject
|  | hasEventListener(type:String):Boolean Checks whether the EventDispatcher object has any listeners registered for a specific type of event. | EventDispatcher
|  | hasOwnProperty(name:String):Boolean Indicates whether an object has a specified property defined. | Object
|  | hitTestObject(obj:DisplayObject):Boolean Evaluates the display object to see if it overlaps or intersects with the obj display object. | DisplayObject
|  | hitTestPoint(x:Number, y:Number, shapeFlag:Boolean = false):Boolean Evaluates the display object to see if it overlaps or intersects with the point specified by the x and y parameters. | DisplayObject
|  | isPrototypeOf(theClass:Object):Boolean Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter. | Object
|  | localToGlobal(point:Point):Point Converts the point object from the display object's (local) coordinates to the Stage (global) coordinates. | DisplayObject
|  | propertyIsEnumerable(name:String):Boolean Indicates whether the specified property exists and is enumerable. | Object
|  | removeChild(child:DisplayObject):DisplayObject Removes the specified child DisplayObject instance from the child list of the DisplayObjectContainer instance. | DisplayObjectContainer
|  | removeChildAt(index:int):DisplayObject Removes a child DisplayObject from the specified index position in the child list of the DisplayObjectContainer. | DisplayObjectContainer
|  | removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void Removes a listener from the EventDispatcher object. | EventDispatcher
|  | setChildIndex(child:DisplayObject, index:int):void Changes the position of an existing child in the display object container. | DisplayObjectContainer
|  | setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void Sets the availability of a dynamic property for loop operations. | Object
|  | startDrag(lockCenter:Boolean = false, bounds:Rectangle = null):void Lets the user drag the specified sprite. | Sprite
|  | stopDrag():void Ends the startDrag() method. | Sprite
|  | swapChildren(child1:DisplayObject, child2:DisplayObject):void Swaps the z-order (front-to-back order) of the two specified child objects. | DisplayObjectContainer
|  | 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. | DisplayObjectContainer
|  | toString():String Returns the string representation of the specified object. | Object
|  | valueOf():Object Returns the primitive value of the specified object. | Object
|  | willTrigger(type:String):Boolean Checks whether an event listener is registered with this EventDispatcher object or any of its ancestors for the specified event type. | EventDispatcher

Events
Hide Inherited Events
Show Inherited Events

| Event | Summary | Defined By
--- | --- | --- | ---
|  | activate | Dispatched when Flash Player gains operating system focus and becomes active. | EventDispatcher
|  | added | Dispatched when a display object is added to the display list. | DisplayObject
|  | addedToStage | Dispatched when a display object is added to the on stage display list, either directly or through the addition of a sub tree in which the display object is contained. | DisplayObject
|  | clear | Dispatched when the user selects 'Clear' (or 'Delete') from the text context menu. | InteractiveObject
|  | click | Dispatched when a user presses and releases the main button of the user's pointing device over the same InteractiveObject. | InteractiveObject
|  | copy | Dispatched when the user activates the platform specific accelerator key combination for a copy operation or selects 'Copy' from the text context menu. | InteractiveObject
|  | cut | Dispatched when the user activates the platform specific accelerator key combination for a cut operation or selects 'Cut' from the text context menu. | InteractiveObject
|  | deactivate | Dispatched when Flash Player loses operating system focus and is becoming inactive. | EventDispatcher
|  | doubleClick | Dispatched when a user presses and releases the main button of a pointing device twice in rapid succession over the same InteractiveObject when that object's doubleClickEnabled flag is set to true. | InteractiveObject
|  | enterFrame | Dispatched when the playhead is entering a new frame. | DisplayObject
|  | exitFrame | Dispatched when the playhead is exiting the current frame. | DisplayObject
|  | focusIn | Dispatched after a display object gains focus. | InteractiveObject
|  | focusOut | Dispatched after a display object loses focus. | InteractiveObject
|  | frameConstructed | Dispatched after the constructors of frame display objects have run but before frame scripts have run. | DisplayObject
|  | keyDown | Dispatched when the user presses a key. | InteractiveObject
|  | keyFocusChange | Dispatched when the user attempts to change focus by using keyboard navigation. | InteractiveObject
|  | keyUp | Dispatched when the user releases a key. | InteractiveObject
|  | mouseDown | Dispatched when a user presses the pointing device button over an InteractiveObject instance in the Flash Player window. | InteractiveObject
|  | mouseFocusChange | Dispatched when the user attempts to change focus by using a pointer device. | InteractiveObject
|  | mouseMove | Dispatched when a user moves the pointing device while it is over an InteractiveObject. | InteractiveObject
|  | mouseOut | Dispatched when the user moves a pointing device away from an InteractiveObject instance. | InteractiveObject
|  | mouseOver | Dispatched when the user moves a pointing device over an InteractiveObject instance in the Flash Player window. | InteractiveObject
|  | mouseUp | Dispatched when a user releases the pointing device button over an InteractiveObject instance in the Flash Player window. | InteractiveObject
|  | mouseWheel | Dispatched when a mouse wheel is spun over an InteractiveObject instance in the Flash Player window. | InteractiveObject
|  | paste | Dispatched when the user activates the platform specific accelerator key combination for a paste operation or selects 'Paste' from the text context menu. | InteractiveObject
|  | removed | Dispatched when a display object is about to be removed from the display list. | DisplayObject
|  | removedFromStage | Dispatched when a display object is about to be removed from the display list, either directly or through the removal of a sub tree in which the display object is contained. | DisplayObject
|  | render | Dispatched when the display list is about to be updated and rendered. | DisplayObject
|  | rollOut | Dispatched when the user moves a pointing device away from an InteractiveObject instance. | InteractiveObject
|  | rollOver | Dispatched when the user moves a pointing device over an InteractiveObject instance. | InteractiveObject
|  | selectAll | Dispatched when the user activates the platform specific accelerator key combination for a select all operation or selects 'Select All' from the text context menu. | InteractiveObject
|  | tabChildrenChange | Dispatched when the value of the object's tabChildren flag changes. | InteractiveObject
|  | tabEnabledChange | Dispatched when the object's tabEnabled flag changes. | InteractiveObject
|  | tabIndexChange | Dispatched when the value of the object's tabIndex property changes. | InteractiveObject

Property Detail

buttonMode | property

`buttonMode:Boolean` [read-write]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

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.

Implementation
`public function get buttonMode():Boolean`
`public function set buttonMode(value:Boolean):void`

See also

SimpleButton
Sprite.useHandCursor
InteractiveObject.tabEnabled
DisplayObjectContainer.mouseChildren
Example
The following example creates two sprites and sets the `buttonMode` property to `true` for one and `false` for the other. When you compile and run the application, both sprites respond to mouse events, but only the one in which `buttonMode` is set to `true` uses the hand cursor and is included in the tab order:

    import flash.display.Sprite;
    import flash.events.MouseEvent;

    var circle1:Sprite = new Sprite();
    circle1.graphics.beginFill(0xFFCC00);
    circle1.graphics.drawCircle(40, 40, 40);
    circle1.buttonMode = true;
    circle1.addEventListener(MouseEvent.CLICK, clicked);

    var circle2:Sprite = new Sprite();
    circle2.graphics.beginFill(0xFFCC00);
    circle2.graphics.drawCircle(120, 40, 40);
    circle2.buttonMode = false;
    circle2.addEventListener(MouseEvent.CLICK, clicked);

    function clicked(event:MouseEvent):void {
        trace ("Click!");
    }

    addChild(circle1);
    addChild(circle2);

dropTarget | property |

`dropTarget:DisplayObject` [read-only]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

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

Implementation
`public function get dropTarget():DisplayObject`

See also

startDrag()
stopDrag()
Example
The following example creates a `circle` sprite and two `target` sprites. The `startDrag()` method is called on the `circle` sprite when the user positions the cursor over the sprite and presses the mouse button, and the `stopDrag()` method is called when the user releases the mouse button. This lets the user drag the sprite. On release of the mouse button, the `mouseRelease()` method is called, which in turn traces the `name` of the `dropTarget` object — the one to which the user dragged the `circle` sprite:

    import flash.display.Sprite;
    import flash.events.MouseEvent;

    var circle:Sprite = new Sprite();
    circle.graphics.beginFill(0xFFCC00);
    circle.graphics.drawCircle(0, 0, 40);

    var target1:Sprite = new Sprite();
    target1.graphics.beginFill(0xCCFF00);
    target1.graphics.drawRect(0, 0, 100, 100);
    target1.name = "target1";

    var target2:Sprite = new Sprite();
    target2.graphics.beginFill(0xCCFF00);
    target2.graphics.drawRect(0, 200, 100, 100);
    target2.name = "target2";

    addChild(target1);
    addChild(target2);
    addChild(circle);

    circle.addEventListener(MouseEvent.MOUSE_DOWN, mouseDown)

    function mouseDown(event:MouseEvent):void {
        circle.startDrag();
    }
    circle.addEventListener(MouseEvent.MOUSE_UP, mouseReleased);

    function mouseReleased(event:MouseEvent):void {
        circle.stopDrag();
        trace(circle.dropTarget.name);
    }

graphics | property |

`graphics:Graphics` [read-only]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

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

Implementation
`public function get graphics():Graphics`
Example
The following example creates a `circle` sprite and uses its `graphics` property to draw a circle with a yellow (0xFFCC00) fill:

    import flash.display.Sprite;

    var circle:Sprite = new Sprite();
    circle.graphics.beginFill(0xFFCC00);
    circle.graphics.drawCircle(40, 40, 40);
    addChild(circle);

hitArea | property |

`hitArea:Sprite` [read-write]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

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.

Implementation
`public function get hitArea():Sprite`
`public function set hitArea(value:Sprite):void`
Example
The following example creates a `circle` sprite and a `square` sprite. The `square` sprite is the `hitArea` for the `circle` sprite. So when the user clicks the `square` sprite, the `circle` sprite dispatches a `click` event:

    import flash.display.Sprite;
    import flash.events.MouseEvent;

    var circle:Sprite = new Sprite();
    circle.graphics.beginFill(0xFFCC00);
    circle.graphics.drawCircle(0, 0, 40);

    var square:Sprite = new Sprite();
    square.graphics.beginFill(0xCCFF00);
    square.graphics.drawRect(200, 0, 100, 100);

    circle.hitArea = square;
    square.mouseEnabled = false;

    circle.addEventListener(MouseEvent.CLICK, clicked);

    function clicked(event:MouseEvent):void{
        trace(event.target == circle); // true
        trace(event.target == square); // false
    }

    addChild(circle);
    addChild(square);

soundTransform | property |

`soundTransform:SoundTransform` [read-write]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

Controls sound within this sprite.

Implementation
`public function get soundTransform():SoundTransform`
`public function set soundTransform(value:SoundTransform):void`

See also

flash.media.SoundTransform
Example
The following example creates a sprite named `container` and adds a Loader object to its child list. The Loader object loads a SWF file. When the user clicks the link in the `tf` text field `true`, the `mute()` method sets the `volume` property of the `soundTransform` property of the `container` sprite:

    import flash.display.Sprite;
    import flash.display.Loader;
    import flash.events.IOErrorEvent;
    import flash.events.MouseEvent;
    import flash.net.URLRequest;
    import flash.text.TextField;
    import flash.media.SoundTransform;

    var container:Sprite = new Sprite();
    addChild(container);

    var ldr:Loader = new Loader;
    var urlReq:URLRequest = new URLRequest("SoundPlayer.swf");
    ldr.load(urlReq);

    container.addChild(ldr);
    ldr.contentLoaderInfo.addEventListener(IOErrorEvent.IO_ERROR, urlNotFound);

    var tf:TextField = new TextField();
    tf.htmlText = "<a href = 'event:Mute'>Mute / Unmute</a>";
    addChild(tf);

    var mySoundTransform:SoundTransform = new SoundTransform();
    mySoundTransform.volume = 1;

    tf.addEventListener(MouseEvent.CLICK, mute);

    function mute(event:MouseEvent):void {
        if (mySoundTransform.volume == 0) {
            mySoundTransform.volume = 1;
        } else {
            mySoundTransform.volume = 0;
        }
        container.soundTransform = mySoundTransform;
    }

    function urlNotFound(event:IOErrorEvent):void {
        trace("The URL was not found.");
    }

useHandCursor | property |

`useHandCursor:Boolean` [read-write]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

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.

Implementation
`public function get useHandCursor():Boolean`
`public function set useHandCursor(value:Boolean):void`

See also

buttonMode
DisplayObjectContainer.mouseChildren
Example
The following example creates two sprites and sets the `buttonMode` property to `true` for both, yet it sets the `useHandCursor` property to `true` for one and `false` for the other. When you compile and run the application, both sprites respond as buttons (and are included in the tab order), but only the one in which `useHandCursor` is set to `true` uses the hand cursor:

    import flash.display.Sprite;
    import flash.events.MouseEvent;

    var circle1:Sprite = new Sprite();
    circle1.graphics.beginFill(0xFFCC00);
    circle1.graphics.drawCircle(40, 40, 40);
    circle1.buttonMode = true;
    circle1.useHandCursor = true;
    circle1.addEventListener(MouseEvent.CLICK, clicked);

    var circle2:Sprite = new Sprite();
    circle2.graphics.beginFill(0xFFCC00);
    circle2.graphics.drawCircle(120, 40, 40);
    circle2.buttonMode = true;
    circle2.useHandCursor = false;
    circle2.addEventListener(MouseEvent.CLICK, clicked);

    function clicked(event:MouseEvent):void {
        trace ("Click!");
    }

    addChild(circle1);
    addChild(circle2);

Constructor Detail

Sprite | () | Constructor

`public function Sprite()`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

Creates a new Sprite instance. After you create the Sprite instance, call the `DisplayObjectContainer.addChild()` or `DisplayObjectContainer.addChildAt()` method to add the Sprite to a parent DisplayObjectContainer.

Method Detail

startDrag | () | method

`public function startDrag(lockCenter:Boolean = false, bounds:Rectangle = null):void`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

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.

Parameters

| `lockCenter:Boolean` (default = `false`)`` — Specifies whether the draggable sprite is locked to the center of the mouse position (`true`), or locked to the point where the user first clicked the sprite (`false`).
| `bounds:Rectangle` (default = `null`)`` — Value relative to the coordinates of the Sprite's parent that specify a constraint rectangle for the Sprite.

See also

dropTarget
stopDrag()
Example
The following example creates a `circle` sprite and two `target` sprites. The `startDrag()` method is called on the `circle` sprite when the user positions the cursor over the sprite and presses the mouse button, and the `stopDrag()` method is called when the user releases the mouse button. This lets the user drag the sprite. On release of the mouse button, the `mouseRelease()` method is called, which in turn traces the `name` of the `dropTarget` object — the one to which the user dragged the `circle` sprite:

    import flash.display.Sprite;
    import flash.events.MouseEvent;

    var circle:Sprite = new Sprite();
    circle.graphics.beginFill(0xFFCC00);
    circle.graphics.drawCircle(0, 0, 40);

    var target1:Sprite = new Sprite();
    target1.graphics.beginFill(0xCCFF00);
    target1.graphics.drawRect(0, 0, 100, 100);
    target1.name = "target1";

    var target2:Sprite = new Sprite();
    target2.graphics.beginFill(0xCCFF00);
    target2.graphics.drawRect(0, 200, 100, 100);
    target2.name = "target2";

    addChild(target1);
    addChild(target2);
    addChild(circle);

    circle.addEventListener(MouseEvent.MOUSE_DOWN, mouseDown)

    function mouseDown(event:MouseEvent):void {
        circle.startDrag();
    }
    circle.addEventListener(MouseEvent.MOUSE_UP, mouseReleased);

    function mouseReleased(event:MouseEvent):void {
        circle.stopDrag();
        trace(circle.dropTarget.name);
    }

stopDrag | () | method |

`public function stopDrag():void`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

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.

See also

dropTarget
startDrag()
Example
The following example creates a `circle` sprite and two `target` sprites. The `startDrag()` method is called on the `circle` sprite when the user positions the cursor over the sprite and presses the mouse button, and the `stopDrag()` method is called when the user releases the mouse button. This lets the user drag the sprite. On release of the mouse button, the `mouseRelease()` method is called, which in turn traces the `name` of the `dropTarget` object — the one to which the user dragged the `circle` sprite:

    import flash.display.Sprite;
    import flash.events.MouseEvent;

    var circle:Sprite = new Sprite();
    circle.graphics.beginFill(0xFFCC00);
    circle.graphics.drawCircle(0, 0, 40);

    var target1:Sprite = new Sprite();
    target1.graphics.beginFill(0xCCFF00);
    target1.graphics.drawRect(0, 0, 100, 100);
    target1.name = "target1";

    var target2:Sprite = new Sprite();
    target2.graphics.beginFill(0xCCFF00);
    target2.graphics.drawRect(0, 200, 100, 100);
    target2.name = "target2";

    addChild(target1);
    addChild(target2);
    addChild(circle);

    circle.addEventListener(MouseEvent.MOUSE_DOWN, mouseDown)

    function mouseDown(event:MouseEvent):void {
        circle.startDrag();
    }
    circle.addEventListener(MouseEvent.MOUSE_UP, mouseReleased);

    function mouseReleased(event:MouseEvent):void {
        circle.stopDrag();
        trace(circle.dropTarget.name);
    }

Examples How to use examples
SpriteExample.as
The following example uses the SpriteExample class to draw an orange square on the stage, and then dispatches events whenever the user clicks or drags the square. This task is accomplished by performing the following steps:

1. Declare the `size` property (100 x 100 pixels) and the background color (orange) for later use in drawing the square.
2. The constructor then creates a new `child` Sprite object and uses it to add two event listeners and their associated methods: `mouseDownHandler()` and `mouseUpHandler()`.
3. The `child` Sprite object is then passed to the `draw()` method, which draws the orange square.
4. The child is then placed on the display list by a call to the `addChild()` method.
5. The event listeners work as follows:
   - `mouseDownHandler()`: when the user clicks the Sprite object, this method adds a mouseMove event listener, the `mouseMoveHandler()` method, which processes the mouse moves. Then the `startDrag()` method is called, which allows the Sprite object to be dragged.
   - `mouseUpHandler()`: when the mouse button is released, the mouseMove event listener is removed and the `stopDrag()` method is called, which freezes the orange square in place.
   - `mouseMoveHandler`: as long as the left mouse button is being held down, this method instructs the player to continuously redraw the orange square.

Note: Each of the event listener methods declares a local `sprite` variable, which is assigned the `target` property of the event.

    package {
        import flash.display.Sprite;
        import flash.events.*;

        public class SpriteExample extends Sprite {
            private var size:uint    = 100;
            private var bgColor:uint = 0xFFCC00;

            public function SpriteExample() {
                var child:Sprite = new Sprite();
                child.addEventListener(MouseEvent.MOUSE_DOWN, mouseDownHandler);
                child.addEventListener(MouseEvent.MOUSE_UP, mouseUpHandler);
                draw(child);
                addChild(child);
            }

            private function mouseDownHandler(event:MouseEvent):void {
                trace("mouseDownHandler");
                var sprite:Sprite = Sprite(event.target);
                sprite.addEventListener(MouseEvent.MOUSE_MOVE, mouseMoveHandler);
                sprite.startDrag();
            }

            private function mouseUpHandler(event:MouseEvent):void {
                trace("mouseUpHandler");
                var sprite:Sprite = Sprite(event.target);
                sprite.removeEventListener(MouseEvent.MOUSE_MOVE, mouseMoveHandler);
                sprite.stopDrag();
            }

            private function mouseMoveHandler(event:MouseEvent):void {
                trace("mouseMoveHandler");
                event.updateAfterEvent();
            }

            private function draw(sprite:Sprite):void {
                sprite.graphics.beginFill(bgColor);
                sprite.graphics.drawRect(0, 0, size, size);
                sprite.graphics.endFill();
            }
        }
    }

Submit Feedback on LiveDocs
© 2004-2008 Adobe Systems Incorporated. All rights reserved.
Tue May 20 2008, 04:02 AM -07:00