From 0ea5fc66924303d1bf73ba283a383e2aadee02f2 Mon Sep 17 00:00:00 2001 From: neodarz Date: Sat, 11 Aug 2018 20:21:34 +0200 Subject: Initial commit --- docs/doxygen/nel/events_howto.html | 186 +++++++++++++++++++++++++++++++++++++ 1 file changed, 186 insertions(+) create mode 100644 docs/doxygen/nel/events_howto.html (limited to 'docs/doxygen/nel/events_howto.html') diff --git a/docs/doxygen/nel/events_howto.html b/docs/doxygen/nel/events_howto.html new file mode 100644 index 00000000..e0dfc6a8 --- /dev/null +++ b/docs/doxygen/nel/events_howto.html @@ -0,0 +1,186 @@ + + + + nevrax.org : docs + + + + + + + + + + + + + + +
# Home   # nevrax.com   
+ + + + +
Nevrax
+ + + + + + + + + + +
+ + +
+ Nevrax.org
+ + + + + + + +
#News
#Mailing-list
#Documentation
#CVS
#Bugs
#License
+
+ + + 		+ + +
+Docs + +
+  + + + + + +
Documentation 
+ +
+Main Page   Namespace List   Class Hierarchy   Alphabetical List   Compound List   File List   Namespace Members   Compound Members   File Members   Related Pages   Search  
+

How to deal with events

 +
+Author:
+Stephane Coutelas

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 whith 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. +

+

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

+

+event_listener.png +
+ +

+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. +

+

+event_callback.png +
+ +

+

Example :

+ +

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

+Rq : This listener stores key states : if a key is pressed its value is on, else it's 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);
+
+

+Notes about the listener CEventListenerAsync : this listener adds two types of event 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 precise both event id and listener to be removed. +

+

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

+ + + +
                                                                                                                                                                    +

+ + -- cgit v1.2.1