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 is
15 an object large enough to hold the data of any event type. All events
16 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 one-for-
139 one with physical key presses. Multiple key presses can combine
140 to generate a single character, e.g. apostrophe + e may produce
141 `é'. Fewer key presses can also generate more characters,
142 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 The X position of the top-left corner of the rectangle which was
351 exposed.
352 display.y (int)
354 The Y position of the top-left corner of the rectangle which was
355 exposed.
356 display.width (int)
358 The width of the rectangle which was exposed.
359 display.height (int)
361 The height of the rectangle which was exposed.
362 Note: The display needs to be created with ALLEGRO_GENERATE_EX‐
364 POSE_EVENTS flag for these events to be generated.
365 ALLEGRO_EVENT_DISPLAY_RESIZE
367 The window has been resized.
368 display.source (ALLEGRO_DISPLAY *)
370 The display which was resized.
371 display.x (int)
373 The X position of the top-left corner of the display.
374 display.y (int)
376 The Y position of the top-left corner of the display.
377 display.width (int)
379 The new width of the display.
380 display.height (int)
382 The new height of the display.
383 You should normally respond to these events by calling al_acknowl‐
385 edge_resize(3). Note that further resize events may be generated by
386 the time you process the event, so these fields may hold outdated in‐
387 formation.
388 ALLEGRO_EVENT_DISPLAY_CLOSE
390 The close button of the window has been pressed.
391 display.source (ALLEGRO_DISPLAY *)
393 The display which was closed.
394 ALLEGRO_EVENT_DISPLAY_LOST
396 When using Direct3D, displays can enter a “lost” state. In that state,
397 drawing calls are ignored, and upon entering the state, bitmap’s pixel
398 data can become undefined. Allegro does its best to preserve the cor‐
399 rect contents of bitmaps (see the ALLEGRO_NO_PRESERVE_TEXTURE flag) and
400 restore them when the device is “found” (see ALLEGRO_EVENT_DIS‐
401 PLAY_FOUND(3)). However, this is not 100% fool proof (see discussion
402 in al_create_bitmap(3)’s documentation).
403 Note: This event merely means that the display was lost, that
405 is, DirectX suddenly lost the contents of all video bitmaps. In
406 particular, you can keep calling drawing functions – they just
407 most likely won’t do anything. If Allegro’s restoration of the
408 bitmaps works well for you then no further action is required
409 when you receive this event.
410 display.source (ALLEGRO_DISPLAY *)
412 The display which was lost.
413 ALLEGRO_EVENT_DISPLAY_FOUND
415 Generated when a lost device is restored to operating state. See ALLE‐
416 GRO_EVENT_DISPLAY_LOST(3).
417 display.source (ALLEGRO_DISPLAY *)
419 The display which was found.
420 ALLEGRO_EVENT_DISPLAY_SWITCH_OUT
422 The window is no longer active, that is the user might have clicked in‐
423 to another window or “tabbed” away. In response to this event you
424 might want to call al_clear_keyboard_state(3) (possibly passing dis‐
425 play.source as its argument) in order to prevent Allegro’s keyboard
426 state from getting out of sync.
427 display.source (ALLEGRO_DISPLAY *)
429 The display which was switched out of.
430 ALLEGRO_EVENT_DISPLAY_SWITCH_IN
432 The window is the active one again.
433 display.source (ALLEGRO_DISPLAY *)
435 The display which was switched into.
436 ALLEGRO_EVENT_DISPLAY_ORIENTATION
438 Generated when the rotation or orientation of a display changes.
439 display.source (ALLEGRO_DISPLAY *)
441 The display which generated the event.
442 event.display.orientation
444 Contains one of the following values:
445 • ALLEGRO_DISPLAY_ORIENTATION_0_DEGREES
447 • ALLEGRO_DISPLAY_ORIENTATION_90_DEGREES
449 • ALLEGRO_DISPLAY_ORIENTATION_180_DEGREES
451 • ALLEGRO_DISPLAY_ORIENTATION_270_DEGREES
453 • ALLEGRO_DISPLAY_ORIENTATION_FACE_UP
455 • ALLEGRO_DISPLAY_ORIENTATION_FACE_DOWN
457 ALLEGRO_EVENT_DISPLAY_HALT_DRAWING
459 When a display receives this event it should stop doing any drawing and
460 then call al_acknowledge_drawing_halt(3) immediately.
461 This is currently only relevant for Android and iOS. It will be sent
463 when the application is switched to background mode, in addition to AL‐
464 LEGRO_EVENT_DISPLAY_SWITCH_OUT(3). The latter may also be sent in sit‐
465 uations where the application is not active but still should continue
466 drawing, for example when a popup is displayed in front of it.
467 Note: This event means that the next time you call a drawing
469 function, your program will crash. So you must stop drawing and
470 you must immediately reply with al_acknowledge_drawing_halt(3).
471 Allegro sends this event because it cannot handle this automati‐
472 cally. Your program might be doing the drawing in a different
473 thread from the event handling, in which case the drawing thread
474 needs to be signaled to stop drawing before acknowledging this
475 event.
476 Note: Mobile devices usually never quit an application, so to
478 prevent the battery from draining while your application is
479 halted it can be a good idea to call al_stop_timer(3) on all
480 your timers, otherwise they will keep generating events. If you
481 are using audio, you can also stop all audio voices (or pass
482 NULL to al_set_default_voice(3) if you use the default mixer),
483 otherwise Allegro will keep streaming silence to the voice even
484 if the stream or mixer are stopped or detached.
485
487 5.1.0
488
490 ALLEGRO_EVENT_DISPLAY_RESUME_DRAWING(3)
491 ALLEGRO_EVENT_DISPLAY_RESUME_DRAWING
493 When a display receives this event, it may resume drawing again, and it
494 must call al_acknowledge_drawing_resume(3) immediately.
495 This is currently only relevant for Android and iOS. The event will be
497 sent when an application returns from background mode and is allowed to
498 draw to the display again, in addition to ALLEGRO_EVENT_DIS‐
499 PLAY_SWITCH_IN(3). The latter event may also be sent in a situation
500 where the application is already active, for example when a popup in
501 front of it closes.
502 Note: Unlike ALLEGRO_EVENT_DISPLAY_FOUND(3) it is not necessary
504 to reload any bitmaps when you receive this event.
505
507 5.1.0
508
510 ALLEGRO_EVENT_DISPLAY_HALT_DRAWING(3)
511 ALLEGRO_EVENT_DISPLAY_CONNECTED
513 This event is sent when a physical display is connected to the device
514 Allegro runs on. Currently, on most platforms, Allegro supports only a
515 single physical display. However, on iOS, a secondary physical display
516 is supported.
517 display.source (ALLEGRO_DISPLAY *)
519 The display which was connected.
520
522 5.1.1
523 ALLEGRO_EVENT_DISPLAY_DISCONNECTED
525 This event is sent when a physical display is disconnected from the de‐
526 vice Allegro runs on. Currently, on most platforms, Allegro supports
527 only a single physical display. However, on iOS, a secondary physical
528 display is supported.
529 display.source (ALLEGRO_DISPLAY *)
531 The display which was disconnected.
532Allegro reference manual ALLEGRO_EVENT(3)