1ALLEGRO_EVENT(3) Library Functions Manual ALLEGRO_EVENT(3)
2
3
4
6 ALLEGRO_EVENT
7
9 #include <allegro5/allegro.h>
10
11 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
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 press 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-
103 repeated.
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 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
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.display (ALLEGRO_DISPLAY *)
178 The display which had mouse focus.
179
180 Note: Calling al_set_mouse_xy(3) also will result in a change of
181 axis values, but such a change is reported with ALLE‐
182 GRO_EVENT_MOUSE_WARPED events instead.
183
184 Note: currently mouse.display may be NULL if an event is gener‐
185 ated in response to al_set_mouse_axis(3).
186
187 ALLEGRO_EVENT_MOUSE_BUTTON_DOWN
188 A mouse button was pressed.
189
190 mouse.x (int)
191 x-coordinate
192
193 mouse.y (int)
194 y-coordinate
195
196 mouse.z (int)
197 z-coordinate
198
199 mouse.w (int)
200 w-coordinate
201
202 mouse.button (unsigned)
203 The mouse button which was pressed, numbering from 1.
204
205 mouse.display (ALLEGRO_DISPLAY *)
206 The display which had mouse focus.
207
208 ALLEGRO_EVENT_MOUSE_BUTTON_UP
209 A mouse button was released.
210
211 mouse.x (int)
212 x-coordinate
213
214 mouse.y (int)
215 y-coordinate
216
217 mouse.z (int)
218 z-coordinate
219
220 mouse.w (int)
221 w-coordinate
222
223 mouse.button (unsigned)
224 The mouse button which was released, numbering from 1.
225
226 mouse.display (ALLEGRO_DISPLAY *)
227 The display which had mouse focus.
228
229 ALLEGRO_EVENT_MOUSE_WARPED
230 al_set_mouse_xy(3) was called to move the mouse. This event is identi‐
231 cal to ALLEGRO_EVENT_MOUSE_AXES otherwise.
232
233 ALLEGRO_EVENT_MOUSE_ENTER_DISPLAY
234 The mouse cursor entered a window opened by the program.
235
236 mouse.x (int)
237 x-coordinate
238
239 mouse.y (int)
240 y-coordinate
241
242 mouse.z (int)
243 z-coordinate
244
245 mouse.w (int)
246 w-coordinate
247
248 mouse.display (ALLEGRO_DISPLAY *)
249 The display which had mouse focus.
250
251 ALLEGRO_EVENT_MOUSE_LEAVE_DISPLAY
252 The mouse cursor leave the boundaries of a window opened by the pro‐
253 gram.
254
255 mouse.x (int)
256 x-coordinate
257
258 mouse.y (int)
259 y-coordinate
260
261 mouse.z (int)
262 z-coordinate
263
264 mouse.w (int)
265 w-coordinate
266
267 mouse.display (ALLEGRO_DISPLAY *)
268 The display which had mouse focus.
269
270 ALLEGRO_EVENT_TIMER
271 A timer counter incremented.
272
273 timer.source (ALLEGRO_TIMER *)
274 The timer which generated the event.
275
276 timer.count (int64_t)
277 The timer count value.
278
279 ALLEGRO_EVENT_DISPLAY_EXPOSE
280 The display (or a portion thereof) has become visible.
281
282 display.source (ALLEGRO_DISPLAY *)
283 The display which was exposed.
284
285 display.x (int)
286
287
288 display.y (int)
289
290 The top-left corner of the display which was exposed.
291
292 display.width (int)
293
294
295 display.height (int)
296 The width and height of the rectangle which was exposed.
297
298 Note: The display needs to be created with ALLEGRO_GENER‐
299 ATE_EXPOSE_EVENTS flag for these events to be generated.
300
301 ALLEGRO_EVENT_DISPLAY_RESIZE
302 The window has been resized.
303
304 display.source (ALLEGRO_DISPLAY *)
305 The display which was resized.
306
307 display.x (int)
308
309
310 display.y (int)
311 The position of the top-level corner of the display.
312
313 display.width (int)
314 The new width of the display.
315
316 display.height (int)
317 The new height of the display.
318
319 Note that further resize events may be generated by the time you
320 process the event, so these fields may hold outdated information.
321
322 ALLEGRO_EVENT_DISPLAY_CLOSE
323 The close button of the window has been pressed.
324
325 display.source (ALLEGRO_DISPLAY *)
326 The display which was closed.
327
328 ALLEGRO_EVENT_DISPLAY_LOST
329 When using Direct3D, displays can enter a “lost” state. In that state,
330 drawing calls are ignored, and upon entering the state, bitmap's pixel
331 data can become undefined. Allegro does its best to preserve the cor‐
332 rect contents of bitmaps (see ALLEGRO_NO_PRESERVE_TEXTURE) and restore
333 them when the device is “found” (see ALLEGRO_EVENT_DISPLAY_FOUND).
334 However, this is not 100% fool proof.
335
336 To ensure that all bitmap contents are restored accurately, one must
337 take additional steps. The best procedure to follow if bitmap con‐
338 stancy is important to you is as follows: first, always have the ALLE‐
339 GRO_NO_PRESERVE_TEXTURE flag set to true when creating bitmaps, as it
340 incurs pointless overhead when using this method. Second, create a
341 mechanism in your game for easily reloading all of your bitmaps — for
342 example, wrap them in a class or data structure and have a “bitmap man‐
343 ager” that can reload them back to the desired state. Then, when you
344 receive an ALLEGRO_EVENT_DISPLAY_FOUND event, tell the bitmap manager
345 (or whatever your mechanism is) to restore your bitmaps.
346
347 display.source (ALLEGRO_DISPLAY *)
348 The display which was lost.
349
350 ALLEGRO_EVENT_DISPLAY_FOUND
351 Generated when a lost device is restored to operating state. See ALLE‐
352 GRO_EVENT_DISPLAY_LOST.
353
354 display.source (ALLEGRO_DISPLAY *)
355 The display which was found.
356
357 ALLEGRO_EVENT_DISPLAY_SWITCH_OUT
358 The window is no longer active, that is the user might have clicked
359 into another window or “tabbed” away.
360
361 display.source (ALLEGRO_DISPLAY *)
362 The display which was switched out of.
363
364 ALLEGRO_EVENT_DISPLAY_SWITCH_IN
365 The window is the active one again.
366
367 display.source (ALLEGRO_DISPLAY *)
368 The display which was switched into.
369
370 ALLEGRO_EVENT_DISPLAY_ORIENTATION
371 Generated when the rotation or orientation of a display changes.
372
373 display.source (ALLEGRO_DISPLAY *)
374 The display which generated the event.
375
376 event.display.orientation
377 Contains one of the following values:
378
379 · ALLEGRO_DISPLAY_ORIENTATION_0_DEGREES
380
381 · ALLEGRO_DISPLAY_ORIENTATION_90_DEGREES
382
383 · ALLEGRO_DISPLAY_ORIENTATION_180_DEGREES
384
385 · ALLEGRO_DISPLAY_ORIENTATION_270_DEGREES
386
387 · ALLEGRO_DISPLAY_ORIENTATION_FACE_UP
388
389 · ALLEGRO_DISPLAY_ORIENTATION_FACE_DOWN
390
392 ALLEGRO_EVENT_SOURCE(3), ALLEGRO_EVENT_TYPE(3), ALLEGRO_USER_EVENT(3)
393
394
395
396Allegro reference manual ALLEGRO_EVENT(3)