aboutsummaryrefslogtreecommitdiff
path: root/docs/doxygen/nel/events_howto.html
diff options
context:
space:
mode:
authorneodarz <neodarz@neodarz.net>2018-08-11 20:21:34 +0200
committerneodarz <neodarz@neodarz.net>2018-08-11 20:21:34 +0200
commit0ea5fc66924303d1bf73ba283a383e2aadee02f2 (patch)
tree2568e71a7ccc44ec23b8bb3f0ff97fb6bf2ed709 /docs/doxygen/nel/events_howto.html
downloadnevrax-website-self-hostable-0ea5fc66924303d1bf73ba283a383e2aadee02f2.tar.xz
nevrax-website-self-hostable-0ea5fc66924303d1bf73ba283a383e2aadee02f2.zip
Initial commit
Diffstat (limited to '')
-rw-r--r--docs/doxygen/nel/events_howto.html186
1 files changed, 186 insertions, 0 deletions
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 @@
+<!doctype html public "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
+<HTML>
+<HEAD>
+ <TITLE>nevrax.org : docs</TITLE>
+ <LINK REL=stylesheet TYPE="text/css" HREF="http://www.nevrax.org/inc/css/nevrax.css">
+ <link href="doxygen.css" rel="stylesheet" type="text/css">
+</HEAD>
+<BODY MARGINHEIGHT="0" MARGINWIDTH="0">
+
+<!-- uplinks -->
+<TABLE CELLSPACING=0 CELLPADDING=0 BORDER=0>
+ <TR>
+ <TD WIDTH=16><IMG SRC="http://www.nevrax.org/inc/img/pixel.gif" WIDTH="16" HEIGHT="16" BORDER=0 ALT=""></TD>
+ <TD WIDTH=140 BGCOLOR=#dddddd><IMG SRC="http://www.nevrax.org/inc/img/pixel.gif" WIDTH="140" HEIGHT="16" BORDER=0 ALT=""></TD>
+ <TD WIDTH=16><IMG SRC="http://www.nevrax.org/inc/img/pixel.gif" WIDTH="16" HEIGHT="16" BORDER=0 ALT=""></TD>
+ <TD><IMG width=6 height=14 SRC="http://www.nevrax.org/inc/img/reddots.gif" ALT="#" VSPACE=2 HSPACE=2 BORDER=0 ></TD><TD VALIGN=middle>&nbsp;<A CLASS=uplinks HREF=http://www.nevrax.org><b>Home</B></FONT></A>&nbsp;&nbsp;&nbsp;</TD>
+ <TD><IMG width=6 height=14 SRC="http://www.nevrax.org/inc/img/reddots.gif" ALT="#" VSPACE=2 HSPACE=2 BORDER=0 ></TD><TD VALIGN=middle>&nbsp;<A CLASS=uplinks HREF=http://www.nevrax.com><b>nevrax.com</B></FONT></A>&nbsp;&nbsp;&nbsp;</TD>
+ </TR>
+</TABLE>
+
+<!-- banner Nevrax -->
+<TABLE CELLSPACING=0 CELLPADDING=0 BORDER=0 WIDTH=100%>
+ <TR><TD BGCOLOR="#000000" BACKGROUND="http://www.nevrax.org/inc/img/black_banner.jpg"><A HREF="http://www.nevrax.org"><IMG SRC="http://www.nevrax.org/inc/img/nevrax.gif" WIDTH="170" HEIGHT="45" BORDER=0 ALT="Nevrax" ></A></TD></TR>
+</TABLE>
+
+<!-- main table -->
+<TABLE CELLSPACING=0 CELLPADDING=0 BORDER=0 height=100%>
+ <TR>
+ <TD WIDTH=16><IMG SRC="http://www.nevrax.org/inc/img/pixel.gif" WIDTH="16" HEIGHT="10" BORDER=0 ALT=""></TD>
+ <TD WIDTH=140 BGCOLOR=#dddddd VALIGN=TOP ALIGN=middle><IMG SRC="http://www.nevrax.org/inc/img/pixel.gif" WIDTH="140" HEIGHT="10" BORDER=0 ALT="">
+
+ <!------ Begin Box ------>
+ <TABLE BORDER=0 CELLSPACING=0 CELLPADDING=0 BGCOLOR=black><TR><TD><TABLE border=0 cellspacing=2 cellpadding=0 width=120><tr><TD ALIGN=middle bgcolor=black>
+ <FONT COLOR=white FACE="sans-serif"><B>Nevrax.org</B></FONT></TD></TR><tr><td colspan=2 bgcolor=#FFFFFF>
+ <TABLE cellspacing=0 cellpadding=1 border=0>
+ <tr><td ALIGN=middle><a class='linkbox' href="http://www.nevrax.org/news/" TITLE="Rubrique news"><img width=13 height=15 hspace=5 border=0 src=http://www.nevrax.org/inc/img/picto-news.gif ALT=#></A></td><td><a class='linkbox' href="http://www.nevrax.org/news/" TITLE="News">News</a></td></tr>
+ <tr><td ALIGN=middle><a class='linkbox' href="http://www.nevrax.org/mail/" TITLE="Rubrique mail"><img width=15 height=11 hspace=5 border=0 src=http://www.nevrax.org/inc/img/picto-mail.gif ALT=#></A></td><td><a class='linkbox' href="http://www.nevrax.org/mail/" TITLE="Mailing list archive">Mailing-list</a></td></tr>
+ <tr><td ALIGN=middle><a class='linkbox' href="http://www.nevrax.org/docs/" TITLE="Rubrique docs"><img width=14 height=16 hspace=5 border=0 src=http://www.nevrax.org/inc/img/picto-docs.gif ALT=#></A></td><td><a class='linkbox' href="http://www.nevrax.org/docs/" TITLE="Documentation">Documentation</a></td></tr>
+ <tr><td ALIGN=middle><a class='linkbox' href="http://www.nevrax.org/cvs/" TITLE="Rubrique cvs"><img width=13 height=17 hspace=5 border=0 src=http://www.nevrax.org/inc/img/picto-cvs.gif ALT=#></A></td><td><a class='linkbox' href="http://www.nevrax.org/cvs/" TITLE="CVS Web">CVS</a></td></tr>
+ <tr><td ALIGN=middle><a class='linkbox' href="http://www.nevrax.org/bugs/" TITLE="Rubrique bugs"><img width=20 height=16 hspace=5 border=0 src=http://www.nevrax.org/inc/img/picto-bugs.gif ALT=#></A></td><td><a class='linkbox' href="http://www.nevrax.org/bugs/" TITLE="Bugtracking">Bugs</a></td></tr>
+ <tr><td ALIGN=middle><a class='linkbox' href="http://www.nevrax.org/GPL.php3" TITLE="Rubrique license"><img width=18 height=12 hspace=5 border=0 src=http://www.nevrax.org/inc/img/picto-gpl.gif ALT=#></A></td><td><a class='linkbox' href="http://www.nevrax.org/GPL.php3" TITLE="License">License</a></td></tr>
+ </TABLE>
+ </TD></TR></TABLE></TD></TR></TABLE>
+ <!------ End Box ------>
+
+ </TD>
+ <TD WIDTH=15><IMG SRC="http://www.nevrax.org/inc/img/pixel.gif" WIDTH="16" HEIGHT="16" BORDER=0 ALT=""></TD>
+ <TD ALIGN=left valign=top><IMG SRC="http://www.nevrax.org/inc/img/pixel.gif" WIDTH="140" HEIGHT="10" BORDER=0 ALT="">
+
+<!-- title -->
+<TABLE background="http://www.nevrax.org/inc/img/redline.gif" CELLSPACING=0 CELLPADDING=0 BORDER=0 width=100%><tr><td>
+<A HREF="http://www.nevrax.org/docs/"><img src="http://www.nevrax.org/inc/img/t_docs.gif" ALT="Docs" HEIGHT=20 BORDER=0></A>
+</td><td><IMG SRC="http://www.nevrax.org/inc/img/pixel.gif" WIDTH="1" HEIGHT="1" BORDER=0 ALT="">
+</td></tr></table>
+&nbsp;
+
+<!-- block -->
+<TABLE bgcolor="#dddddd" CELLSPACING=0 CELLPADDING=0 BORDER=0 width=100%><tr><td width=1% valign=middle><img width=6 height=14 hspace=2 vspace=2 src="http://www.nevrax.org/inc/img/reddots.gif"></TD>
+ <TD><B>Documentation</B></TD>
+ <TD ALIGN=RIGHT>&nbsp;</td>
+</tr></table>
+<!-- Generated by Doxygen 1.2.14 -->
+<center>
+<a class="qindex" href="index.html">Main Page</a> &nbsp; <a class="qindex" href="namespaces.html">Namespace List</a> &nbsp; <a class="qindex" href="hierarchy.html">Class Hierarchy</a> &nbsp; <a class="qindex" href="classes.html">Alphabetical List</a> &nbsp; <a class="qindex" href="annotated.html">Compound List</a> &nbsp; <a class="qindex" href="files.html">File List</a> &nbsp; <a class="qindex" href="namespacemembers.html">Namespace Members</a> &nbsp; <a class="qindex" href="functions.html">Compound Members</a> &nbsp; <a class="qindex" href="globals.html">File Members</a> &nbsp; <a class="qindex" href="pages.html">Related Pages</a> &nbsp; <a class="qindexRef" doxygen="_cgi:http://www.nevrax.org/cgi-bin/nel-search.cgi" href="http://www.nevrax.org/cgi-bin/nel-search.cgi">Search</a> &nbsp; </center>
+<hr><a name="events_howto"><h2>How to deal with events</h2></a>
+ <dl compact><dt><b>
+Author: </b><dd>
+Stephane Coutelas</dl><a name="events_overview"><h3>Overall view</h3></a>
+
+<p>
+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.
+<p>
+<a name="event"><h3>CEvent</h3></a>
+
+<p>
+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 <a class="el" href="events_8h.html">events.h</a>.
+<p>
+<a name="event_listener"><h3>IEventListener</h3></a>
+
+<p>
+The interface provides a callback. A listener must implements this interface. Existing listeners can be found in <a class="el" href="event__listener_8h.html">event_listener.h</a>.
+<p>
+In the following example, the listener is supposed to have been added to an event server along with the event type EventCharId: <div class="fragment"><pre>CCallback cb;
+server.addListener (<a class="code" href="namespaceNLMISC.html#a254">EventCharId</a>, &amp;cb);
+</pre></div> When this callback is called whith such event it prints the char : <div class="fragment"><pre><font class="keyword">class </font>CCallback : <font class="keyword">public</font> IEventListener
+{
+ <font class="keyword">virtual</font> <font class="keywordtype">void</font> operator ()(<font class="keyword">const</font> CEvent&amp; event)
+ {
+ CEventChar ec = (CEventChar &amp;) event; <font class="comment">// here we know that we receive a CEventChar event</font>
+ printf(<font class="stringliteral">"%c"</font>, ec.Char);
+ }
+};
+</pre></div>
+<p>
+<a name="event_emitter"><h3>IEventEmitter</h3></a>
+
+<p>
+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.
+<p>
+<a name="event_server"><h3>CEventServer</h3></a>
+
+<p>
+A server is made of :<ul>
+<li>a multimap of (CClassId, IEventListener*)<li>a list of IEventEmitter*<li>a list of CEvent*</ul>
+When a call to the method pump is done, the server pumps its emitters for events. Events are stacked up in the list.
+<p>
+<div align="center">
+<img src="event_pump.png" alt="event_pump.png">
+</div>
+ Then, for each event, according to their id, the server applies the right callbacks stored in the multimap.
+<p>
+<div align="center">
+<img src="event_listener.png" alt="event_listener.png">
+</div>
+
+<p>
+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.
+<p>
+<div align="center">
+<img src="event_callback.png" alt="event_callback.png">
+</div>
+
+<p>
+<a name="event_example"><h3>Example :</h3></a>
+
+<p>
+Here is an example of the use of the special listener CEventListenerAsync (defined in <a class="el" href="event__listener_8cpp.html">event_listener.cpp</a>).
+<p>
+Rq : This listener stores key states : if a key is pressed its value is on, else it's off.
+<p>
+<div class="fragment"><pre><font class="comment">// declaring a listener</font>
+CEventListenerAsync asyncListener;
+
+<font class="comment">// declaring the server</font>
+CEventServer server;
+
+<font class="comment">// adding an emitter to the server </font>
+... <font class="comment">// here, a driver is initialized</font>
+server.addEmitter(driver-&gt;getEventEmitter()); <font class="comment">//in this ex the driver provides the emitter</font>
+
+<font class="comment">// adding the listener to the server</font>
+asyncListener.addToServer(server);
+
+<font class="comment">// events loop</font>
+<font class="keywordflow">do</font>
+{
+ <font class="comment">//pump for events</font>
+ server.pump();
+
+ <font class="comment">// user main function</font>
+ mainproc();
+}
+<font class="keywordflow">while</font>(!asyncListener.isKeyPush(<a class="code" href="namespaceNLMISC.html#a317a73">KeyESCAPE</a>));
+
+<font class="comment">// removing listener from server</font>
+asyncListener.removeFromServer(Server);
+</pre></div>
+<p>
+Notes about the listener CEventListenerAsync : this listener adds two types of event to a server : EventKeyUpId and EventKeyDownId.
+<p>
+<div class="fragment"><pre><font class="keywordtype">void</font> CEventListenerAsync::addToServer (CEventServer&amp; server)
+{
+ server.addListener (<a class="code" href="namespaceNLMISC.html#a253">EventKeyUpId</a>, <font class="keyword">this</font>);
+ server.addListener (<a class="code" href="namespaceNLMISC.html#a252">EventKeyDownId</a>, <font class="keyword">this</font>);
+}
+</pre></div>
+<p>
+The remove method is similar to add method, we must precise both event id and listener to be removed.
+<p>
+<div class="fragment"><pre><font class="keywordtype">void</font> CEventListenerAsync::removeFromServer (CEventServer&amp; server)
+{
+ server.removeListener (<a class="code" href="namespaceNLMISC.html#a253">EventKeyUpId</a>, <font class="keyword">this</font>);
+ server.removeListener (<a class="code" href="namespaceNLMISC.html#a252">EventKeyDownId</a>, <font class="keyword">this</font>);
+}
+</pre></div>
+<p>
+
+
+<!-- footer -->
+<BR><FONT Size=+5>&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; </FONT>
+</TD>
+<TD WIDTH=15><IMG SRC=http://www.nevrax.org/inc/img/pixel.gif WIDTH=15 HEIGHT=15 BORDER=0 ALT=""></TD>
+</TR>
+</TABLE>
+</BODY>
+</HTML>