ButtonEventHandler Documentation

Author: Trevor McCauley
Last Modified: 4/05/08 3:16:02

Summary

ButtonEventHandler class:

- description

ButtonEventHandler Properties:

- autoUpdateArrangement
- overlapBlocksEvents

ButtonEventHandler Methods:

- initialize
- uninitialize
- getEventObject
- updateArrangement

ButtonEventHandler class

version: 0.9.7

description:

The ButtonEventHandler class allows for timeline-based instances (MovieClips) to receive button events and allows for those events to bubble up to parent clips. This is contrary to normal button event behavior (Buttons and MovieClips) which starts at the parent clip, or the first parent clip with any kind of button event assigned to it, and prevents any child clips from receiving any button events at all. A list of all supported events are as follows:

ButtonEventHandler uses onEnterFrame and hitTest to determine what events are fired and when. This allows it to bypass the restriction of normal button event handling, however, because of this, it is also more CPU intensive than normal button events. Some differences between using ButtonEventHandler and normal button event handers: To enable a movie clip to receive events from ButtonEventHandler, you must first initialize it with ButtonEventHandler.initialize (note that movie clips with child clips that have already been initialized will automatically be initialized themselves). The initialize method returns a ButtonEvent instance which is used to handle events sent managed by ButtonEventHandler. Using that instance's addEventListener method, you can register objects to receive events detected by ButtonEventHandler relating to the movie clip initialized. The ButtonEvent object returned from initialization is automatically set as a listener to itself (and each event recognized by ButtonEventHandler). The event object passed to listeners for those events will be the respective ButtonEvent instance.

ButtonEventHandler Properties:

autoUpdateArrangement

Determines whether or not arrangement for handled movie clips is automatically updated every frame. If depths are altered for movie clips receiving events, this should be kept false.

overlapBlocksEvents

Determines whether or not overlapping prevents events for objects in the same timeline (no parent/child relationships) from triggering. If true, the behavior is like that of normal Flash buttons where buttons above other buttons, prevent the buttons below from receiving events.

ButtonEventHandler Methods:

initialize

description: Initializes a target timeline instance (MovieClip) to be registered for receiving events from the ButtonEventHandler class. When initialized, the target as well as all its parents are initialized too, if not already. The returned ButtonEvent object can be used to handle received events.

usage: event:ButtonEvent = ButtonEventHandler.initialize(target:MovieClip);

parameters:

returns: ButtonEvent object associated with the target movie clip passed. This is the same object sent to event handlers when they are called.

uninitialize

description: Removes the target movie clip from initialization preventing from receiving further events from ButtonEventHandler. Any child movie clips are removed along with target.

usage: success:Boolean = ButtonEventHandler.initialize(target:MovieClip);

parameters:

returns: True or false depending on whether or not the removal was successful.

getEventObject

description: Returns an event object associated with the target movie clip. If no ButtonEvent is associated with the target, the target will be initialized and a new ButtonEvent object will be created and returned.

usage: event:ButtonEvent = ButtonEventHandler.getEventObject(movie:MovieClip);

parameters:

returns: ButtonEvent object associated with the target movie clip passed. This is the same object sent to event handlers when they are called.

updateArrangement

description: Updates the arrangement and precedence of movie clips handled by ButtonEventHandler. This will automatically be called every frame if autoUpdateArrangement is true. You would only need to call this if autoUpdateArrangement is false and you've altered the depths of any movie clips receiving events from ButtonEventHandler.

usage: ButtonEventHandler.updateArrangement();

parameters:

returns: No return specified