Navigation C API Pages Python bindings Applications

Event Queue

Event queue is a queue to store input events.

Note This API is semi internal, normally the queue is used indirectly by the backend code.

Event Queue API

#include <GP.h>
/* or */
#include <input/GP_EventQueue.h>

#define GP_EVENT_QUEUE_DECLARE(name, scr_w, scr_h) ...;

/*
 * Initializes event queue passed as a pointer. The events array must be
 * queue_size long.
 *
 * If queue_size is set to zero, default value is expected.
 */
void GP_EventQueueInit(struct GP_EventQueue *self,
                       unsigned int screen_w, unsigned int screen_h,
                       unsigned int queue_size);

/*
 * Allocates and initializes event queue.
 *
 * If queue_size is set to zero, default value is used.
 */
struct GP_EventQueue *GP_EventQueueAlloc(unsigned int screen_w,
                                         unsigned int screen_h,
                                         unsigned int queue_size);

These functions are used to create an event queue.

The GP_EVENT_QUEUE_DECLARE is a macro that takes name and screen size and declares and initializes an event queue structure.

The initialization functions takes pointer to a memory large enough to hold an event queue structure and array of queue_size events.

The last function allocates and initializes an event queue. If allocation has failed NULL is returned.

#include <GP.h>
/* or */
#include <input/GP_EventQueue.h>

unsigned int GP_EventsQueueEventsQueued(GP_EventQueue *self);

This function returns number of queued events.

#include <GP.h>
/* or */
#include <input/GP_EventQueue.h>

int GP_EventQueueGet(GP_EventQueue *self, GP_Event *ev);

In case there are any events queued, the top event is removed from the queue, copied into the event structure that is passed as argument and non-zero is returned.

If there are no events queued the call returns immediately with zero.

#include <GP.h>
/* or */
#include <input/GP_EventQueue.h>

int GP_EventQueuePeek(GP_EventQueue *self, GP_Event *ev);

Same as GP_EventQueueGet() but the top event is not removed from the queue.

#include <GP.h>
/* or */
#include <input/GP_EventQueue.h>

void GP_EventQueuePutBack(GP_EventQueue *self, GP_Event *ev);

Puts event to the top of the queue. Useful for putting back event that has been removed from the queue.

#include <GP.h>
/* or */
#include <input/GP_EventQueue.h>

/*
 * Inject event that moves cursor by rx and ry.
 *
 * If timeval is NULL, current time is used.
 */
void GP_EventQueuePushRel(struct GP_EventQueue *self,
                          int32_t rx, int32_t ry, struct timeval *time);

/*
 * Produces relative event that moves cursor to the point x, y.
 *
 * If timeval is NULL, current time is used.
 */
void GP_EventQueuePushRelTo(struct GP_EventQueue *self,
                            uint32_t x, uint32_t y, struct timeval *time);

/*
 * Inject absolute event.
 *
 * If timeval is NULL, current time is used.
 */
void GP_EventQueuePushAbs(struct GP_EventQueue *self,
                          uint32_t x, uint32_t y, uint32_t pressure,
                          uint32_t x_max, uint32_t y_max, uint32_t pressure_max,
                          struct timeval *time);

/*
 * Inject event that changes key state (i.e. press, release, repeat).
 *
 * If timeval is NULL, current time is used.
 */
void GP_EventQueuePushKey(struct GP_EventQueue *self,
                          uint32_t key, uint8_t code, struct timeval *time);

/*
 * Inject window resize event
 */
void GP_EventQueuePushResize(struct GP_EventQueue *self,
                             uint32_t w, uint32_t h, struct timeval *time);

/*
 * Inject common event.
 */
void GP_EventQueuePush(struct GP_EventQueue *self,
                       uint16_t type, uint32_t code, int32_t value,
                       struct timeval *time);

Following functions are used for puting events into the event queue. If pointer to the timeval structure is NULL the event time will be filled with exact time the event was added to the queue.