Handling Events

Cool Focus applets can notify your movie when particular events occur. This is optional, and if you're new to ActionScript you may prefer to ignore this page. However, you can use these events to create interactivity between the applet and other objects in your movie.

1. Callback Query

When an applet starts, it will query its container (_level0 in the example code we used previously) for event-handler callback functions. Most Cool Focus applets support three events:

link - the applet will notify the callback function when the user clicks a linking item in the applet, passing back the URL and Target specified for that item. Note that some applets such as Elevator allow URL parameters to be used to navigate the applet itself by using 'reserved words' such as '_back' and '_home'; in those cases, the applet will always handle them internally without calling back. Similarly if a URL is used to load a new datafile into the applet by specifying the URL as 'datafile(mydata.inf)', this will be also handled by the applet internally. Most (but not all) applets support the link event.
message - the applet notifies the callback function when a status-bar message should be displayed, passing the text of the message. Many applets allow you to define a status-bar message for each item, and other features such as Testmode use the status bar. All applets support the message event.
loaded - the applet notifies the callback function when it has finished loading, indicating that the properties it exposes are available for use. All applets support the loaded event.

If you don't define a callback for the link event, the applet will handle all links itself. However, if you don't define a callback for the message event, the messages will be ignored.

2. Answering the Callback Query

To use the callbacks, add this function to the object containing the applet (in our example, _level0):

function onSetCallback(sender, event)
{
   if (sender==example)
   {
      if (event=="link") return ExampleLink;
      else if (event=="message") return ExampleMessage;
      else if (event=="loaded") return ExampleLoaded;
   }
}

The name of this function must not change. The sender argument is the MovieClip object containing the applet (_level0.example here). The event argument is a string containing the name of the event: "link", "message" or "loaded", which will always be lowercase. You should return a function object which will receive the event callback, or null if the applet should handle these events itself.

Note that if you use several applets in the container, they will all query this function, so you can use the sender argument to determine which applet is sending the query (and, if necessary, return a different function for each applet).

3. Adding Event-Handler Functions

Finally you need to write the functions which will receive the event callbacks. For the link event the function should look like this:

function ExampleLink(sender, linkurl, linktarget)
{
trace("Link clicked in Example: " + linkurl + ", " + linktarget);
}

The three arguments passed to this function are:

sender

linkurl - the URL to link to (exactly as it was specified in your datafile).

linktarget - the frame target to be used for the link. This will be the Target defined for the item that was clicked, or the target defined in the applet's DefaultTarget parameter if the item didn't have an associated Target parameter.

For the message event the function should look like this:

function ExampleMessage(sender, message)
{
trace("Message received from Example: " + message);
}

The sender argument is the same as is used for the link event's function, explained above. The message argument is a string containing the message to be displayed.

Note that the string argument passed to the message event handler may be an empty string ("") or a space (" ") indicating that there is no text to display; it will not be a null value.

For the loaded event the function should look like this:

function ExampleLoaded(sender)
{
trace("Example has loaded");
}

The sender argument is the same as is used for the link event's function, explained above.

4. Additional Movie Control

You can use the two events to create interactivity between the applet and your own movie.

The "link" event
If you were using the applet to navigate between web pages (as it was designed to do), it would be simplest to define no callback for the link event and allow the applet to handle links itself. A more powerful way to use this event is to control some aspect of your own movie. For example, you could hide or show a particular object in response to a particular "linkurl" argument. Remember that the "linkurl" and "linktarget" arguments passed to your function will be whatever you assigned as URL and Target/DefaultTarget parameters for the clicked item in your datafile. Of course, they don't have to be URLs or frame names: they can be any identifier that you can evaluate.

The "message" event
The main purpose of the message event is to let you display "status bar" messages in a dynamic text field in your own movie. In many Cool Focus applets, you can define a 'Message' parameter to accompany an item, and the contents of that parameter will be passed to your function when the mouse moves over the item. When the mouse leaves the item, your function will be passed a space (" "). However, if you choose to, you can use the Message parameter to hold some other form of identifier, such as a number to represent the index of the item in the applet. This allows you to respond to mouse-over events (by receiving your identifier for the item under the mouse) and mouse-out events (by receiving a space) and take particular actions in your movie.