These components, like our version 1 component described in our book for Flash MX, use an event/listener mechanism to communicate with other objects. In version 2, these components use Flash's new addEventListener() mechanism, for compatibility with other aspects of Flash.

Listeners receive events by defining methods with the name of the event, and then registering with the components addEventListener() method. Alternatively, if the listener has a method named handleEvent, then the component sends the registered events to that method.

Like the Macromedia v2 components, the event is passed as an object to the listener, with properties target indicating the source component, and type indicating the event name. Where appropriate, components send values to accompany the event by setting the val property of the event object. Note: each component instance defines a single event object that it reuses for each event. Therefore, if you need to preserve a value from the event, copy it during the event handling.

The FMXIS Component set features two extensions to Macromedia's EventDispatcher mechanism. First, you can use the method addListener() to register a listener to receive all events from that component. Second, you can register a listener by string name rather than pointer, by using addProxyListener(). It is called a "proxy listener" because it sets up internally a mechanism to forward the event to the listener you designate. This type of listener is determined at the moment the event is generated, and hence allows for more complex manipulation of listeners. It also allows you to specify the listener by name in the component property panel, rather than having to remember to programmatically add the listener at initialization. The proxy listener mechanism also recognizes absolute and relative path designations such as _parent, _root, and _level.

Since we advocate a centralized event handling mechanism, we incorporated another feature not found in the default Macromedia v2 component architecture. You can change the name of the event in each component programmatically (via a component property) or via the component property panel. This avoids the situation in which two components have the same event name, for example, onChange. Each component help file will tell you the name of the property holding the event name.

how to add listeners to a component

To register a listener to receive all events from a component, for example, a listener called myListener with a button instance called myButton, you could use the addListener() method, as follows:

myButton.addListener(myListener);

All components automatically have this method because they derive from a base class, we call FMXISBase, which defines six methods:

1. addListener(inst)
2. addEventListener("event name", inst)
3. removeListener(inst)
4. removeEventListener("event name", inst)
5. addProxyListener("listener instance name")
6. removeProxyListener("listener instance name")

In the addListener example above, the listener is passed as the instance (inst) itself. For maximum flexibility you can choose whether to pass in the instance or simply the instance name (string), for example, myButton.addListener("myListener"). If you pass in the instance name, the listener is determined at event notification time.

Why would you pass in the instance name rather than the instance? If the instance is not defined yet when you want to place the addListener call. Also, just because we're super-nice, you can specify absolute (using _root, _global, and _level) or relative paths (using _parent) in the string. For example, if your listener is located a few movie clips above the current timeline, you could say myButton.addListener("_parent._parent.myListener").

If you are familiar with our components already you may realize that it's not just because we're super nice (but it never hurts to remind you of that, especially when we want you to pay us). The real reason is for convenience. We like having the ability to specify one listener in the component parameter panel for the component. That way, when you drag the component onto the Stage, you can type in the name of the listener instance (a string, coincidentally), and then you don't have to programmatically add at least the first listener.