Working With NeL Events

Overall view

To manage events, a class has to get or create a server. The server stores emitters, listeners, and events. When the server is required to pump events, it checks every emitters to get last events. All the listeners are stored in the server as a pair (type of event, listener). Thus a particular event can be handled by several listeners. It's the class which adds emitters and listeners it needs to the server.

CEvent

CEvent inherits CClassId. A predefined event is built by inheriting CEvent and using a CClassId, built whith a unique id.
Existing events can be found in events.h.

IEventListener

The interface provides a callback. A listener must implements this interface. Existing listeners can be found in event_listener.h. In the following example, the listener is supposed to have been added to an event server along with the event type EventCharId:

CCallback cb; server.addListener (EventCharId, &cb);

When this callback is called with such event it prints the char:

class CCallback : public IEventListener
{
	virtual void operator ()(const CEvent& event)
	{
		CEventChar ec = (CEventChar &) event; // here we know that we receive a CEventChar event
		printf("%c", ec.Char);
	}
};

IEventEmitter

It's the interface which gets low-level events and posts them to the server as NEL events. An emitter must implements this interface. Existing emitters can be found in emitters.h.

CEventServer

A server is made of:

• a multimap of (CClassId, IEventListener*)
• a list of IEventEmitter*
• a list of CEvent*

When a call to the method pump is done, the server pumps its emitters for events. Events are stacked up in the list.

 
Then, for each event, according to their id, the server applies the right callbacks stored in the multimap.

 
As for emitters, both server and class know the IListener. The listener callback is the operator() which takes an event in parameter. Thus, the user defines the listener/callback he needs and adds it to the server.

Example

Here is an example of the use of the special listener CEventListenerAsync (defined in event_listener.cpp).

This listener stores key states: if a key is pressed its value is on, otherwise it is off.

// declaring a listener
CEventListenerAsync asyncListener;

// declaring the server
CEventServer server;

// adding an emitter to the server
...
// here, a driver is initialized
server.addEmitter(driver->getEventEmitter()); //in this ex the driver provides the emitter

// adding the listener to the server
asyncListener.addToServer(server);

// events loop
do
{
 //pump for events
 server.pump();

 // user main function
 mainproc();
}
while(!asyncListener.isKeyPush(KeyESCAPE));

// removing listener from server
asyncListener.removeFromServer(Server);

The listener method CEventListenerAsync::addToServer adds two types of events to a server: EventKeyUpId and EventKeyDownId.

void CEventListenerAsync::addToServer (CEventServer& server) {
  server.addListener (EventKeyUpId, this);
  server.addListener (EventKeyDownId, this);
}

The remove method is similar to add method, we must precess both event IDs for the listener to be removed.

void CEventListenerAsync::removeFromServer (CEventServer& server) {
     server.removeListener (EventKeyUpId, this);
     server.removeListener (EventKeyDownId, this)
}