Call me crazy, but I really like Flash’s EventDispatcher class – it’s simple, powerful and most of all relatively fast.
I felt the need to take EventDispatcher outside of my flash projects to my more advanced C++ ones. This turned out to be quite an easy task.
Instead of a boring ‘download code’ link, I will write the steps of implementing it using C++’s STLs, just because I feel like writing.
I would like to start by noting that I will only implement the EventDispatcher class, and not flash.events.Event. I will have a very basic and dull Event class. Another note would be the Object class, which isn’t reimplemented for performance (RTTI hacks are expensive).
Let’s start by examining our situation:
- Events are identified as strings
- An event can have several listeners
- Event functions have priority from -2M to 2M (32bit signed)
- Events have phases
In this article, I will tackle those one by one.
Let’s starts with the basics, we know EventDispatcher::addEventListener takes functions as callbacks, so let’s define an event listener type. Before we can do that though, we also need to define an Event class to be passed when the event callback is called.
// Event class
class Event
{
public:
Event(std::string type, bool bubbles = false, bool cancelable = false):
type(type), bubbles(bubbles), cancelable(cancelable)
{
}
const std::string type;
const bool bubbles;
const bool cancelable;
/*
const void* target;
const unsigned int eventPhase;
const void* currentTarget;
*/
};
// Event function callback pointer type
typedef void (*eventFunctionPtr)(const Event &);
The Event class does nothing important but emulating flash’s Event class and holding a const std::string for the type of the event.
The callback type, called eventFunctionPtr basically points to a function that returns nothing (void) and takes a const refrence to an Event as an argument, so the following AS3 code:
public function eventListener(event:Event):void
{
// Listener code ...
}
Would become this code in C++:
void eventListener(const Event &event)
{
// Listener code ...
}
Now that we have our Event class type and the function callback type, let’s implement the basics – mapping string to function callbacks. This can easily be done using std::map which stores data (in this case, a function pointer) that can later be retrieved by using a key (in this case, a string). This is a bit like using a primary key to refer to a record in a database table.
The code at the moment is quite simple, having only addEventListener coded:
class EventDispatcher
{
public:
void addEventListener(const std::string &type, eventFunctionPtr listener, bool useCapture = false, int priority = 0, bool useWeakReference = false)
{
// Set the event listener to the key
eventHandlerList[type] = listener;
}
private:
std::map<std::string, eventFunctionPtr > eventHandlerList;
};
Implementing the method hasEventListener is also effortless, since we are just checking to see if a key exists on the map:
bool hasEventListener(const std::string &type)
{
return (eventHandlerList.find(type) != eventHandlerList.end());
}
Now for the heart of the EventDispatcher class – the dispatchEvent method, which will simply execute the function we get from the key:
void dispatchEvent(const Event &event)
{
if(hasEventListener(event.type))
eventHandlerList[event.type](event);
}
The reason we’re checking if the event listener exists for this event is because std::map will create a null function pointer, which will be slow, memory consuming and will report false positives when using hasEventListener when calling dispatchEvent with event type that is not registered with our EventDispatcher. This simple check makes sure we only execute the event listener if it has in fact, a callback.
When we try to implement the method removeEventListener, we come across a problem – we only have one callback for each event string. removeEventListener method takes a string and a function pointer which will not be used. If one callback per event is what you need, the following code will do the trick:
void removeEventListener(const std::string &type, eventFunctionPtr listener, bool useCapture = false)
{
eventHandlerList.erase(type);
}
Since that’s not what we desire, we will move on to the next item on the list, which specifies that each event can have several listeners. We can easily do that by mapping a string to a list of function pointers using std::list.
Let’s start by redefining eventHandlerList to it’s new type:
std::map<std::string, std::list<eventFunctionPtr > > eventHandlerList;
However that requires us to change addEventListener and removeEventListener, although hasEventListener will remain unchanged.
addEventListener has the easiest ‘fix’, now instead of assigning the listener to the map’s key, we add it to the list we receive. This changes addEventListener to the following code:
void addEventListener(const std::string &type, eventFunctionPtr listener, bool useCapture = false, int priority = 0, bool useWeakReference = false)
{
// Simply add the event listener to the list of listeners
eventHandlerList[type].push_back(listener);
}
In removeEventHandler’s case, we remove all occurrences of the listener from the list, first checking if the map has this key registered:
void removeEventListener(const std::string &type, eventFunctionPtr listener, bool useCapture = false)
{
if(hasEventListener(type))
eventHandlerList[type].remove(listener);
}
The dispatchEvent method, however, gets a complete make over, because this time we have to iterate over the list of callbacks and execute them all:
void dispatchEvent(const Event &event)
{
// Leave if no event registered
if(!hasEventListener(event.type))
return;
// A reference to keep code clean
std::list<eventFunctionPtr > &allFunctions = eventHandlerList[event.type];
// Iterate through all functions in the event and execute them
for(std::list<eventFunctionPtr >::iterator i=allFunctions.begin(); i!=allFunctions.end(); ++i)
(*i)(event);
}
The function hasEventListener does not need to change, and still works with our new structure, since the base data structure is still std::map.
Now that we are done with that, we are facing a new problem – priorities. Flash enables you to give priorities to the function, letting them be closer to the time of the event was dispatched. However, Flash is so flexible that it lets us set the priorities as an signed 32bit integer. Imagine this – an array of 4,294,967,296 (2 to the power of 32 – 4 billion) lists residing on memory for each event we have – this is huge!
A neat solution would be to use another map to map integers to list, this time for the sole purpose of saving memory, not speed.
So this time our eventHandlerList evolved into this scary looking type:
std::map<std::string, std::map<int, std::list<eventFunctionPtr > > eventHandlerList;
In case you are lost, here is a quick description of what’s going on: this structure maps a string (event type) to another map, which maps a 32bit integer to a list of function pointers.
Again, we will start by modifying the simplest method, which is addEventListener. The change this time, will simply map the priority in addition to the type:
void addEventListener(const std::string &type, eventFunctionPtr listener, bool useCapture = false, int priority = 0, bool useWeakReference = false)
{
// Simply add the event listener to the list of listeners for the selected priority
eventHandlerList[type][priority].push_back(listener);
}
Dispatching an event now gets a little more interesting, since we have to iterate over two structures – first the map of priorities, then the list of callbacks. We will be iterating the map in reverse, since we want higher priority functions (higher keys) to be executed first as opposed to the way std::map iterates which is from lowest to highest (negative to positive).
void dispatchEvent(const Event &event)
{
// Leave if no event registered
if(!hasEventListener(event.type))
return;
// A reference to keep code clean
std::map<int, std::list<eventFunctionPtr > > &allFunctions = eventHandlerList[event.type];
// Iterate through all functions in the event, from high proproty to low
for(std::map<int, std::list<eventFunctionPtr > >::reverse_iterator i=allFunctions.rbegin(); i!=allFunctions.rend(); ++i) {
std::list &funcList = i->second;
// Execute callbacks
for(std::list::iterator f=funcList.begin(); f!=funcList.end(); ++f)
(*f)(event);
}
}
The real tricky method is removeEventListener – because we only receive the event type and the listener to remove, we have no information on what priority the callback has and where it’s located inside our structure, which means we will have to search for it.
Another problem is false positives – if we remove an event listener from the list, an empty list will stay in memory, meaning that hasEventListener will return true if the list is empty. A way to overcome this problem is to erase the list from the priority map whenever it’s empty AND remove the priority map from the event type map.
The following code will do both:
void removeEventListener(const std::string &type, eventFunctionPtr listener, bool useCapture = false)
{
// Leave if no event registered
if(!hasEventListener(type))
return;
// Reference to keep the code clean
std::map<int, std::list<eventFunctionPtr > > &allFunctions = eventHandlerList[type];
// Since we don't know the function's priority, we'll search for it
for(std::map<int, std::list<eventFunctionPtr > >::iterator i=allFunctions.begin(); i!=allFunctions.end(); ++i) {
// Saving a branch here: instead of checking if the callback exists let remove() do it for us
i->second.remove(listener);
// Remove object from the map if list gone empty to eliminate false positives
if(i->second.empty())
allFunctions.erase(i);
}
// Remove map to eliminate false positives
if(allFunctions.empty())
eventHandlerList.erase(type);
}
I could go on, but from here on, the class really starts integrating into the GUI code part (bubbling, phases…) which would require a GUI code.
I hope this would help someone, I just wanted to write something on my aging site.
