dispatchEvent()™

Today I’d like to talk about a basic technique that’s a little deceptive when migrating from AS2 to AS3: creating a clickable button from a Sprite or MovieClip.

So you create a new Sprite or custom view class that subclasses Sprite. For purposes of argument, here’s a simple button class:

package
{
    import flash.display.Sprite;
    import flash.filters.BevelFilter;

    public class CustomButton extends Sprite
    {
        public function CustomButton(width:Number = 100, height:Number = 20)
        {
            super();
            graphics.beginFill(0xaaaaaa);
            graphics.drawRoundRect(0, 0, width, height, 6, 6);
            graphics.endFill();
            filters = [new BevelFilter(2)];
        }
    }
}

Then you do two things new to AS3. You add it to your display list, and you attach an event listener:

var button:CustomButton = new CustomButton();
addChild(button);
button.addEventListener(MouseEvent.CLICK, onButtonClick);

You’ll notice that (if you do something in onButtonClick) the button is functional. But the problem is: no hand cursor! What the devil?

For a second let’s recall AS2. To get our little pointy finger cursor, all we had to do was add an onRelease callback to the MovieClip or MovieClip subclass. The code above proves the analog of this in AS3 does not apply. We didn’t automatically get a hand cursor by virtue of adding a CLICK listener.

Remember, though, in AS2, there was a property on MovieClips called useHandCursor? Setting this to false could disable the hand cursor on that object. Well, Sprites and MovieClips still have this property in AS3. You might think: why not set this to true? Unfortunately, that’s not it either.

The proper way to make a Sprite/MovieClip show the system hand cursor when the mouse is over it is to use the new buttonMode property. See it in LiveDocs here.

buttonMode tells a Sprite if it should behave like a button or not. It defaults to false: even if you have event listeners set on the Sprite, it will not behave like a button. You need to manually set buttonMode to true.

“Behaving like a button” means three things.

1. The system hand cursor is used.
2. The item appears in the tab order.
3. When the item has tab focus and you press space, it broadcasts the CLICK event.
4. (Minor) if you have _over, _up, and _down frame labels they will be used as button states.

As far as hand cursors go, useHandCursor can control whether the hand cursor is used with the object or not, but it means nothing if buttonMode is not set.

tabEnabled can set whether the item appears in the tab order. This property doesn’t require buttonMode to be true to take effect. In other words, you can have something in the tab ordering without it needing to be a button. But remember, without buttonMode, when you tab to the item and press space, it won’t trigger a CLICK event.

Some problems we run into: If your clickable object contains anything else clickable, the target of those events will be the inner object. Furthermore, if you have a TextField inside of a button mode Sprite, the mouse cursor won’t appear as a hand cursor above that TextField, even if you have no event listeners on it and it’s not selectable. You can see this in the demonstration below. Try clicking inside the flash movie and tabbing around as well. The button mode button inside button 1 (on the left) is getting in the tab order, and the text field inside button 2 (on the right) is stealing the cursor type.

In order to fix these issues, if they are indeed problematic, you can use these additional properties of InteractiveObject and DisplayObjectContainer.

tabEnabled

Whether this item can be tabbed to.

tabChildren

Whether the children of this item can be tabbed to.

mouseEnabled

Whether this item accepts mouse events.

mouseChildren

Whether the children of this item accept mouse events.

By setting mouseChildren to false, you can treat any complex compositions of objects as one mouse target, even if the inner items would otherwise be clickable.

Play around with the example to see how these properties can affect the mouse cursor, ability to be tabbed to, and the target of events.

In short: buttonMode makes a Sprite a button. useHandCursor is only meant to override behavior set by buttonMode. You can also make buttons by extending the SimpleButton class.