Difference between revisions of "GEVENT"

Revision as of 14:59, 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, 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 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? ;-)