Difference between revisions of "GEVENT"

From uGFX Wiki
Jump to: navigation, search
(→‎A closer look)
(→‎A closer look)
 
(18 intermediate revisions by the same user not shown)
Line 1: Line 1:
−
The GEVENT module is a very powerful event system. It provides a way to create a many-to-many relationship between sources and listeners. This allows to create user interfaces which use different hardware controls such as buttons AND touchscreen inputs at the same time very easily.
+
The GEVENT module is a very powerful event system. It provides a way to create a '''many-to-many''' relationships between sources and listeners. This allows to create user interfaces which use different hardware controls such as buttons '''AND''' touchscreen inputs at the same time very easily.
  
−
When you want to use the GEVENT module, you first have to enable it in your [[gfxconf.h]]:
+
The following guide will use terms like '''listener''' and '''sources'''. If you are not familiar with those terms or if you never worked with an event system before, please read the [[GEVENT FAQ]] first.
  
−
<pre>#define GFX_USE_GEVENT TRUE</pre>
+
== API reference ==
−
The following guide will use terms like '''listener''' and '''sources'''. If you are not familiar with those terms or if you never worked with an event system before, please read our FAQ of the GEVENT module.
+
The API reference of the GEVENT module can be found [http://api.ugfx.io/group___g_e_v_e_n_t.html here].
−
 
+
−
+
  
 
== Overview ==
 
== Overview ==
Line 12: Line 10:
  
 
#Create one or more listeners
 
#Create one or more listeners
−
#Attach one or more sourcees to this/those listeners
+
#Attach one or more sources to this/those listeners
 
#Wait for events
 
#Wait for events
 
But let's take a closer look to these steps:
 
But let's take a closer look to these steps:
−
 
−
 
  
 
== A closer look ==
 
== A closer look ==
−
After we have enabled the GEVENT module as described above, we have to create at least one listener. A listener is that part of an event system which does something when a certain event has been triggered.
+
After we have enabled the GEVENT module in the [[Configuration|configuration file]], we have to create at least one listener. A listener is that part of an event system which does something when a certain event has been triggered.
  
 
<syntaxhighlight lang=c>
 
<syntaxhighlight lang=c>
−
void geventListenerInit(GListener *pl);
+
void geventListenerInit(GListener* pl);
 
</syntaxhighlight>
 
</syntaxhighlight>
 
Okay, so now we have a working listener but it's currently not listening to any event. We can now attach any event to that listener:
 
Okay, so now we have a working listener but it's currently not listening to any event. We can now attach any event to that listener:
  
 
<syntaxhighlight lang=c>
 
<syntaxhighlight lang=c>
−
bool_t geventAttachSource(GListener *pl, GSourceHandle gsh, unsigned flags);
+
gBool geventAttachSource(GListener* pl, GSourceHandle gsh, gU32 flags);
 
</syntaxhighlight>
 
</syntaxhighlight>
−
And now we're ready to take off. We can now use the geventEventWait() routine to wait for an event:
+
And now we're ready to take off. We can now use the <code>geventEventWait()</code> routine to wait for an event:
  
 
<syntaxhighlight lang=c>
 
<syntaxhighlight lang=c>
−
GEvent* geventEventWait(GListener *pl, systime_t timeout);
+
GEvent* geventEventWait(GListener* pl, gDelay timeout);
 
</syntaxhighlight>
 
</syntaxhighlight>
−
Please note that the geventEventWait() routine is a polling routine (therefore the timeout parameter). Furthermore, the current implementation of GEVENT does not provide an event queue. An event which is triggered while you are not listening for events using geventEventWait() will simply be skipped. The reason to implement this behaviour can be found in the memory and CPU usage of such a system. However, GEVENT is not meant for critical event tasks but only for user space applications.
+
Please note that the <code>geventEventWait()</code> routine is a polling routine (therefore the timeout parameter). Furthermore, the current implementation of GEVENT does not provide an event queue. An event which is triggered while you are not listening for events using <code>geventEventWait()</code> will simply be skipped. The reason to implement this behavior can be found in the memory and CPU usage of such a system. However, GEVENT is not meant for critical event tasks but only for user space applications.
  
 
== A real world example ==
 
== A real world example ==
Line 40: Line 36:
  
 
Let's asume you're building some media player device. It's very likely that you will have hardware controlls (buttons, a slider or a dial) to control the volume. However, somewhere you want to be able to control the volume over a touchscreen input as well. You would now have to create two different callbacks and update the value of one versus the other. Sure, it's no problem to do that indeed, but wouldn't it be simpler just to attach two sources to one listener? ;-)
 
Let's asume you're building some media player device. It's very likely that you will have hardware controlls (buttons, a slider or a dial) to control the volume. However, somewhere you want to be able to control the volume over a touchscreen input as well. You would now have to create two different callbacks and update the value of one versus the other. Sure, it's no problem to do that indeed, but wouldn't it be simpler just to attach two sources to one listener? ;-)
 +
 +
 +
 +
[[Category:Module]]

Latest revision as of 15:00, 20 August 2021

The GEVENT module is a very powerful event system. It provides a way to create a many-to-many relationships between sources and listeners. This allows to create user interfaces which use different hardware controls such as buttons AND touchscreen inputs at the same time very easily.

The following guide will use terms like listener and sources. If you are not familiar with those terms or if you never worked with an event system before, please read the GEVENT FAQ first.

API reference

The API reference of the GEVENT module can be found here.

Overview

Using GEVENT is a simple three step process:

  1. Create one or more listeners
  2. Attach one or more sources to this/those listeners
  3. Wait for events

But let's take a closer look to these steps:

A closer look

After we have enabled the GEVENT module in the configuration file, we have to create at least one listener. A listener is that part of an event system which does something when a certain event has been triggered. 

void geventListenerInit(GListener* pl);

Okay, so now we have a working listener but it's currently not listening to any event. We can now attach any event to that listener: 

gBool geventAttachSource(GListener* pl, GSourceHandle gsh, gU32 flags);

And now we're ready to take off. We can now use the geventEventWait() routine to wait for an event: 

GEvent* geventEventWait(GListener* pl, gDelay timeout);

Please note that the geventEventWait() routine is a polling routine (therefore the timeout parameter). Furthermore, the current implementation of GEVENT does not provide an event queue. An event which is triggered while you are not listening for events using geventEventWait() will simply be skipped. The reason to implement this behavior can be found in the memory and CPU usage of such a system. However, GEVENT is not meant for critical event tasks but only for user space applications.

A real world example

You're asking why we created a many-to-many event system? Let me show you...

Let's asume you're building some media player device. It's very likely that you will have hardware controlls (buttons, a slider or a dial) to control the volume. However, somewhere you want to be able to control the volume over a touchscreen input as well. You would now have to create two different callbacks and update the value of one versus the other. Sure, it's no problem to do that indeed, but wouldn't it be simpler just to attach two sources to one listener? ;-)

Retrieved from "https://wiki.ugfx.io/index.php?title=GEVENT&oldid=1942"