Event-Management

Data Structures
class	nrEngine::Event
	Base untemplated class used for the event instancies. More...
class	nrEngine::EventActor
	Event actors could acts as a server and client on event communication channels. More...
class	nrEngine::EventChannel
	Event channel used for communication between application/engine's components. More...
class	nrEngine::EventFactory
	Event factories are used to create events of certain types. More...
class	nrEngine::EventManager
	Main class providing the event messaging system. More...
Defines
#define	META_Event(type)
Functions
template<class T>
static T *	nrEngine::event_cast (Event *base)
template<class T>
static SharedPtr< T >	nrEngine::event_shared_cast (SharedPtr< Event > base) throw (Exception)

---

Detailed Description

If you want to start to write a game you should be familar with event systems and event based programming. Event system are used to pass events between system modules without calling certain functions of that modules. So using of events could reduce the dependability of the system components.

In our engine we are trying to improve the normal behaviour of the event management system. We do not only use simple events, instead of this we mix several techniques like signals, triggers and state machines within the concept of events to give the develeoper a possibility to increase the dependecy gap between application modules.

The engine does also use name driven event system instead of id driven design. This is done for the reasons of readability and expandability. So if new event should be added to the system, it can be added by using other name rather then to recompile the application by adding new ids. Also using of string based names for the vents allows better using of scripting.

New type of events could be easely added through plugins, so the engine must not be recompiled. For example: the engine could easely be extended to an input system. The input system can fully be programmed as a plugin. To allow a communication between the components of the engine and application, the new plugin could generate a new type of events, namely "input". Each event listener which is registered for hearing the communication channel for the input events will be informed if there is a new event.

Our events are priority based. This means that each event does get a priority number defining how soon this event should be delivered. In each cycle the application running all events/messages comming to a channel will be collected in a priority queue. When the EventManager gets updated it tells the channels, that they now can deliver the messages to all connected actors. So the events with the highest priority will be delivered as first and the messages with the lowest priority will be delivered as last. If there is two events of the same priority, so it is not defined which one will be delivered as first.

There is also special events having the priority number IMMEDIATE which will cause the channel to deliver this message immediately without be stored in the queue. This actors will be informed about this events as soon as the event is triggered.

C++ does not provide any possibility to write the event management typesafe without big circumastances. There are some techniques, but this will end up in a big code plus a lot of function calls if to provide you the derived class instance instead of the base Event class. However we will try to give you the possibility of using your own event types derived from the base class in a controlled typesafe way. This means that if you handle correctly, so you will never cast to any wrong class by handling events.

---

Another problem which we have to solve is: How to share event messages between plugins and application. Assume you compiled your application with the nrEngine library linked in. Then if you start the app you use the same memory mapping like the engine does. It means sending now events through the nrEngine's subsystem to your application is not a big problem. However if you now use plugins which are dynamic libraries, which are linked dynamicaly while your app is running, this approach could not work so easy. it means you are still able to send events, but you now can not convert an event to a type which is provided by the plugin. (i.e. plugin defines new type of events (NewEvent). Plugin create an instance of this class and send it to your application, you now not able to cast base class Event to this NewEvent class). Problem of sharing type information between modules.

One solution were to forbidd plugins to send any new type of events which was not declared in the engine before. This solution might work, but then we loose to generality of our engine, because then we have to implement all things which are needed for properly use in the engine (graphics, inputs, ...)

The other solution is to provide the engine TODO !!!!!!

---

Define Documentation

#define META_Event

(

type

)

Value:

public:\
                        virtual const char* getEventType() const { return #type; }

Macro for definining event type information. Use this macro in all event definitions of classes derived from Event.

Definition at line 33 of file Event.h.

---

Function Documentation

template<class T>

static T* nrEngine::event_cast

(

Event *

base

)

[static]

Cast a certain event to another one. As casting we use dynamic_cast<T>() which will return 0 if casting can not be done of this kind of objects.

If casting could not be done, so an exception will be thrown, which you have to catch.

Definition at line 108 of file Event.h.

template<class T>

static SharedPtr<T> nrEngine::event_shared_cast

(

SharedPtr< Event >

base

)

throw (Exception) [static]

Same as event_cast() but cast now between smart pointers.

Definition at line 122 of file Event.h.

---