Recipe 11.12. Creating Simple Drag-and-Drop Functionality

Problem

You want to be able to create a draggable movie clip.

Solution

Use the startDrag( ) and stopDrag( ) methods.

Discussion

You can cause a movie clip to follow the mouse pointer using the startDrag( ) method, and you can tell the movie clip to stop following the mouse pointer using the stopDrag( ) method. Depending on the effect you want to create, you can use these methods in several different ways.

First of all, you can place the startDrag( ) method call on a frame to cause the movie clip to begin following the mouse pointer as soon as the playhead enters that frame. For example, if you place the action on the first frame of the movie, the specified movie clip will follow the pointer from the very beginning of playback:

	mClip.startDrag();

When you use the startDrag( ) method in this way, you'll usually specify a value for the first, optional parameter of the method. The first parameter is a Boolean value indicating whether the movie clip should snap to the pointer. The default value is false, which means that the movie clip will follow the mouse pointer at the same distance that existed between them at the time the method was invoked. For example, if the movie clip instance was on stage at 0,0 and the mouse pointer was at 300,300 when the method was invoked, wherever the user moves the pointer, the movie clip will be offset by 300 pixels up and to the left. However, if you specify the value TRue when you invoke the startDrag( ) method, the initial offset is disregarded, and Flash automatically snaps the center of the movie clip instance to the mouse pointer. The result is that the movie clip follows the mouse pointer with no offset. The effect can be used to create custom mouse cursors.

	mClip.startDrag(true);

In other cases, you don't want to start dragging the movie clip based on the playhead entering a frame, but rather based on the user's interaction. For example, if you create a puzzle using Flash, you want the pieces to be draggable only when the user clicks and drags them. In these cases, you want to enable dragging when the use clicks the mouse (a press event), and you want to stop dragging when the user releases the mouse. Therefore, you should place the startDrag( ) method call in an onPress( ) event handler method that you define for the movie clip instance, and you should place the stopDrag( ) method in the onRelease( ) event handler method you define for the movie clip instance:

	mClip.onPress = function():Void {
	  this.startDrag();
	};

	mClip.onRelease = function():Void {
	  this.stopDrag();
	};

In the preceding code example, there are a couple of things to notice. First of all, within the event handler methods, you reference the movie clip instance with the this keyword. The other thing to notice is that in the example, the startDrag( ) method does not have any parameters. In most simple drag-and-drop cases, you don't want the movie clip to snap to the mouse pointer. Instead, you want the movie clip to get dragged from whatever point the user clicks on it. On the other hand, if you do want the movie clip to snap to the mouse pointer, you can do so by specifying true as the first, optional parameter for the startDrag( ) method. The stopDrag( ) method never needs any parameters.

	mClip.onPress = function() {
	  this.startDrag(true);
	};

	mClip.onRelease = function() {
	  this.stopDrag();
	};