If you get the hang of using your own custom events in ActionScript 3.0 you can streamline your development and get more control of your code. This is the first part in a serie of two where we’re going to show you how you can create and use your own custom events.

In this first part we’re going to use a real-world example and use a custom event-class to load XML more smoothly. We’ll also go through how you create a document class and how you link it to your flash document.

1. Everything starts somewhere

First off, create a folder on your desktop that you call CustomEvents where you can put all the files corresponding to this tutorial. This will be our project directory.

2. Create the flash document:

Open up Adobe Flash (in this case we use Adobe Flash CS4 but the approach is similar if you use another version such as Adobe Flash CS3), choose File->New->Flash File (ActionScript 3.0) and save it as Main.fla in your current project directory.

3. Create the XML-file:

Create a folder in your project directory that you call xml. Add the following code to a file called images.xml and save it in the xml-folder in your project directory. This is the file that we are going to load with the help of our custom event class.
<?xml version="1.0" encoding="utf-8"?>
<images>
<image>
<url>images/image1.jpg</url>
</image>
<image>
<url>images/image2.jpg</url>
</image>
<image>
<url>images/image3.jpg</url>
</image>
</images>
This file is pretty straight-forward. It contains three image-nodes that each of them contain a url-node that specifies the location of each image.

4. Create the custom event class

To be able to streamline and make it easy to use our ActionScript-classes it’s nice (so far it’s possible) to make general classes that you can reuse from project to project. So create a new folder on your desktop that you call AS3Classes and create another folder in that directory that you call com. We’ll get back to how you customize your flash document so it can use the classes you put in this folder. But first off, let’s create the classes.

In Adobe Flash, choose File->New->ActionScript file and add the following code to the file that you save as XMLoaderEvent.as in the com-folder.
package com
{
import flash.events.Event;
public class XMLLoaderEvent extends Event
{
public var xml:XML;
public static const COMPLETE:String = "complete";
public function XMLLoaderEvent(type:String,
bubbles:Boolean = false, cancelable:Boolean = false,
xml:XML = null)
{
super(type, bubbles, cancelable);
this.xml = xml;
}
}
}
You don’t need to create your own event class to be able to listen to all the events you can listen to when you load files but it’s a nice thing to do because you get more control of your code. As you can see the event class doesn’t actually load a file, it just has a few properties that you can use when you load a file. We’ll create a specific class later on that actually do all the loading but we’ll get back to that soon.

5. Create a document class

You can start your code by adding ActionScript directly on the first frame in your main timeline but since we write all our code in classes it’s nice to keep on doing this and that’s why we now need to create our document class.

Choose File->New->ActionScript file, add the following code to it and save it as Main.as in your current project directory.
package
{
import flash.display.MovieClip;
public class Main extends MovieClip
{
public function Main()
{
// This is the constructor of our document class. This
//is where our code will start.
trace("Hello world!");
}
}
}
Now we need to tell our flash document that we want this class to be the document class. Choose File->Publish settings->Flash (the tab)->Settings. At the top of that popup-window you can tell your flash document the name of your document class that in this case is Main. So just write Main in this input and save all your changes.

If you now press CTRL+Enter you will publish your flash document and if you don’t get any error and in the output-window can read the text (“Hello world!”) that we trace in the constructor in our document class everything is set up correctly.

6. Create our XMLLoader class

We want to load XML and we want to write reusable code that we might want to use on other projects so let’s create a general class that we can use each time we want to load XML.

Choose File->New->ActionScript file, add the following code to the class and save it as XMLLoader.as in your com-folder:
package com
{
import flash.display.Sprite;
import flash.events.Event;
import flash.events.IOErrorEvent;
import flash.events.ProgressEvent;
import flash.net.URLLoader;
import flash.net.URLRequest;
public class XMLLoader extends Sprite
{
public function XMLLoader(url:String)
{
// Load the XML
var urlR:URLRequest = new URLRequest(url);
var l:URLLoader = new URLLoader(urlR);
// Add listeners
l.addEventListener(Event.COMPLETE, onComplete);
}
public function onComplete(e:Event):void
{
// Dispatch the complete event when the XML is loaded
this.dispatchEvent(new XMLLoaderEvent(
XMLLoaderEvent.COMPLETE, false, false,
XML(e.target.data)));
}
}
}

This class takes a url to the xml-file as argument and starts to load the XML and dispatches our own XMLLoaderEvent.COMPLETE-event when the XML has been loaded.

7. Tell our flash document where it can find our custom classes that we save in our AS3Classes-folder

To be able to use our classes that we put in our AS3Classes-folder we need to tell our document that this folder exists. You do that by choosing File->Publish settings->Flash (the tab)->Settings. There are a couple of new tabs and you should add the source path to your AS3Classes-folder here. Do that and save your changes.

8. Wrap it all together

Our next and final step is to instanciate our XMLLoader-class and trace the XML when it’s been loaded. So add some code to our document class so it’ll look like this:
package
{
import flash.display.MovieClip;
import com.XMLLoader;
import com.XMLLoaderEvent;
public class Main extends MovieClip
{
public function Main()
{
trace("Hello world!");
var url:String = "xml/images.xml";
var xl:XMLLoader = new XMLLoader(url);
xl.addEventListener(XMLLoaderEvent.COMPLETE,
onXMLLoaded);
}
public function onXMLLoaded(e:XMLLoaderEvent):void
{
trace(e.xml);
}
}
}

Now the code is ready to go so press CTRL+Enter and if everything is set up correctly you will now be able to read the contents of the XML-file in your output window.

This was more of an introduction to how you can write and use your custom events. In part 2 we’re going to take this code a step further and write code to load images more smoothly and more in-depth descripe how event classes work and how you can customize them.

/Simon