table of contents
other versions
- jessie 2:5.0.10-3
ALLEGRO_EVENT(3alleg5) Allegro reference manual() | ALLEGRO_EVENT(3alleg5) Allegro reference manual() |
NAME¶
ALLEGRO_EVENT - Allegro 5 APISYNOPSIS¶
-
#include <allegro5/allegro.h> typedef union ALLEGRO_EVENT ALLEGRO_EVENT;
DESCRIPTION¶
An ALLEGRO_EVENT is a union of all builtin event structures, i.e. it is an object large enough to hold the data of any event type. All events have the following fields in common:- type (ALLEGRO_EVENT_TYPE)
- Indicates the type of event.
- any.timestamp (double)
- When the event was generated.
ALLEGRO_EVENT_JOYSTICK_AXIS¶
A joystick axis value changed. joystick.id (ALLEGRO_JOYSTICK *) : The joystick which generated the event. This is not the same as the event source joystick.source.- joystick.stick (int)
- The stick number, counting from zero. Axes on a joystick are grouped into "sticks".
- joystick.axis (int)
- The axis number on the stick, counting from zero.
- joystick.pos (float)
- The axis position, from -1.0 to +1.0.
ALLEGRO_EVENT_JOYSTICK_BUTTON_DOWN¶
A joystick button was pressed. joystick.id (ALLEGRO_JOYSTICK *) : The joystick which generated the event.- joystick.button (int)
- The button which was pressed, counting from zero.
ALLEGRO_EVENT_JOYSTICK_BUTTON_UP¶
A joystick button was released. joystick.id (ALLEGRO_JOYSTICK *) : The joystick which generated the event.- joystick.button (int)
- The button which was released, counting from zero.
ALLEGRO_EVENT_JOYSTICK_CONFIGURATION¶
A joystick was plugged in or unplugged. See al_reconfigure_joysticks(3alleg5) for details.ALLEGRO_EVENT_KEY_DOWN¶
A keyboard key was pressed.- keyboard.keycode (int)
- The code corresponding to the physical key which was pressed. See the "Key codes" section for the list of ALLEGRO_KEY_* constants.
Note: this event is about the physical keys being pressed on the
keyboard. Look for ALLEGRO_EVENT_KEY_CHAR events for character input.
ALLEGRO_EVENT_KEY_UP¶
A keyboard key was released.- keyboard.keycode (int)
- The code corresponding to the physical key which was released. See the "Key codes" section for the list of ALLEGRO_KEY_* constants.
ALLEGRO_EVENT_KEY_CHAR¶
A character was typed on the keyboard, or a character was auto-repeated.- keyboard.keycode (int)
- The code corresponding to the physical key which was last pressed. See the "Key codes" section for the list of ALLEGRO_KEY_* constants.
- keyboard.unichar (int)
- A Unicode code point (character). This may be zero or negative if the event was generated for a non-visible "character", such as an arrow or Function key. In that case you can act upon the keycode field.
Some special keys will set the unichar field to their standard ASCII values:
Tab=9, Return=13, Escape=27. In addition if you press the Control key together
with A to Z the unichar field will have the values 1 to 26. For example Ctrl-A
will set unichar to 1 and Ctrl-H will set it to 8.
As of Allegro 5.0.2 there are some inconsistencies in the treatment of Backspace
(8 or 127) and Delete (127 or 0) keys on different platforms. These can be
worked around by checking the keycode field.
- keyboard.modifiers (unsigned)
- This is a bitfield of the modifier keys which were pressed when the event occurred. See "Keyboard modifier flags" for the constants.
- keyboard.repeat (bool)
- Indicates if this is a repeated character.
Note: in many input methods, characters are not entered
one-for-one with physical key presses. Multiple key presses can combine to
generate a single character, e.g. apostrophe + e may produce 'é'. Fewer
key presses can also generate more characters, e.g. macro sequences expanding
to common phrases.
ALLEGRO_EVENT_MOUSE_AXES¶
One or more mouse axis values changed.- mouse.x (int)
- x-coordinate
- mouse.y (int)
- y-coordinate
- mouse.z (int)
- z-coordinate. This usually means the vertical axis of a mouse wheel, where up is positive and down is negative.
- mouse.w (int)
- w-coordinate. This usually means the horizontal axis of a mouse wheel.
- mouse.dx (int)
- Change in the x-coordinate value since the previous ALLEGRO_EVENT_MOUSE_AXES event.
- mouse.dy (int)
- Change in the y-coordinate value since the previous ALLEGRO_EVENT_MOUSE_AXES event.
- mouse.dz (int)
- Change in the z-coordinate value since the previous ALLEGRO_EVENT_MOUSE_AXES event.
- mouse.dw (int)
- Change in the w-coordinate value since the previous ALLEGRO_EVENT_MOUSE_AXES event.
Note: Calling al_set_mouse_xy(3alleg5) also will result in a change of
axis values, but such a change is reported with ALLEGRO_EVENT_MOUSE_WARPED
events instead.
Note: currently mouse.display may be NULL if an event is generated in
response to al_set_mouse_axis(3alleg5).
ALLEGRO_EVENT_MOUSE_BUTTON_DOWN¶
A mouse button was pressed.- mouse.x (int)
- x-coordinate
- mouse.y (int)
- y-coordinate
- mouse.z (int)
- z-coordinate
- mouse.w (int)
- w-coordinate
- mouse.button (unsigned)
- The mouse button which was pressed, numbering from 1.
ALLEGRO_EVENT_MOUSE_BUTTON_UP¶
A mouse button was released.- mouse.x (int)
- x-coordinate
- mouse.y (int)
- y-coordinate
- mouse.z (int)
- z-coordinate
- mouse.w (int)
- w-coordinate
- mouse.button (unsigned)
- The mouse button which was released, numbering from 1.
ALLEGRO_EVENT_MOUSE_WARPED¶
al_set_mouse_xy(3alleg5) was called to move the mouse. This event is identical to ALLEGRO_EVENT_MOUSE_AXES otherwise.ALLEGRO_EVENT_MOUSE_ENTER_DISPLAY¶
The mouse cursor entered a window opened by the program.- mouse.x (int)
- x-coordinate
- mouse.y (int)
- y-coordinate
- mouse.z (int)
- z-coordinate
- mouse.w (int)
- w-coordinate
ALLEGRO_EVENT_MOUSE_LEAVE_DISPLAY¶
The mouse cursor leave the boundaries of a window opened by the program.- mouse.x (int)
- x-coordinate
- mouse.y (int)
- y-coordinate
- mouse.z (int)
- z-coordinate
- mouse.w (int)
- w-coordinate
ALLEGRO_EVENT_TIMER¶
A timer counter incremented. timer.source (ALLEGRO_TIMER *) : The timer which generated the event.- timer.count (int64_t)
- The timer count value.
ALLEGRO_EVENT_DISPLAY_EXPOSE¶
The display (or a portion thereof) has become visible. display.source (ALLEGRO_DISPLAY *) : The display which was exposed.- display.x (int)
- display.y (int)
- display.width (int)
- display.height (int)
- The width and height of the rectangle which was exposed.
Note: The display needs to be created with ALLEGRO_GENERATE_EXPOSE_EVENTS
flag for these events to be generated.
ALLEGRO_EVENT_DISPLAY_RESIZE¶
The window has been resized. display.source (ALLEGRO_DISPLAY *) : The display which was resized.- display.x (int)
- display.y (int)
- The position of the top-level corner of the display.
- display.width (int)
- The new width of the display.
- display.height (int)
- The new height of the display.
ALLEGRO_EVENT_DISPLAY_CLOSE¶
The close button of the window has been pressed. display.source (ALLEGRO_DISPLAY *) : The display which was closed.ALLEGRO_EVENT_DISPLAY_LOST¶
When using Direct3D, displays can enter a "lost" state. In that state, drawing calls are ignored, and upon entering the state, bitmap's pixel data can become undefined. Allegro does its best to preserve the correct contents of bitmaps (see ALLEGRO_NO_PRESERVE_TEXTURE) and restore them when the device is "found" (see ALLEGRO_EVENT_DISPLAY_FOUND). However, this is not 100% fool proof. To ensure that all bitmap contents are restored accurately, one must take additional steps. The best procedure to follow if bitmap constancy is important to you is as follows: first, always have the ALLEGRO_NO_PRESERVE_TEXTURE flag set to true when creating bitmaps, as it incurs pointless overhead when using this method. Second, create a mechanism in your game for easily reloading all of your bitmaps -- for example, wrap them in a class or data structure and have a "bitmap manager" that can reload them back to the desired state. Then, when you receive an ALLEGRO_EVENT_DISPLAY_FOUND event, tell the bitmap manager (or whatever your mechanism is) to restore your bitmaps. display.source (ALLEGRO_DISPLAY *) : The display which was lost.ALLEGRO_EVENT_DISPLAY_FOUND¶
Generated when a lost device is restored to operating state. See ALLEGRO_EVENT_DISPLAY_LOST. display.source (ALLEGRO_DISPLAY *) : The display which was found.ALLEGRO_EVENT_DISPLAY_SWITCH_OUT¶
The window is no longer active, that is the user might have clicked into another window or "tabbed" away. display.source (ALLEGRO_DISPLAY *) : The display which was switched out of.ALLEGRO_EVENT_DISPLAY_SWITCH_IN¶
The window is the active one again. display.source (ALLEGRO_DISPLAY *) : The display which was switched into.ALLEGRO_EVENT_DISPLAY_ORIENTATION¶
Generated when the rotation or orientation of a display changes. display.source (ALLEGRO_DISPLAY *) : The display which generated the event.- event.display.orientation
- Contains one of the following values:
- •
- ALLEGRO_DISPLAY_ORIENTATION_0_DEGREES
- •
- ALLEGRO_DISPLAY_ORIENTATION_90_DEGREES
- •
- ALLEGRO_DISPLAY_ORIENTATION_180_DEGREES
- •
- ALLEGRO_DISPLAY_ORIENTATION_270_DEGREES
- •
- ALLEGRO_DISPLAY_ORIENTATION_FACE_UP
- •
- ALLEGRO_DISPLAY_ORIENTATION_FACE_DOWN