Recipe 7.13 Creating a Draggable Movie Clip

7.13.1 Problem

You want a user to be able to drag a movie clip with the mouse.

7.13.2 Solution

Use the startDrag( ) method.

7.13.3 Discussion

You can allow the user to drag any movie clip with the mouse by invoking the startDrag( ) method on the clip. When invoked without parameters, startDrag( ) moves the movie clip relative to the pointer at the moment the method was invoked (the clip moves with the pointer but maintains the same distance from the pointer). You can see this for yourself.

The startDrag( ) method can be called with no parameters, as shown in the previous example. Optionally, you can also specify one Boolean parameter that explicitly tells the movie clip whether or not to snap to the mouse pointer:

_root.createEmptyMovieClip("circle_mc", 1);
circle_mc.lineStyle(1, 0x000000, 100);
circle_mc.drawCircle(100);

// Call the startDrag(  ) method from circle_mc, passing it the value true. This will
// cause the movie clip to automatically snap to the pointer. This use of the
// startDrag(  ) method can be useful for situations such as creating custom pointers
// (see Recipe 7.14).
circle_mc.startDrag(true);

Additionally, you can define a rectangular area within which the movie clip can be dragged by specifying values for the optional second through fifth parameters of the startDrag( ) method. The following is a complete list of possible parameters for startDrag( ):

lockCenter

If true, the movie clip snaps to the pointer; otherwise, the movie clip moves relative to its position to the pointer when the method was called.

left

A number indicating the leftmost pixel value to which the movie clip can be dragged.

top

A number indicating the topmost pixel value to which the movie clip can be dragged.

right

A number indicating the rightmost pixel value to which the movie clip can be dragged.

bottom

A number indicating the bottommost pixel value to which the movie clip can be dragged.

Here is an example that demonstrates the optional constraining feature of startDrag( ):

// Create a new movie clip and draw a circle within it.
_root.createEmptyMovieClip("circle_mc", 1);
circle_mc.lineStyle(1, 0x000000, 100);
circle_mc.drawCircle(100);

// Create a new movie clip and draw a rectangle within it at (200,200).
_root.createEmptyMovieClip("rectangle_mc", 2);
rectangle_mc.lineStyle(1, 0x000000, 100);
rectangle_mc.drawRectangle(300, 300);
rectangle_mc._x = 200;
rectangle_mc._y = 200;

// Determine the bounding area within which the circle can be dragged. Figure it such
// that the circle never leaves the boundaries of the rectangle.
rb = rectangle_mc.getBounds(_root);
l = rb.xMin + circle_mc._width/2;
r = rb.xMax - circle_mc._width/2;
t = rb.yMin + circle_mc._width/2;
b = rb.yMax - circle_mc._width/2;

// Invoke startDrag(  ) on circle_mc, telling it to snap circle_mc to the pointer and
// passing the bounding box limits within which circle_mc can be dragged.
circle_mc.startDrag(true, l, t, r, b);

The preceding code snippets show how to make a movie clip draggable from the beginning of playback. Another popular place for startDrag( ) is within an onPress( ) event handler method, where it makes a movie clip draggable as soon as it is clicked. To stop the clip from dragging when the user releases the mouse button, call stopDrag( ) from within the movie clip's onRelease( ) event handler method:

// Draw a filled circle movie clip.
_root.createEmptyMovieClip("circle_mc", 1);
circle_mc.lineStyle(1, 0x000000, 100);
circle_mc.beginFill(0, 100);
circle_mc.drawCircle(100);
circle_mc.endFill(  );

// When the user clicks anywhere on the circle, allow it to be dragged.
circle_mc.onPress = function (  ) {
  this.startDrag(  );
};

// When the user releases the mouse button, stop the drag action. This drops the
// movie clip on the Stage wherever the user released the mouse button.
circle_mc.onRelease = function (  ) {
  this.stopDrag(  );

};