1ALLEGRO_EVENT(3)                                              ALLEGRO_EVENT(3)
2
3
4

NAME

6       ALLEGRO_EVENT - Allegro 5 API
7

SYNOPSIS

9              #include <allegro5/allegro.h>
10
11              typedef union ALLEGRO_EVENT ALLEGRO_EVENT;
12

DESCRIPTION

14       An  ALLEGRO_EVENT  is a union of all builtin event structures, i.e.  it
15       is an object large enough to hold the data  of  any  event  type.   All
16       events have the following fields in common:
17
18       type (ALLEGRO_EVENT_TYPE)
19              Indicates the type of event.
20
21       any.source (ALLEGRO_EVENT_SOURCE *)
22              The event source which generated the event.
23
24       any.timestamp (double)
25              When the event was generated.
26
27       By  examining  the type field you can then access type-specific fields.
28       The any.source field tells you which event source generated  that  par‐
29       ticular  event.   The  any.timestamp field tells you when the event was
30       generated.  The time is  referenced  to  the  same  starting  point  as
31       al_get_time(3).
32
33       Each  event  is  of  one of the following types, with the usable fields
34       given.
35
36   ALLEGRO_EVENT_JOYSTICK_AXIS
37       A joystick axis value changed.
38
39       joystick.id (ALLEGRO_JOYSTICK *)
40              The joystick which generated the event.  This is not the same as
41              the event source joystick.source.
42
43       joystick.stick (int)
44              The  stick  number,  counting from zero.  Axes on a joystick are
45              grouped into "sticks".
46
47       joystick.axis (int)
48              The axis number on the stick, counting from zero.
49
50       joystick.pos (float)
51              The axis position, from -1.0 to +1.0.
52
53   ALLEGRO_EVENT_JOYSTICK_BUTTON_DOWN
54       A joystick button was pressed.
55
56       joystick.id (ALLEGRO_JOYSTICK *)
57              The joystick which generated the event.
58
59       joystick.button (int)
60              The button which was pressed, counting from zero.
61
62   ALLEGRO_EVENT_JOYSTICK_BUTTON_UP
63       A joystick button was released.
64
65       joystick.id (ALLEGRO_JOYSTICK *)
66              The joystick which generated the event.
67
68       joystick.button (int)
69              The button which was released, counting from zero.
70
71   ALLEGRO_EVENT_JOYSTICK_CONFIGURATION
72       A joystick  was  plugged  in  or  unplugged.   See  al_reconfigure_joy‐
73       sticks(3) for details.
74
75   ALLEGRO_EVENT_KEY_DOWN
76       A keyboard key was pressed.
77
78       keyboard.keycode (int)
79              The  code  corresponding  to the physical key which was pressed.
80              See the [Key codes] section for the list of  ALLEGRO_KEY_*  con‐
81              stants.
82
83       keyboard.display (ALLEGRO_DISPLAY *)
84              The display which had keyboard focus when the event occurred.
85
86              Note: this event is about the physical keys being pressed on the
87              keyboard.  Look for ALLEGRO_EVENT_KEY_CHAR events for  character
88              input.
89
90   ALLEGRO_EVENT_KEY_UP
91       A keyboard key was released.
92
93       keyboard.keycode (int)
94              The  code  corresponding to the physical key which was released.
95              See the [Key codes] section for the list of  ALLEGRO_KEY_*  con‐
96              stants.
97
98       keyboard.display (ALLEGRO_DISPLAY *)
99              The display which had keyboard focus when the event occurred.
100
101   ALLEGRO_EVENT_KEY_CHAR
102       A  character was typed on the keyboard, or a character was auto-repeat‐
103       ed.
104
105       keyboard.keycode (int)
106              The code corresponding  to  the  physical  key  which  was  last
107              pressed.   See  the  [Key  codes]  section for the list of ALLE‐
108              GRO_KEY_* constants.
109
110       keyboard.unichar (int)
111              A Unicode code point (character).  This may be zero or  negative
112              if  the  event was generated for a non-visible "character", such
113              as an arrow or Function key.  In that case you can act upon  the
114              keycode field.
115
116              Some  special  keys will set the unichar field to their standard
117              ASCII values: Tab=9, Return=13, Escape=27.  In addition  if  you
118              press  the  Control  key  together with A to Z the unichar field
119              will have the values 1 to  26.   For  example  Ctrl-A  will  set
120              unichar to 1 and Ctrl-H will set it to 8.
121
122              As of Allegro 5.0.2 there are some inconsistencies in the treat‐
123              ment of Backspace (8 or 127) and Delete (127 or 0) keys on  dif‐
124              ferent  platforms.   These  can be worked around by checking the
125              keycode field.
126
127       keyboard.modifiers (unsigned)
128              This is a bitfield of the modifier keys which were pressed  when
129              the  event occurred.  See "Keyboard modifier flags" for the con‐
130              stants.
131
132       keyboard.repeat (bool)
133              Indicates if this is a repeated character.
134
135       keyboard.display (ALLEGRO_DISPLAY *)
136              The display which had keyboard focus when the event occurred.
137
138              Note:  in  many  input  methods,  characters  are  not   entered
139              one-for-one with physical key presses.  Multiple key presses can
140              combine to generate a single character, e.g.  apostrophe + e may
141              produce  'é'.   Fewer key presses can also generate more charac‐
142              ters, e.g.  macro sequences expanding to common phrases.
143
144   ALLEGRO_EVENT_MOUSE_AXES
145       One or more mouse axis values changed.
146
147       mouse.x (int)
148              x-coordinate
149
150       mouse.y (int)
151              y-coordinate
152
153       mouse.z (int)
154              z-coordinate.  This usually means the vertical axis of  a  mouse
155              wheel, where up is positive and down is negative.
156
157       mouse.w (int)
158              w-coordinate.  This usually means the horizontal axis of a mouse
159              wheel.
160
161       mouse.dx (int)
162              Change in  the  x-coordinate  value  since  the  previous  ALLE‐
163              GRO_EVENT_MOUSE_AXES event.
164
165       mouse.dy (int)
166              Change  in  the  y-coordinate  value  since  the  previous ALLE‐
167              GRO_EVENT_MOUSE_AXES event.
168
169       mouse.dz (int)
170              Change in  the  z-coordinate  value  since  the  previous  ALLE‐
171              GRO_EVENT_MOUSE_AXES event.
172
173       mouse.dw (int)
174              Change  in  the  w-coordinate  value  since  the  previous ALLE‐
175              GRO_EVENT_MOUSE_AXES event.
176
177       mouse.pressure (float)
178              Pressure, ranging from 0.0 to 1.0.
179
180       mouse.display (ALLEGRO_DISPLAY *)
181              The display which had mouse focus.
182
183              Note: Calling al_set_mouse_xy(3) also will result in a change of
184              axis   values,   but  such  a  change  is  reported  with  ALLE‐
185              GRO_EVENT_MOUSE_WARPED(3) events instead which are identical ex‐
186              cept for their type.
187
188              Note:  currently mouse.display may be NULL if an event is gener‐
189              ated in response to al_set_mouse_axis(3).
190
191   ALLEGRO_EVENT_MOUSE_BUTTON_DOWN
192       A mouse button was pressed.
193
194       mouse.x (int)
195              x-coordinate
196
197       mouse.y (int)
198              y-coordinate
199
200       mouse.z (int)
201              z-coordinate
202
203       mouse.w (int)
204              w-coordinate
205
206       mouse.button (unsigned)
207              The mouse button which was pressed, numbering from 1.
208
209       mouse.pressure (float)
210              Pressure, ranging from 0.0 to 1.0.
211
212       mouse.display (ALLEGRO_DISPLAY *)
213              The display which had mouse focus.
214
215   ALLEGRO_EVENT_MOUSE_BUTTON_UP
216       A mouse button was released.
217
218       mouse.x (int)
219              x-coordinate
220
221       mouse.y (int)
222              y-coordinate
223
224       mouse.z (int)
225              z-coordinate
226
227       mouse.w (int)
228              w-coordinate
229
230       mouse.button (unsigned)
231              The mouse button which was released, numbering from 1.
232
233       mouse.pressure (float)
234              Pressure, ranging from 0.0 to 1.0.
235
236       mouse.display (ALLEGRO_DISPLAY *)
237              The display which had mouse focus.
238
239   ALLEGRO_EVENT_MOUSE_WARPED
240       al_set_mouse_xy(3) was called to move the mouse.  This event is identi‐
241       cal to ALLEGRO_EVENT_MOUSE_AXES otherwise.
242
243   ALLEGRO_EVENT_MOUSE_ENTER_DISPLAY
244       The mouse cursor entered a window opened by the program.
245
246       mouse.x (int)
247              x-coordinate
248
249       mouse.y (int)
250              y-coordinate
251
252       mouse.z (int)
253              z-coordinate
254
255       mouse.w (int)
256              w-coordinate
257
258       mouse.display (ALLEGRO_DISPLAY *)
259              The display which had mouse focus.
260
261   ALLEGRO_EVENT_MOUSE_LEAVE_DISPLAY
262       The mouse cursor left the boundaries of a window opened by the program.
263
264       mouse.x (int)
265              x-coordinate
266
267       mouse.y (int)
268              y-coordinate
269
270       mouse.z (int)
271              z-coordinate
272
273       mouse.w (int)
274              w-coordinate
275
276       mouse.display (ALLEGRO_DISPLAY *)
277              The display which had mouse focus.
278
279   ALLEGRO_EVENT_TOUCH_BEGIN
280       The touch input device registered a new touch.
281
282       touch.display (ALLEGRO_DISPLAY)
283              The display which was touched.
284
285       touch.id (int)
286              An  identifier  for  this  touch.  If supported by the device it
287              will stay the same for events from the  same  finger  until  the
288              touch ends.
289
290       touch.x (float)
291              The x coordinate of the touch in pixels.
292
293       touch.y (float)
294              The y coordinate of the touch in pixels.
295
296       touch.dx (float)
297              Movement speed in pixels in x direction.
298
299       touch.dy (float)
300              Movement speed in pixels in y direction.
301
302       touch.primary (bool)
303              Whether this is the only/first touch or an additional touch.
304

SINCE

306       5.1.0
307
308   ALLEGRO_EVENT_TOUCH_END
309       A touch ended.
310
311       Has the same fields as ALLEGRO_EVENT_TOUCH_BEGIN(3).
312

SINCE

314       5.1.0
315
316   ALLEGRO_EVENT_TOUCH_MOVE
317       The position of a touch changed.
318
319       Has the same fields as ALLEGRO_EVENT_TOUCH_BEGIN(3).
320

SINCE

322       5.1.0
323
324   ALLEGRO_EVENT_TOUCH_CANCEL
325       A  touch  was cancelled.  This is device specific but could for example
326       mean that a finger moved off the border of the device or moved so  fast
327       that it could not be tracked any longer.
328
329       Has the same fields as ALLEGRO_EVENT_TOUCH_BEGIN(3).
330

SINCE

332       5.1.0
333
334   ALLEGRO_EVENT_TIMER
335       A [timer]ALLEGRO_TIMER(3) counter incremented.
336
337       timer.source (ALLEGRO_TIMER *)
338              The timer which generated the event.
339
340       timer.count (int64_t)
341              The timer count value.
342
343   ALLEGRO_EVENT_DISPLAY_EXPOSE
344       The display (or a portion thereof) has become visible.
345
346       display.source (ALLEGRO_DISPLAY *)
347              The display which was exposed.
348
349       display.x (int)
350                display.y (int)
351
352       The top-left corner of the rectangle which was exposed.
353
354       display.width (int)
355                display.height (int)
356       The width and height of the rectangle which was exposed.
357
358              Note:  The display needs to be created with ALLEGRO_GENERATE_EX‐
359              POSE_EVENTS flag for these events to be generated.
360
361   ALLEGRO_EVENT_DISPLAY_RESIZE
362       The window has been resized.
363
364       display.source (ALLEGRO_DISPLAY *)
365              The display which was resized.
366
367       display.x (int)
368                display.y (int)
369       The position of the top-level corner of the display.
370
371       display.width (int)
372              The new width of the display.
373
374       display.height (int)
375              The new height of the display.
376
377       You should normally respond to  these  events  by  calling  al_acknowl‐
378       edge_resize(3).   Note  that  further resize events may be generated by
379       the time you process the event, so these fields may hold  outdated  in‐
380       formation.
381
382   ALLEGRO_EVENT_DISPLAY_CLOSE
383       The close button of the window has been pressed.
384
385       display.source (ALLEGRO_DISPLAY *)
386              The display which was closed.
387
388   ALLEGRO_EVENT_DISPLAY_LOST
389       When using Direct3D, displays can enter a "lost" state.  In that state,
390       drawing calls are ignored, and upon entering the state, bitmap's  pixel
391       data  can become undefined.  Allegro does its best to preserve the cor‐
392       rect contents of bitmaps (see the ALLEGRO_NO_PRESERVE_TEXTURE flag) and
393       restore  them  when  the  device  is  "found"  (see  ALLEGRO_EVENT_DIS‐
394       PLAY_FOUND(3)).  However, this is not 100% fool proof  (see  discussion
395       in al_create_bitmap(3)'s documentation).
396
397              Note:  This  event  merely means that the display was lost, that
398              is, DirectX suddenly lost the contents of all video bitmaps.  In
399              particular,  you can keep calling drawing functions -- they just
400              most likely won't do anything.  If Allegro's restoration of  the
401              bitmaps  works  well  for you then no further action is required
402              when you receive this event.
403
404       display.source (ALLEGRO_DISPLAY *)
405              The display which was lost.
406
407   ALLEGRO_EVENT_DISPLAY_FOUND
408       Generated when a lost device is restored to operating state.  See ALLE‐
409       GRO_EVENT_DISPLAY_LOST(3).
410
411       display.source (ALLEGRO_DISPLAY *)
412              The display which was found.
413
414   ALLEGRO_EVENT_DISPLAY_SWITCH_OUT
415       The window is no longer active, that is the user might have clicked in‐
416       to another window or "tabbed" away.  In  response  to  this  event  you
417       might  want  to  call al_clear_keyboard_state(3) (possibly passing dis‐
418       play.source as its argument) in order  to  prevent  Allegro's  keyboard
419       state from getting out of sync.
420
421       display.source (ALLEGRO_DISPLAY *)
422              The display which was switched out of.
423
424   ALLEGRO_EVENT_DISPLAY_SWITCH_IN
425       The window is the active one again.
426
427       display.source (ALLEGRO_DISPLAY *)
428              The display which was switched into.
429
430   ALLEGRO_EVENT_DISPLAY_ORIENTATION
431       Generated when the rotation or orientation of a display changes.
432
433       display.source (ALLEGRO_DISPLAY *)
434              The display which generated the event.
435
436       event.display.orientation
437              Contains one of the following values:
438
439              · ALLEGRO_DISPLAY_ORIENTATION_0_DEGREES
440
441              · ALLEGRO_DISPLAY_ORIENTATION_90_DEGREES
442
443              · ALLEGRO_DISPLAY_ORIENTATION_180_DEGREES
444
445              · ALLEGRO_DISPLAY_ORIENTATION_270_DEGREES
446
447              · ALLEGRO_DISPLAY_ORIENTATION_FACE_UP
448
449              · ALLEGRO_DISPLAY_ORIENTATION_FACE_DOWN
450
451   ALLEGRO_EVENT_DISPLAY_HALT_DRAWING
452       When a display receives this event it should stop doing any drawing and
453       then call al_acknowledge_drawing_halt(3) immediately.
454
455       This is currently only relevant for Android and iOS.  It will  be  sent
456       when the application is switched to background mode, in addition to AL‐
457       LEGRO_EVENT_DISPLAY_SWITCH_OUT(3).  The latter may also be sent in sit‐
458       uations  where  the application is not active but still should continue
459       drawing, for example when a popup is displayed in front of it.
460
461              Note: This event means that the next time  you  call  a  drawing
462              function, your program will crash.  So you must stop drawing and
463              you must immediately reply with  al_acknowledge_drawing_halt(3).
464              Allegro sends this event because it cannot handle this automati‐
465              cally.  Your program might be doing the drawing in  a  different
466              thread from the event handling, in which case the drawing thread
467              needs to be signaled to stop drawing before  acknowledging  this
468              event.
469
470              Note:  Mobile  devices  usually never quit an application, so to
471              prevent the battery from  draining  while  your  application  is
472              halted  it  can  be  a good idea to call al_stop_timer(3) on all
473              your timers, otherwise they will keep generating events.  If you
474              are  using  audio,  you  can also stop all audio voices (or pass
475              NULL to al_set_default_voice(3) if you use the  default  mixer),
476              otherwise  Allegro will keep streaming silence to the voice even
477              if the stream or mixer are stopped or detached.
478

SINCE

480       5.1.0
481

SEE ALSO

483       ALLEGRO_EVENT_DISPLAY_RESUME_DRAWING(3)
484
485   ALLEGRO_EVENT_DISPLAY_RESUME_DRAWING
486       When a display receives this event, it may resume drawing again, and it
487       must call al_acknowledge_drawing_resume(3) immediately.
488
489       This is currently only relevant for Android and iOS.  The event will be
490       sent when an application returns from background mode and is allowed to
491       draw   to   the   display  again,  in  addition  to  ALLEGRO_EVENT_DIS‐
492       PLAY_SWITCH_IN(3).  The latter event may also be sent  in  a  situation
493       where  the  application  is already active, for example when a popup in
494       front of it closes.
495
496              Note: Unlike ALLEGRO_EVENT_DISPLAY_FOUND(3) it is not  necessary
497              to reload any bitmaps when you receive this event.
498

SINCE

500       5.1.0
501

SEE ALSO

503       ALLEGRO_EVENT_DISPLAY_HALT_DRAWING(3)
504
505   ALLEGRO_EVENT_DISPLAY_CONNECTED
506       This  event  is sent when a physical display is connected to the device
507       Allegro runs on.  Currently, on most platforms, Allegro supports only a
508       single physical display.  However, on iOS, a secondary physical display
509       is supported.
510
511       display.source (ALLEGRO_DISPLAY *)
512              The display which was connected.
513

SINCE

515       5.1.1
516
517   ALLEGRO_EVENT_DISPLAY_DISCONNECTED
518       This event is sent when a physical display is disconnected from the de‐
519       vice  Allegro  runs on.  Currently, on most platforms, Allegro supports
520       only a single physical display.  However, on iOS, a secondary  physical
521       display is supported.
522
523       display.source (ALLEGRO_DISPLAY *)
524              The display which was disconnected.
525
526
527
528Allegro reference manual                                      ALLEGRO_EVENT(3)
Impressum