Flash™ MX loadMovie Support

Cool Focus Flash applets are primarily designed to be used directly on an HTML page by using <object> and <embed> tags. However, they can also be incorporated into your own Flash movies if you use Flash MX (v6.0) or later. Some knowledge of ActionScript is needed, but the scripting is quite simple and explained below (using ActionScript 1.0).

1. Applet Registration

Only registered Cool Focus applets may be incorporated into your own movies. Unregistered applets may be used only for evaluation and site-development on a private server. In addition to our usual startup notice shown in unregistered applets, one of the links in the applet will be exchanged for a link to the Cool Focus web site until registered.

2. First Steps

Begin by creating your datafile in the usual way following the steps in this documentation. You must also include these 3 parameters:

Width=250
Height=180
Copyright=Cool Focus, www.coolfocus.com

If you use Design Studio to create your datafile, these parameters will be included automatically. You can easily adjust the Width and Height parameters later in any text editor if you need to.

The first two parameters set the dimensions of the applet when incorporated into your movie; set these to the width and height you want to allow for the applet. These parameters are required: if they are not set, the applet will take the entire Stage area.

The third parameter is also required, and must be included exactly as above (case-sensitively, and with one space after the comma).

3. Copying Files

For simplicity, you should keep the Cool Focus applet file (.SWF file) and its datafile (.INF file) in the same folder as your own Flash movie. When you publish your own movie to your web site, remember to publish the two Cool Focus files to the same location.

4. Adding the Applet to your Movie

Add the following ActionScript to the level or MovieClip object which should contain it:

createEmptyMovieClip("example", 20);
example.loadMovie("Messenger.swf");

This code creates a new, empty MovieClip object to hold the applet, assigns it the name example and a depth of 20. Of course, you can change the name and depth to whatever you choose. If this were placed in the first frame of the first layer, you would refer to the applet as _level0.example and its container would be _level0.

The second line loads the specified Cool Focus applet file. (If the applet file is not in the same folder as your movie, you will need to specify an absolute or relative path to it.)

Using the second line of code above, the Messenger applet would be loaded into your movie and would read its parameters from a file named Messenger.inf in the same folder as Messenger.swf. If you need to specify a different datafile, change the second line to:

example.loadMovie("Messenger.swf?datafile=appletdata.inf");

changing appletdata.inf to the name of your datafile.

5. Setting the Applet's Position

By default the applet will be placed at point 0,0 on the Stage. To position it elsewhere, add the following two lines:

example._x=60; //horizontal position
example._y=105; //vertical position

Everything else the applet needs to know is included in its datafile. If the applet has a Transparent parameter, you may want to set this to Yes so that other parts of your own movie beneath the applet can be seen.

The remainder of this page covers slightly more complex options which you may prefer to ignore.

6. Handling Events

When an applet starts, it will query its container (_level0 in the example code above) for event-handler callback functions. Most Cool Focus applets support two 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; 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, 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.

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.

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;
   }
}

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" or "message", 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).

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.

7. 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.