GEVENT
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.
When you want to use the GEVENT module, you first have to enable it in your gfxconf.h:
#define GFX_USE_GEVENT TRUE
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.
Overview
Using GEVENT is a simple three step process:
- Create one or more listeners
- Attach one or more sourcees 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 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.
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:
bool_t geventAttachSource(GListener *pl, GSourceHandle gsh, unsigned 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, systime_t 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 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.
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? ;-)
