GEVENT
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:
- Create one or more listeners
- Attach one or more sources to this/those listeners
- 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? ;-)
