Recipe 9.7. Making Buttons Respond to Dragging and Releasing Off the Instance

Problem

You want your button to respond when a user clicks on the button and drags off of it and/or when the user releases the button after having dragged off of the button.

Solution

Use the onDragOff( ) and/or onReleaseOutside( ) event handler methods.

Discussion

Although the most common button events are click-and rollover-related events, you can also handle several other kinds of user actions. Among these events are the user actions of clicking on a button and dragging off of it, and clicking on a button, dragging off of it, and then releasing.

In order to understand how and when to use these additional events, consider first that the typical behavior of a button the responds to click releases is as follows: the user clicks on the button, and when they release, the actions are triggered. As long as the user has not yet released the button, they can change their mind by dragging the mouse pointer off the button before releasing it. At that point, when they release, the button actions are not triggered. Normally this is the behavior that you would want from a button. However, in some situations you want to make sure that the actions are also triggered when the user releases the button outside the button instance. For example, if the button is moving on the stage while the user clicks it, it may move out from under the mouse pointer before the user has the opportunity to release. Another good example is when creating sliders. Sliders are generally constrained to a certain region over which they can be dragged. If the user tries to drag the slider outside that region, the slider will stop at the boundary, but the mouse pointer will continue. If the user releases the button after having dragged off the button, you still want to handle the event. In these cases, you should also detect when the user releases outside using an onReleaseOutside( ) event handler method. The correct syntax is:

 btInstance.onReleaseOutside = function() {   // Actions to occur when the user releases the button outside the button instance. } 

In some situations, you might want to define different actions for a basic release and a release outside the button instance. However, in most cases you will want to define the same actions. Rather than define the same actions twice (once in the onRelease( ) method and once in the onReleaseOutside( ) method), you can simply assign the value of one method to the other. Here is an example:

 // First, define the onRelease( ) event handler method. btInstance.onRelease = function() {   // Actions to occur when the user releases the button outside the button instance. } // Next, assign the value of the onRelease( ) method to the onReleaseOutside( ) // method. So in either event, the same actions are invoked. btInstance.onReleaseOutside = btInstance.onRelease;