AS3 Dragging and Dropping Tutorial - AS3 startDrag() and AS3 stopDrag()

Exercise File:
as3-drag-and-drop.fla - Flash CS4/CS5
as3-drag-and-drop.fla - Flash CS3

In this tutorial, we're going to learn how to create simple AS3 drag and drop functionality using the AS3 startDrag() and AS3 stopDrag() methods. The exercise file can be downloaded from the link above, and the AS3 dragging and dropping code is provided below along with comments that explain the code.

[VIEW DEMO]

Here is the ActionScript 3 code:

circle_mc.addEventListener(MouseEvent.MOUSE_DOWN, drag);
square_mc.addEventListener(MouseEvent.MOUSE_DOWN, drag);
stage.addEventListener(MouseEvent.MOUSE_UP, drop);

function drag(e:MouseEvent):void
{
     e.target.startDrag(false, new Rectangle(75,50,350,250));
}

function drop(e:MouseEvent):void
{
     stopDrag();
}

Here's the same code for ActionScript 3 dragging and dropping, but with comments:

/*Use the AS3 startDrag() method of the MovieClip class in
order to let the user drag MovieClip instances all over the stage.

Example:
myMovieClip.startDrag();

You can call this method whenever the user presses on
a MovieClip instance, so that the user can start
dragging it once he or she presses on the MovieClip.
The event for that would be MouseEvent.MOUSE_DOWN.

To stop the user from being able to drag the MovieClip
instance, you use the AS3 stopDrag() method. You can call 
this whenever the user releases the mouse button so that 
the object being dragged will be released the same time 
the mouse button is released. The event for that would 
be MouseEvent.MOUSE_UP.

To summarize:
Call the AS3 startDrag() method whenever MOUSE_DOWN happens, and call
the AS3 stopDrag() method whenever MOUSE_UP happens. In other words,
enable dragging while the user is pressing on the movie
clip, and disable dragging when the user releases it. */

/*Add the MouseEvent.MOUSE_DOWN listeners to the MovieClip
instances that you'd like the user to be able to drag.*/
circle_mc.addEventListener(MouseEvent.MOUSE_DOWN, drag);
square_mc.addEventListener(MouseEvent.MOUSE_DOWN, drag);

/*Add the MouseEvent.MOUSE_UP listener to the stage.*/
stage.addEventListener(MouseEvent.MOUSE_UP, drop);

/*This is the event listener function for the MOUSE_DOWN
event, which enables dragging.*/
function drag(e:MouseEvent):void
{
     e.target.startDrag(false, new Rectangle(75,50,350,250));
     /*This will enable dragging for whichever object is
     currently being pressed.
 
     It accepts 2 parameters (these are optional):
 
     1. lockCenter:Boolean - true or false
     If set to true, the object's registration point locks
     to the mouse pointer. If false, whatever part of the
     object that was clicked on locks to the pointer.
 
     2. Bounds:Rectangle
     Lets you create a rectangular boundary that restricts where
     the object can be dragged. You create a rectangle
     object that will serve as the boundary:

     new Rectangle (x,y,width,height)

     This rectangle will not be seen. The rectangle shape
     that you see on the stage of this exercise file is 
     just a drawing to help illustrate where the 
     boundary is. Also, it's not the shape itself that
     stays inside the boundary, but the MovieClip instance's
     registration point. So parts of the MovieClip instance
     can still move beyond the boundary.*/
}

/*This is the event listener function for the MOUSE_UP
event, which disables dragging.*/
function drop(e:MouseEvent):void
{
     stopDrag();
     /*Simply call the stopDrag() method, and whichever
     object is currently being dragged will then be
     dropped.*/
}

/*Why add the MOUSE_UP event listener to the stage instead
of to the MovieClip instances?

As long as the mouse pointer is within the stage, then
we can be sure that the MOUSE_UP event will be detected.
The problem with adding the MOUSE_UP event listener
to any of the MovieClip instances is that sometimes, 
the MovieClip instance gets left behind when the user
drags too fast. If the user releases the mouse button
and the mouse pointer is NOT on the actual MovieClip
instance, then the MOUSE_UP event won't get dispatched.
This will cause the MovieClip instance to get stuck
to the mouse pointer even though the mouse button has 
already been released. So it would be better to add the 
event listener to the stage instead.*/

And that concludes this basic example on AS3 dragging and dropping using the AS3 startDrag() and the AS3 stopDrag() methods.