aboutsummaryrefslogtreecommitdiff
path: root/docs/doxygen/nel/events_howto.html
blob: a11131e3b3a676b95f0988b93b0f7da869eeeb91 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
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="/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="/inc/img/pixel.gif" WIDTH="16" HEIGHT="16" BORDER=0 ALT=""></TD>
        <TD WIDTH=140 BGCOLOR=#dddddd><IMG  SRC="/inc/img/pixel.gif" WIDTH="140" HEIGHT="16" BORDER=0 ALT=""></TD>
        <TD WIDTH=16><IMG  SRC="/inc/img/pixel.gif" WIDTH="16" HEIGHT="16" BORDER=0 ALT=""></TD>
        <TD><IMG width=6 height=14 SRC="/inc/img/reddots.gif" ALT="#" VSPACE=2 HSPACE=2 BORDER=0 ></TD><TD VALIGN=middle>&nbsp;<A CLASS=uplinks HREF=><b>Home</B></FONT></A>&nbsp;&nbsp;&nbsp;</TD>
        <TD><IMG  width=6 height=14  SRC="/inc/img/reddots.gif" ALT="#" VSPACE=2 HSPACE=2 BORDER=0 ></TD><TD VALIGN=middle>&nbsp;<A CLASS=uplinks HREF=><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="/inc/img/black_banner.jpg"><A HREF=""><IMG  SRC="/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="/inc/img/pixel.gif" WIDTH="16" HEIGHT="10" BORDER=0 ALT=""></TD>
	<TD WIDTH=140   BGCOLOR=#dddddd VALIGN=TOP ALIGN=middle><IMG  SRC="/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="/news/" TITLE="Rubrique news"><img width=13 height=15  hspace=5 border=0 src=/inc/img/picto-news.gif ALT=#></A></td><td><a  class='linkbox' href="/news/" TITLE="News">News</a></td></tr>
			<tr><td ALIGN=middle><a  class='linkbox' href="/mail/" TITLE="Rubrique mail"><img width=15 height=11  hspace=5 border=0 src=/inc/img/picto-mail.gif ALT=#></A></td><td><a  class='linkbox' href="/mail/" TITLE="Mailing list archive">Mailing-list</a></td></tr>
			<tr><td ALIGN=middle><a  class='linkbox' href="/docs/" TITLE="Rubrique docs"><img width=14 height=16  hspace=5 border=0 src=/inc/img/picto-docs.gif ALT=#></A></td><td><a  class='linkbox' href="/docs/" TITLE="Documentation">Documentation</a></td></tr>
			<tr><td ALIGN=middle><a  class='linkbox' href="/cvs/" TITLE="Rubrique cvs"><img width=13 height=17  hspace=5 border=0 src=/inc/img/picto-cvs.gif ALT=#></A></td><td><a  class='linkbox' href="/cvs/" TITLE="CVS Web">CVS</a></td></tr>
			<tr><td ALIGN=middle><a  class='linkbox' href="/bugs/" TITLE="Rubrique bugs"><img width=20 height=16  hspace=5 border=0 src=/inc/img/picto-bugs.gif ALT=#></A></td><td><a  class='linkbox' href="/bugs/" TITLE="Bugtracking">Bugs</a></td></tr>
			<tr><td ALIGN=middle><a  class='linkbox' href="/GPL.php3" TITLE="Rubrique license"><img  width=18 height=12   hspace=5 border=0 src=/inc/img/picto-gpl.gif ALT=#></A></td><td><a  class='linkbox' href="/GPL.php3" TITLE="License">License</a></td></tr>
		</TABLE>
		</TD></TR></TABLE></TD></TR></TABLE>
		<!------ End Box  ------>

	</TD>
	<TD WIDTH=15><IMG  SRC="/inc/img/pixel.gif" WIDTH="16" HEIGHT="16" BORDER=0 ALT=""></TD>
	<TD ALIGN=left valign=top><IMG  SRC="/inc/img/pixel.gif" WIDTH="140" HEIGHT="10" BORDER=0 ALT="">

<!-- title -->
<TABLE  background="/inc/img/redline.gif" CELLSPACING=0 CELLPADDING=0  BORDER=0 width=100%><tr><td>
<A HREF="/docs/"><img src="/inc/img/t_docs.gif" ALT="Docs" HEIGHT=20 BORDER=0></A>
</td><td><IMG  SRC="/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="/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:/cgi-bin/nel-search.cgi" href="/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=/inc/img/pixel.gif WIDTH=15 HEIGHT=15 BORDER=0 ALT=""></TD>
</TR>
</TABLE>
</BODY>
</HTML>