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 *) : The event source which generated
22 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 *) : The joystick which generated the
40 event. This is not the same as the event source joystick.source.
41 joystick.stick (int)
43 The stick number, counting from zero. Axes on a joystick are
44 grouped into "sticks".
45 joystick.axis (int)
47 The axis number on the stick, counting from zero.
48 joystick.pos (float)
50 The axis position, from -1.0 to +1.0.
51 ALLEGRO_EVENT_JOYSTICK_BUTTON_DOWN
53 A joystick button was pressed.
54 joystick.id (ALLEGRO_JOYSTICK *) : The joystick which generated the
56 event.
57 joystick.button (int)
59 The button which was pressed, counting from zero.
60 ALLEGRO_EVENT_JOYSTICK_BUTTON_UP
62 A joystick button was released.
63 joystick.id (ALLEGRO_JOYSTICK *) : The joystick which generated the
65 event.
66 joystick.button (int)
68 The button which was released, counting from zero.
69 ALLEGRO_EVENT_JOYSTICK_CONFIGURATION
71 A joystick was plugged in or unplugged. See al_reconfigure_joy‐
72 sticks(3) for details.
73 ALLEGRO_EVENT_KEY_DOWN
75 A keyboard key was pressed.
76 keyboard.keycode (int)
78 The code corresponding to the physical key which was pressed.
79 See the [Key codes] section for the list of ALLEGRO_KEY_* con‐
80 stants.
81 keyboard.display (ALLEGRO_DISPLAY *) : The display which had keyboard
83 focus when the event occurred.
84 Note: this event is about the physical keys being pressed on the
86 keyboard. Look for ALLEGRO_EVENT_KEY_CHAR events for character
87 input.
88 ALLEGRO_EVENT_KEY_UP
90 A keyboard key was released.
91 keyboard.keycode (int)
93 The code corresponding to the physical key which was released.
94 See the [Key codes] section for the list of ALLEGRO_KEY_* con‐
95 stants.
96 keyboard.display (ALLEGRO_DISPLAY *) : The display which had keyboard
98 focus when the event occurred.
99 ALLEGRO_EVENT_KEY_CHAR
101 A character was typed on the keyboard, or a character was
102 auto-repeated.
103 keyboard.keycode (int)
105 The code corresponding to the physical key which was last
106 pressed. See the [Key codes] section for the list of ALLE‐
107 GRO_KEY_* constants.
108 keyboard.unichar (int)
110 A Unicode code point (character). This may be zero or negative
111 if the event was generated for a non-visible "character", such
112 as an arrow or Function key. In that case you can act upon the
113 keycode field.
114 Some special keys will set the unichar field to their standard
116 ASCII values: Tab=9, Return=13, Escape=27. In addition if you
117 press the Control key together with A to Z the unichar field
118 will have the values 1 to 26. For example Ctrl-A will set
119 unichar to 1 and Ctrl-H will set it to 8.
120 As of Allegro 5.0.2 there are some inconsistencies in the treat‐
122 ment of Backspace (8 or 127) and Delete (127 or 0) keys on dif‐
123 ferent platforms. These can be worked around by checking the
124 keycode field.
125 keyboard.modifiers (unsigned)
127 This is a bitfield of the modifier keys which were pressed when
128 the event occurred. See "Keyboard modifier flags" for the con‐
129 stants.
130 keyboard.repeat (bool)
132 Indicates if this is a repeated character.
133 keyboard.display (ALLEGRO_DISPLAY *) : The display which had keyboard
135 focus when the event occurred.
136 Note: in many input methods, characters are not entered
138 one-for-one with physical key presses. Multiple key presses can
139 combine to generate a single character, e.g. apostrophe + e may
140 produce 'é'. Fewer key presses can also generate more charac‐
141 ters, e.g. macro sequences expanding to common phrases.
142 ALLEGRO_EVENT_MOUSE_AXES
144 One or more mouse axis values changed.
145 mouse.x (int)
147 x-coordinate
148 mouse.y (int)
150 y-coordinate
151 mouse.z (int)
153 z-coordinate. This usually means the vertical axis of a mouse
154 wheel, where up is positive and down is negative.
155 mouse.w (int)
157 w-coordinate. This usually means the horizontal axis of a mouse
158 wheel.
159 mouse.dx (int)
161 Change in the x-coordinate value since the previous ALLE‐
162 GRO_EVENT_MOUSE_AXES event.
163 mouse.dy (int)
165 Change in the y-coordinate value since the previous ALLE‐
166 GRO_EVENT_MOUSE_AXES event.
167 mouse.dz (int)
169 Change in the z-coordinate value since the previous ALLE‐
170 GRO_EVENT_MOUSE_AXES event.
171 mouse.dw (int)
173 Change in the w-coordinate value since the previous ALLE‐
174 GRO_EVENT_MOUSE_AXES event.
175 mouse.pressure (float)
177 Pressure, ranging from 0.0 to 1.0.
178 mouse.display (ALLEGRO_DISPLAY *) : The display which had mouse focus.
180 Note: Calling al_set_mouse_xy(3) also will result in a change of
182 axis values, but such a change is reported with ALLE‐
183 GRO_EVENT_MOUSE_WARPED(3) events instead which are identical
184 except for their type.
185 Note: currently mouse.display may be NULL if an event is gener‐
187 ated in response to al_set_mouse_axis(3).
188 ALLEGRO_EVENT_MOUSE_BUTTON_DOWN
190 A mouse button was pressed.
191 mouse.x (int)
193 x-coordinate
194 mouse.y (int)
196 y-coordinate
197 mouse.z (int)
199 z-coordinate
200 mouse.w (int)
202 w-coordinate
203 mouse.button (unsigned)
205 The mouse button which was pressed, numbering from 1.
206 mouse.pressure (float)
208 Pressure, ranging from 0.0 to 1.0.
209 mouse.display (ALLEGRO_DISPLAY *) : The display which had mouse focus.
211 ALLEGRO_EVENT_MOUSE_BUTTON_UP
213 A mouse button was released.
214 mouse.x (int)
216 x-coordinate
217 mouse.y (int)
219 y-coordinate
220 mouse.z (int)
222 z-coordinate
223 mouse.w (int)
225 w-coordinate
226 mouse.button (unsigned)
228 The mouse button which was released, numbering from 1.
229 mouse.pressure (float)
231 Pressure, ranging from 0.0 to 1.0.
232 mouse.display (ALLEGRO_DISPLAY *) : The display which had mouse focus.
234 ALLEGRO_EVENT_MOUSE_WARPED
236 al_set_mouse_xy(3) was called to move the mouse. This event is identi‐
237 cal to ALLEGRO_EVENT_MOUSE_AXES otherwise.
238 ALLEGRO_EVENT_MOUSE_ENTER_DISPLAY
240 The mouse cursor entered a window opened by the program.
241 mouse.x (int)
243 x-coordinate
244 mouse.y (int)
246 y-coordinate
247 mouse.z (int)
249 z-coordinate
250 mouse.w (int)
252 w-coordinate
253 mouse.display (ALLEGRO_DISPLAY *) : The display which had mouse focus.
255 ALLEGRO_EVENT_MOUSE_LEAVE_DISPLAY
257 The mouse cursor left the boundaries of a window opened by the program.
258 mouse.x (int)
260 x-coordinate
261 mouse.y (int)
263 y-coordinate
264 mouse.z (int)
266 z-coordinate
267 mouse.w (int)
269 w-coordinate
270 mouse.display (ALLEGRO_DISPLAY *) : The display which had mouse focus.
272 ALLEGRO_EVENT_TOUCH_BEGIN
274 The touch input device registered a new touch.
275 touch.display (ALLEGRO_DISPLAY)
277 The display which was touched.
278 touch.id (int)
280 An identifier for this touch. If supported by the device it
281 will stay the same for events from the same finger until the
282 touch ends.
283 touch.x (float)
285 The x coordinate of the touch in pixels.
286 touch.y (float)
288 The y coordinate of the touch in pixels.
289 touch.dx (float)
291 Movement speed in pixels in x direction.
292 touch.dy (float)
294 Movement speed in pixels in y direction.
295 touch.primary (bool)
297 Whether this is the only/first touch or an additional touch.
298
300 5.1.0
301 ALLEGRO_EVENT_TOUCH_END
303 A touch ended.
304 Has the same fields as ALLEGRO_EVENT_TOUCH_BEGIN(3).
306
308 5.1.0
309 ALLEGRO_EVENT_TOUCH_MOVE
311 The position of a touch changed.
312 Has the same fields as ALLEGRO_EVENT_TOUCH_BEGIN(3).
314
316 5.1.0
317 ALLEGRO_EVENT_TOUCH_CANCEL
319 A touch was cancelled. This is device specific but could for example
320 mean that a finger moved off the border of the device or moved so fast
321 that it could not be tracked any longer.
322 Has the same fields as ALLEGRO_EVENT_TOUCH_BEGIN(3).
324
326 5.1.0
327 ALLEGRO_EVENT_TIMER
329 A [timer]ALLEGRO_TIMER(3) counter incremented.
330 timer.source (ALLEGRO_TIMER *) : The timer which generated the event.
332 timer.count (int64_t)
334 The timer count value.
335 ALLEGRO_EVENT_DISPLAY_EXPOSE
337 The display (or a portion thereof) has become visible.
338 display.source (ALLEGRO_DISPLAY *) : The display which was exposed.
340 display.x (int)
342 display.y (int)
345 The top-left corner of the rectangle which was exposed.
347 display.width (int)
349 display.height (int)
352 The width and height of the rectangle which was exposed.
353 Note: The display needs to be created with ALLEGRO_GENER‐
355 ATE_EXPOSE_EVENTS flag for these events to be generated.
356 ALLEGRO_EVENT_DISPLAY_RESIZE
358 The window has been resized.
359 display.source (ALLEGRO_DISPLAY *) : The display which was resized.
361 display.x (int)
363 display.y (int)
366 The position of the top-level corner of the display.
367 display.width (int)
369 The new width of the display.
370 display.height (int)
372 The new height of the display.
373 You should normally respond to these events by calling al_acknowl‐
375 edge_resize(3). Note that further resize events may be generated by
376 the time you process the event, so these fields may hold outdated
377 information.
378 ALLEGRO_EVENT_DISPLAY_CLOSE
380 The close button of the window has been pressed.
381 display.source (ALLEGRO_DISPLAY *) : The display which was closed.
383 ALLEGRO_EVENT_DISPLAY_LOST
385 When using Direct3D, displays can enter a "lost" state. In that state,
386 drawing calls are ignored, and upon entering the state, bitmap's pixel
387 data can become undefined. Allegro does its best to preserve the cor‐
388 rect contents of bitmaps (see the ALLEGRO_NO_PRESERVE_TEXTURE flag) and
389 restore them when the device is "found" (see ALLEGRO_EVENT_DIS‐
390 PLAY_FOUND(3)). However, this is not 100% fool proof (see discussion
391 in al_create_bitmap(3)'s documentation).
392 Note: This event merely means that the display was lost, that
394 is, DirectX suddenly lost the contents of all video bitmaps. In
395 particular, you can keep calling drawing functions -- they just
396 most likely won't do anything. If Allegro's restoration of the
397 bitmaps works well for you then no further action is required
398 when you receive this event.
399 display.source (ALLEGRO_DISPLAY *) : The display which was lost.
401 ALLEGRO_EVENT_DISPLAY_FOUND
403 Generated when a lost device is restored to operating state. See ALLE‐
404 GRO_EVENT_DISPLAY_LOST(3).
405 display.source (ALLEGRO_DISPLAY *) : The display which was found.
407 ALLEGRO_EVENT_DISPLAY_SWITCH_OUT
409 The window is no longer active, that is the user might have clicked
410 into another window or "tabbed" away.
411 display.source (ALLEGRO_DISPLAY *) : The display which was switched out
413 of.
414 ALLEGRO_EVENT_DISPLAY_SWITCH_IN
416 The window is the active one again.
417 display.source (ALLEGRO_DISPLAY *) : The display which was switched
419 into.
420 ALLEGRO_EVENT_DISPLAY_ORIENTATION
422 Generated when the rotation or orientation of a display changes.
423 display.source (ALLEGRO_DISPLAY *) : The display which generated the
425 event.
426 event.display.orientation
428 Contains one of the following values:
429 · ALLEGRO_DISPLAY_ORIENTATION_0_DEGREES
431 · ALLEGRO_DISPLAY_ORIENTATION_90_DEGREES
433 · ALLEGRO_DISPLAY_ORIENTATION_180_DEGREES
435 · ALLEGRO_DISPLAY_ORIENTATION_270_DEGREES
437 · ALLEGRO_DISPLAY_ORIENTATION_FACE_UP
439 · ALLEGRO_DISPLAY_ORIENTATION_FACE_DOWN
441 ALLEGRO_EVENT_DISPLAY_HALT_DRAWING
443 When a display receives this event it should stop doing any drawing and
444 then call al_acknowledge_drawing_halt(3) immediately.
445 This is currently only relevant for Android and iOS. It will be sent
447 when the application is switched to background mode, in addition to
448 ALLEGRO_EVENT_DISPLAY_SWITCH_OUT(3). The latter may also be sent in
449 situations where the application is not active but still should con‐
450 tinue drawing, for example when a popup is displayed in front of it.
451 Note: This event means that the next time you call a drawing
453 function, your program will crash. So you must stop drawing and
454 you must immediately reply with al_acknowledge_drawing_halt(3).
455 Allegro sends this event because it cannot handle this automati‐
456 cally. Your program might be doing the drawing in a different
457 thread from the event handling, in which case the drawing thread
458 needs to be signaled to stop drawing before acknowledging this
459 event.
460 Note: Mobile devices usually never quit an application, so to
462 prevent the battery from draining while your application is
463 halted it can be a good idea to call al_stop_timer(3) on all
464 your timers, otherwise they will keep generating events. If you
465 are using audio, you can also stop all audio voices (or pass
466 NULL to al_set_default_voice(3) if you use the default mixer),
467 otherwise Allegro will keep streaming silence to the voice even
468 if the stream or mixer are stopped or detached.
469
471 5.1.0
472
474 ALLEGRO_EVENT_DISPLAY_RESUME_DRAWING(3)
475 ALLEGRO_EVENT_DISPLAY_RESUME_DRAWING
477 When a display receives this event, it may resume drawing again, and it
478 must call al_acknowledge_drawing_resume(3) immediately.
479 This is currently only relevant for Android and iOS. The event will be
481 sent when an application returns from background mode and is allowed to
482 draw to the display again, in addition to ALLEGRO_EVENT_DIS‐
483 PLAY_SWITCH_IN(3). The latter event may also be sent in a situation
484 where the application is already active, for example when a popup in
485 front of it closes.
486 Note: Unlike ALLEGRO_EVENT_DISPLAY_FOUND(3) it is not necessary
488 to reload any bitmaps when you receive this event.
489
491 5.1.0
492
494 ALLEGRO_EVENT_DISPLAY_HALT_DRAWING(3)
495 ALLEGRO_EVENT_DISPLAY_CONNECTED
497 This event is sent when a physical display is connected to the device
498 Allegro runs on. Currently, on most platforms, Allegro supports only a
499 single physical display. However, on iOS, a secondary physical display
500 is suported.
501 display.source (ALLEGRO_DISPLAY *) : The display which was connected.
503
505 5.1.1
506 ALLEGRO_EVENT_DISPLAY_DISCONNECTED
508 This event is sent when a physical display is disconnected from the
509 device Allegro runs on. Currently, on most platforms, Allegro supports
510 only a single physical display. However, on iOS, a secondary physical
511 display is suported.
512 display.source (ALLEGRO_DISPLAY *) : The display which was discon‐
514 nected.
515Allegro reference manual ALLEGRO_EVENT(3)