Difference between revisions of "GEVENT"
(→A closer look) |
(→A closer look) |
||
| (14 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''' | + | 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 | + | 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 10: | Line 10: | ||
#Create one or more listeners | #Create one or more listeners | ||
| − | #Attach one or more | + | #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 | + | 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> | ||
| − | + | gBool geventAttachSource(GListener* pl, GSourceHandle gsh, gU32 flags); | |
</syntaxhighlight> | </syntaxhighlight> | ||
And now we're ready to take off. We can now use the <code>geventEventWait()</code> 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, | + | GEvent* geventEventWait(GListener* pl, gDelay timeout); |
</syntaxhighlight> | </syntaxhighlight> | ||
| − | 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 | + | 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 39: | Line 37: | ||
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: | + | |
| + | [[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:
- 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? ;-)
