1ALLEGRO_EVENT(3) ALLEGRO_EVENT(3)
2
6 ALLEGRO_EVENT - Allegro 5 API
7
9 #include <allegro5/allegro.h>
10 typedef union ALLEGRO_EVENT ALLEGRO_EVENT;
12
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 type (ALLEGRO_EVENT_TYPE)
19 Indicates the type of event.
20 any.source (ALLEGRO_EVENT_SOURCE *)
22 The event source which generated the event.
23 any.timestamp (double)
25 When the event was generated.
26 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 Each event is of one of the following types, with the usable fields
34 given.
35 ALLEGRO_EVENT_JOYSTICK_AXIS
37 A joystick axis value changed.
38 joystick.id (ALLEGRO_JOYSTICK *)
40 The joystick which generated the event. This is not the same as
41 the event source joystick.source.
42 joystick.stick (int)
44 The stick number, counting from zero. Axes on a joystick are
45 grouped into "sticks".
46 joystick.axis (int)
48 The axis number on the stick, counting from zero.
49 joystick.pos (float)
51 The axis position, from -1.0 to +1.0.
52 ALLEGRO_EVENT_JOYSTICK_BUTTON_DOWN
54 A joystick button was pressed.
55 joystick.id (ALLEGRO_JOYSTICK *)
57 The joystick which generated the event.
58 joystick.button (int)
60 The button which was pressed, counting from zero.
61 ALLEGRO_EVENT_JOYSTICK_BUTTON_UP
63 A joystick button was released.
64 joystick.id (ALLEGRO_JOYSTICK *)
66 The joystick which generated the event.
67 joystick.button (int)
69 The button which was released, counting from zero.
70 ALLEGRO_EVENT_JOYSTICK_CONFIGURATION
72 A joystick was plugged in or unplugged. See al_reconfigure_joy‐
73 sticks(3) for details.
74 ALLEGRO_EVENT_KEY_DOWN
76 A keyboard key was pressed.
77 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 keyboard.display (ALLEGRO_DISPLAY *)
84 The display which had keyboard focus when the event occurred.
85 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 ALLEGRO_EVENT_KEY_UP
91 A keyboard key was released.
92 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 keyboard.display (ALLEGRO_DISPLAY *)
99 The display which had keyboard focus when the event occurred.
100 ALLEGRO_EVENT_KEY_CHAR
102 A character was typed on the keyboard, or a character was auto-repeat‐
103 ed.
104 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 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 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 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 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 keyboard.repeat (bool)
133 Indicates if this is a repeated character.
134 keyboard.display (ALLEGRO_DISPLAY *)
136 The display which had keyboard focus when the event occurred.
137 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 ALLEGRO_EVENT_MOUSE_AXES
145 One or more mouse axis values changed.
146 mouse.x (int)
148 x-coordinate
149 mouse.y (int)
151 y-coordinate
152 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 mouse.w (int)
158 w-coordinate. This usually means the horizontal axis of a mouse
159 wheel.
160 mouse.dx (int)
162 Change in the x-coordinate value since the previous ALLE‐
163 GRO_EVENT_MOUSE_AXES event.
164 mouse.dy (int)
166 Change in the y-coordinate value since the previous ALLE‐
167 GRO_EVENT_MOUSE_AXES event.
168 mouse.dz (int)
170 Change in the z-coordinate value since the previous ALLE‐
171 GRO_EVENT_MOUSE_AXES event.
172 mouse.dw (int)
174 Change in the w-coordinate value since the previous ALLE‐
175 GRO_EVENT_MOUSE_AXES event.
176 mouse.pressure (float)
178 Pressure, ranging from 0.0 to 1.0.
179 mouse.display (ALLEGRO_DISPLAY *)
181 The display which had mouse focus.
182 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 Note: currently mouse.display may be NULL if an event is gener‐
189 ated in response to al_set_mouse_axis(3).
190 ALLEGRO_EVENT_MOUSE_BUTTON_DOWN
192 A mouse button was pressed.
193 mouse.x (int)
195 x-coordinate
196 mouse.y (int)
198 y-coordinate
199 mouse.z (int)
201 z-coordinate
202 mouse.w (int)
204 w-coordinate
205 mouse.button (unsigned)
207 The mouse button which was pressed, numbering from 1.
208 mouse.pressure (float)
210 Pressure, ranging from 0.0 to 1.0.
211 mouse.display (ALLEGRO_DISPLAY *)
213 The display which had mouse focus.
214 ALLEGRO_EVENT_MOUSE_BUTTON_UP
216 A mouse button was released.
217 mouse.x (int)
219 x-coordinate
220 mouse.y (int)
222 y-coordinate
223 mouse.z (int)
225 z-coordinate
226 mouse.w (int)
228 w-coordinate
229 mouse.button (unsigned)
231 The mouse button which was released, numbering from 1.
232 mouse.pressure (float)
234 Pressure, ranging from 0.0 to 1.0.
235 mouse.display (ALLEGRO_DISPLAY *)
237 The display which had mouse focus.
238 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 ALLEGRO_EVENT_MOUSE_ENTER_DISPLAY
244 The mouse cursor entered a window opened by the program.
245 mouse.x (int)
247 x-coordinate
248 mouse.y (int)
250 y-coordinate
251 mouse.z (int)
253 z-coordinate
254 mouse.w (int)
256 w-coordinate
257 mouse.display (ALLEGRO_DISPLAY *)
259 The display which had mouse focus.
260 ALLEGRO_EVENT_MOUSE_LEAVE_DISPLAY
262 The mouse cursor left the boundaries of a window opened by the program.
263 mouse.x (int)
265 x-coordinate
266 mouse.y (int)
268 y-coordinate
269 mouse.z (int)
271 z-coordinate
272 mouse.w (int)
274 w-coordinate
275 mouse.display (ALLEGRO_DISPLAY *)
277 The display which had mouse focus.
278 ALLEGRO_EVENT_TOUCH_BEGIN
280 The touch input device registered a new touch.
281 touch.display (ALLEGRO_DISPLAY)
283 The display which was touched.
284 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 touch.x (float)
291 The x coordinate of the touch in pixels.
292 touch.y (float)
294 The y coordinate of the touch in pixels.
295 touch.dx (float)
297 Movement speed in pixels in x direction.
298 touch.dy (float)
300 Movement speed in pixels in y direction.
301 touch.primary (bool)
303 Whether this is the only/first touch or an additional touch.
304
306 5.1.0
307 ALLEGRO_EVENT_TOUCH_END
309 A touch ended.
310 Has the same fields as ALLEGRO_EVENT_TOUCH_BEGIN(3).
312
314 5.1.0
315 ALLEGRO_EVENT_TOUCH_MOVE
317 The position of a touch changed.
318 Has the same fields as ALLEGRO_EVENT_TOUCH_BEGIN(3).
320
322 5.1.0
323 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 Has the same fields as ALLEGRO_EVENT_TOUCH_BEGIN(3).
330
332 5.1.0
333 ALLEGRO_EVENT_TIMER
335 A [timer]ALLEGRO_TIMER(3) counter incremented.
336 timer.source (ALLEGRO_TIMER *)
338 The timer which generated the event.
339 timer.count (int64_t)
341 The timer count value.
342 ALLEGRO_EVENT_DISPLAY_EXPOSE
344 The display (or a portion thereof) has become visible.
345 display.source (ALLEGRO_DISPLAY *)
347 The display which was exposed.
348 display.x (int)
350 display.y (int)
351 The top-left corner of the rectangle which was exposed.
353 display.width (int)
355 display.height (int)
356 The width and height of the rectangle which was exposed.
357 Note: The display needs to be created with ALLEGRO_GENERATE_EX‐
359 POSE_EVENTS flag for these events to be generated.
360 ALLEGRO_EVENT_DISPLAY_RESIZE
362 The window has been resized.
363 display.source (ALLEGRO_DISPLAY *)
365 The display which was resized.
366 display.x (int)
368 display.y (int)
369 The position of the top-level corner of the display.
370 display.width (int)
372 The new width of the display.
373 display.height (int)
375 The new height of the display.
376 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 ALLEGRO_EVENT_DISPLAY_CLOSE
383 The close button of the window has been pressed.
384 display.source (ALLEGRO_DISPLAY *)
386 The display which was closed.
387 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 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 display.source (ALLEGRO_DISPLAY *)
405 The display which was lost.
406 ALLEGRO_EVENT_DISPLAY_FOUND
408 Generated when a lost device is restored to operating state. See ALLE‐
409 GRO_EVENT_DISPLAY_LOST(3).
410 display.source (ALLEGRO_DISPLAY *)
412 The display which was found.
413 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 display.source (ALLEGRO_DISPLAY *)
422 The display which was switched out of.
423 ALLEGRO_EVENT_DISPLAY_SWITCH_IN
425 The window is the active one again.
426 display.source (ALLEGRO_DISPLAY *)
428 The display which was switched into.
429 ALLEGRO_EVENT_DISPLAY_ORIENTATION
431 Generated when the rotation or orientation of a display changes.
432 display.source (ALLEGRO_DISPLAY *)
434 The display which generated the event.
435 event.display.orientation
437 Contains one of the following values:
438 · ALLEGRO_DISPLAY_ORIENTATION_0_DEGREES
440 · ALLEGRO_DISPLAY_ORIENTATION_90_DEGREES
442 · ALLEGRO_DISPLAY_ORIENTATION_180_DEGREES
444 · ALLEGRO_DISPLAY_ORIENTATION_270_DEGREES
446 · ALLEGRO_DISPLAY_ORIENTATION_FACE_UP
448 · ALLEGRO_DISPLAY_ORIENTATION_FACE_DOWN
450 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 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 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 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
480 5.1.0
481
483 ALLEGRO_EVENT_DISPLAY_RESUME_DRAWING(3)
484 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 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 Note: Unlike ALLEGRO_EVENT_DISPLAY_FOUND(3) it is not necessary
497 to reload any bitmaps when you receive this event.
498
500 5.1.0
501
503 ALLEGRO_EVENT_DISPLAY_HALT_DRAWING(3)
504 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 display.source (ALLEGRO_DISPLAY *)
512 The display which was connected.
513
515 5.1.1
516 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 display.source (ALLEGRO_DISPLAY *)
524 The display which was disconnected.
525Allegro reference manual ALLEGRO_EVENT(3)