This thread is part 2 in the “Understanding the AS3 Event System” series. It continues on the “office” illustration used in part 1. If you have not read part 1, it is recommended that you do so.

I originally wrote this thread as a response to a Kirupa forum thread: Passing a string to be a custom event

This is my first draft, so any opinions or thoughts are deeply appreciated, especially if there is anything you still don’t fully understand or would like me to clarify further.

Listen, don’t tell my boss, but those days when work gets slow, I fire up some StarCraft! StarCraft is no fun alone, so Nico, Bob, Larry, and I all play against eachother. The problem is that we all need to be logged on at the same time in order to play together. I’m the one who plays the most, so I am the “Game Master”; the one who starts up the server, chooses a map, and waits for everyone else to join in.

We need some way to alert each other when I start up a StarCraft game, and keep it a secret from my boss (he reads all our emails, so I can’t tell them via email). So, we use the Event system!

Custom Event Strings

We have planned that whenever I am about to start up a new game, I stand up and yell out to everyone “I am about to call Yamato!” (who our boss assumes is one of my Japanese clients)

Everyone knows that the custom event string (also known as event type) for when everyone listening should play starcraft is "Yamato". So, ahead of time, Nico, Bob, and Larry listen for my "Yamato" event:

1

homeButton.addEventListener("Yamato", startPlayingStarScraft);

Now, we may start playing dozens of different games, and I have chosen a different “code name” as the event string for each type of game:

1
2
3
4

homeButton.addEventListener("MarcoPolo", startPlayingAOE);
homeButton.addEventListener("Gelinor", startPlayingRuneScape);
homeButton.addEventListener("Germany", startPlayingCOD);
homeButton.addEventListener("Orcish", startPlayingWOW);

Custom Events

Now, I could create a different type of Event Folder for each type of game, such as StarCraftEvent, RuneScapeEvent, AOEEvent etc.

Each type of event file would have information inside of it, for instance, the StarCraftEvent Folder may have the following properties: – target – Me, since I’m the one “dispatching” the event – type – the custom event string, in this case “Yamato” – map – the StarCraft map we will be playing in – players – a list of all players – settings – the game settings

And our class would look something like this (note that target and type are automatically inherited by the Event since you extend it)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

public class StarCraftEvent extends Event
{
    public function StarCraftEvent(the_type:String, the_map:SCMap, the_players:Array, the_settings:GameSettings)
    {
        //Since you extend the Event, let the super class know a few more additional details
        super(the_type);

        map = the_map;
        players = the_players;
        settings = the_settings;
    }

    public var map:SCMap;
    public var players:Array;
    public var settings:GameSettings
}

This would be my totally custom made event class! Perfectly customized for whenever we want to start a StarCraft game, allowing everyone to get the information they need!

Dispatching the Custom Event

This is exactly as simple as it was dispatching the "clicked" event:

1
2
3
4
5
6

//Create the event
var players:Array = [Andreas, Nico, Bob, Larry];
var scEvent:StarCraftEvent = new StarCraftEvent("<u>Yamato</u>", lostTemple, players, defaultSettings);

//Dispatch the event (and it's folder containing all the info)
dispatchEvent(scEvent);

That dispatches an event which alerts everyone who is listening that I am about to start up a StarCraft game.

So, Nico, Bob, and Larry run up to my cubicle and I hand them all the StarCraftEvent Folder containing ALL the information they need to join in the game.

Do you really need to create Custom Events?

Now I can create a new Custom Event for each and every game we play and that would alright.

But I noticed, no one really reads the information in the Event Folder! I spent good money putting together and printing out all the information for those folders, and no one reads them! They get the file from me, then run back to their own cubicles, fire up the game, and throw the Event Folder directly into the trash.

Surround your pullquote like this {“ text to be quoted ”}

Instead, what if I print out a plain old Event Folder? All it says is the target and the type, but if they want more information (which someone once in a while does) they can ask me for it directly.

FORGET about the hassle with the StarCraftEvent class, and just do this:

1
2

var eventFolder:Event = new Event("Yamato");
dispatchEvent(eventFolder);

99% of the time. That is all you will ever need. You save a lot of unnecessary work.

You don’t always need to create custom Events, usually it is enough just using custom Event Strings.

That is Custom Events 101

Continue to Part #3 – Easy Event Bubbling