doc/event_queue.txt

   1 Event Queue
   2 -----------
   3
   4 Event queue is a queue to store link:input.html[input events].
   5
   6 NOTE: This API is semi internal, normally the queue is used indirectly by the
   7       backend code.
   8
   9 Event Queue API
  10 ~~~~~~~~~~~~~~~
  11
  12 [source,c]
  13 -------------------------------------------------------------------------------
  14 #include <GP.h>
  15 /* or */
  16 #include <input/GP_EventQueue.h>
  17
  18 #define GP_EVENT_QUEUE_DECLARE(name, scr_w, scr_h) ...;
  19
  20 /*
  21  * Initializes event queue passed as a pointer. The events array must be
  22  * queue_size long.
  23  *
  24  * If queue_size is set to zero, default value is expected.
  25  */
  26 void GP_EventQueueInit(struct GP_EventQueue *self,
  27                        unsigned int screen_w, unsigned int screen_h,
  28                        unsigned int queue_size);
  29
  30 /*
  31  * Allocates and initializes event queue.
  32  *
  33  * If queue_size is set to zero, default value is used.
  34  */
  35 struct GP_EventQueue *GP_EventQueueAlloc(unsigned int screen_w,
  36                                          unsigned int screen_h,
  37                                          unsigned int queue_size);
  38 -------------------------------------------------------------------------------
  39
  40 These functions are used to create an event queue.
  41
  42 The 'GP_EVENT_QUEUE_DECLARE' is a macro that takes name and screen size and
  43 declares and initializes an event queue structure.
  44
  45 The initialization functions takes pointer to a memory large enough to hold an
  46 event queue structure and array of queue_size events.
  47
  48 The last function allocates and initializes an event queue. If allocation has
  49 failed 'NULL' is returned.
  50
  51 [source,c]
  52 -------------------------------------------------------------------------------
  53 #include <GP.h>
  54 /* or */
  55 #include <input/GP_EventQueue.h>
  56
  57 unsigned int GP_EventsQueueEventsQueued(GP_EventQueue *self);
  58 -------------------------------------------------------------------------------
  59
  60 This function returns number of queued events.
  61
  62 [source,c]
  63 -------------------------------------------------------------------------------
  64 #include <GP.h>
  65 /* or */
  66 #include <input/GP_EventQueue.h>
  67
  68 int GP_EventQueueGet(GP_EventQueue *self, GP_Event *ev);
  69 -------------------------------------------------------------------------------
  70
  71 In case there are any events queued, the top event is removed from the
  72 queue, copied into the event structure that is passed as argument and
  73 non-zero is returned.
  74
  75 If there are no events queued the call returns immediately with zero.
  76
  77 [source,c]
  78 -------------------------------------------------------------------------------
  79 #include <GP.h>
  80 /* or */
  81 #include <input/GP_EventQueue.h>
  82
  83 int GP_EventQueuePeek(GP_EventQueue *self, GP_Event *ev);
  84 -------------------------------------------------------------------------------
  85
  86 Same as +GP_EventQueueGet()+ but the top event is not removed from the queue.
  87
  88 [source,c]
  89 -------------------------------------------------------------------------------
  90 #include <GP.h>
  91 /* or */
  92 #include <input/GP_EventQueue.h>
  93
  94 void GP_EventQueuePutBack(GP_EventQueue *self, GP_Event *ev);
  95 -------------------------------------------------------------------------------
  96
  97 Puts event to the top of the queue. Useful for putting back event that has
  98 been removed from the queue.
  99
 100 [source,c]
 101 -------------------------------------------------------------------------------
 102 #include <GP.h>
 103 /* or */
 104 #include <input/GP_EventQueue.h>
 105
 106 /*
 107  * Inject event that moves cursor by rx and ry.
 108  *
 109  * If timeval is NULL, current time is used.
 110  */
 111 void GP_EventQueuePushRel(struct GP_EventQueue *self,
 112                           int32_t rx, int32_t ry, struct timeval *time);
 113
 114 /*
 115  * Produces relative event that moves cursor to the point x, y.
 116  *
 117  * If timeval is NULL, current time is used.
 118  */
 119 void GP_EventQueuePushRelTo(struct GP_EventQueue *self,
 120                             uint32_t x, uint32_t y, struct timeval *time);
 121
 122 /*
 123  * Inject absolute event.
 124  *
 125  * If timeval is NULL, current time is used.
 126  */
 127 void GP_EventQueuePushAbs(struct GP_EventQueue *self,
 128                           uint32_t x, uint32_t y, uint32_t pressure,
 129                           uint32_t x_max, uint32_t y_max, uint32_t pressure_max,
 130                           struct timeval *time);
 131
 132 /*
 133  * Inject event that changes key state (i.e. press, release, repeat).
 134  *
 135  * If timeval is NULL, current time is used.
 136  */
 137 void GP_EventQueuePushKey(struct GP_EventQueue *self,
 138                           uint32_t key, uint8_t code, struct timeval *time);
 139
 140 /*
 141  * Inject window resize event
 142  */
 143 void GP_EventQueuePushResize(struct GP_EventQueue *self,
 144                              uint32_t w, uint32_t h, struct timeval *time);
 145
 146 /*
 147  * Inject common event.
 148  */
 149 void GP_EventQueuePush(struct GP_EventQueue *self,
 150                        uint16_t type, uint32_t code, int32_t value,
 151                        struct timeval *time);
 152
 153 -------------------------------------------------------------------------------
 154
 155 Following functions are used for puting events into the event queue. If
 156 pointer to the timeval structure is 'NULL' the event 'time' will be filled
 157 with exact time the event was added to the queue.