1ALLEGRO_EVENT(3) Library Functions Manual ALLEGRO_EVENT(3)
2
6 ALLEGRO_EVENT
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 press 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-
103 repeated.
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.display (ALLEGRO_DISPLAY *)
178 The display which had mouse focus.
179 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 Note: currently mouse.display may be NULL if an event is gener‐
185 ated in response to al_set_mouse_axis(3).
186 ALLEGRO_EVENT_MOUSE_BUTTON_DOWN
188 A mouse button was pressed.
189 mouse.x (int)
191 x-coordinate
192 mouse.y (int)
194 y-coordinate
195 mouse.z (int)
197 z-coordinate
198 mouse.w (int)
200 w-coordinate
201 mouse.button (unsigned)
203 The mouse button which was pressed, numbering from 1.
204 mouse.display (ALLEGRO_DISPLAY *)
206 The display which had mouse focus.
207 ALLEGRO_EVENT_MOUSE_BUTTON_UP
209 A mouse button was released.
210 mouse.x (int)
212 x-coordinate
213 mouse.y (int)
215 y-coordinate
216 mouse.z (int)
218 z-coordinate
219 mouse.w (int)
221 w-coordinate
222 mouse.button (unsigned)
224 The mouse button which was released, numbering from 1.
225 mouse.display (ALLEGRO_DISPLAY *)
227 The display which had mouse focus.
228 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 ALLEGRO_EVENT_MOUSE_ENTER_DISPLAY
234 The mouse cursor entered a window opened by the program.
235 mouse.x (int)
237 x-coordinate
238 mouse.y (int)
240 y-coordinate
241 mouse.z (int)
243 z-coordinate
244 mouse.w (int)
246 w-coordinate
247 mouse.display (ALLEGRO_DISPLAY *)
249 The display which had mouse focus.
250 ALLEGRO_EVENT_MOUSE_LEAVE_DISPLAY
252 The mouse cursor leave the boundaries of a window opened by the pro‐
253 gram.
254 mouse.x (int)
256 x-coordinate
257 mouse.y (int)
259 y-coordinate
260 mouse.z (int)
262 z-coordinate
263 mouse.w (int)
265 w-coordinate
266 mouse.display (ALLEGRO_DISPLAY *)
268 The display which had mouse focus.
269 ALLEGRO_EVENT_TIMER
271 A timer counter incremented.
272 timer.source (ALLEGRO_TIMER *)
274 The timer which generated the event.
275 timer.count (int64_t)
277 The timer count value.
278 ALLEGRO_EVENT_DISPLAY_EXPOSE
280 The display (or a portion thereof) has become visible.
281 display.source (ALLEGRO_DISPLAY *)
283 The display which was exposed.
284 display.x (int)
286 display.y (int)
289 The top-left corner of the display which was exposed.
291 display.width (int)
293 display.height (int)
296 The width and height of the rectangle which was exposed.
297 Note: The display needs to be created with ALLEGRO_GENER‐
299 ATE_EXPOSE_EVENTS flag for these events to be generated.
300 ALLEGRO_EVENT_DISPLAY_RESIZE
302 The window has been resized.
303 display.source (ALLEGRO_DISPLAY *)
305 The display which was resized.
306 display.x (int)
308 display.y (int)
311 The position of the top-level corner of the display.
312 display.width (int)
314 The new width of the display.
315 display.height (int)
317 The new height of the display.
318 Note that further resize events may be generated by the time you
320 process the event, so these fields may hold outdated information.
321 ALLEGRO_EVENT_DISPLAY_CLOSE
323 The close button of the window has been pressed.
324 display.source (ALLEGRO_DISPLAY *)
326 The display which was closed.
327 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 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 display.source (ALLEGRO_DISPLAY *)
348 The display which was lost.
349 ALLEGRO_EVENT_DISPLAY_FOUND
351 Generated when a lost device is restored to operating state. See ALLE‐
352 GRO_EVENT_DISPLAY_LOST.
353 display.source (ALLEGRO_DISPLAY *)
355 The display which was found.
356 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 display.source (ALLEGRO_DISPLAY *)
362 The display which was switched out of.
363 ALLEGRO_EVENT_DISPLAY_SWITCH_IN
365 The window is the active one again.
366 display.source (ALLEGRO_DISPLAY *)
368 The display which was switched into.
369 ALLEGRO_EVENT_DISPLAY_ORIENTATION
371 Generated when the rotation or orientation of a display changes.
372 display.source (ALLEGRO_DISPLAY *)
374 The display which generated the event.
375 event.display.orientation
377 Contains one of the following values:
378 · ALLEGRO_DISPLAY_ORIENTATION_0_DEGREES
380 · ALLEGRO_DISPLAY_ORIENTATION_90_DEGREES
382 · ALLEGRO_DISPLAY_ORIENTATION_180_DEGREES
384 · ALLEGRO_DISPLAY_ORIENTATION_270_DEGREES
386 · ALLEGRO_DISPLAY_ORIENTATION_FACE_UP
388 · ALLEGRO_DISPLAY_ORIENTATION_FACE_DOWN
390
392 ALLEGRO_EVENT_SOURCE(3), ALLEGRO_EVENT_TYPE(3), ALLEGRO_USER_EVENT(3)
393Allegro reference manual ALLEGRO_EVENT(3)