Events

Overview of the event system

An “event” is a thing that happens at some instant in time.  The fact that this event occurred is captured in a piece of data, known also as an “event”.

Event can be created by some certain types of objects, collectively known as “event sources”, and then placed into “event queues”, in chronological order.  The user can take events out of event queues, also in chronological order, and examine them.

event source 1 \
\
event source 2 ---->--- event queue ----->---- user
/
event source 3 /

Events are The user takes events
generated and out of the queue,
placed into examines them,
event queues. and acts on them.
Summary
Overview of the event system
Each event is of one of the following types
An ALLEGRO_EVENT is a union of all builtin event structures, i.e.
An event source is any object which can generate events.

Enumerations

ALLEGRO_EVENT_TYPE

Each event is of one of the following types

ALLEGRO_EVENT_JOYSTICK_AXISa joystick axis value changed.  Fields are: joystick.stick, joystick.axis, joystick.pos (-1.0 to 1.0).
ALLEGRO_EVENT_JOYSTICK_BUTTON_DOWNa joystick button was pressed.  Fields are: joystick.button.
ALLEGRO_EVENT_JOYSTICK_BUTTON_UPa joystick button was released.  Fields are: joystick.button.
ALLEGRO_EVENT_KEY_DOWNa keyboard key was pressed.  Fields: keyboard.keycode, keyboard.unichar, keyboard.modifiers.
ALLEGRO_EVENT_KEY_REPEATa typed character auto-repeated.  Fields: keyboard.keycode (ALLEGRO_KEY_*), keyboard.unichar (unicode character), keyboard.modifiers (ALLEGRO_KEYMOD_*).
ALLEGRO_EVENT_KEY_UPa keyboard key was released.  Fields: keyboard.keycode.
ALLEGRO_EVENT_MOUSE_AXESone or more mouse axis values changed.  Fields: mouse.x, mouse.y, mouse.z, mouse.dx, mouse.dy, mouse.dz.
ALLEGRO_EVENT_MOUSE_BUTTON_DOWNa mouse button was pressed.  Fields: mouse.x, mouse.y, mouse.z, mouse.button.
ALLEGRO_EVENT_MOUSE_BUTTON_UPa mouse button was released.  Fields: mouse.x, mouse.y, mouse.z, mouse.button.
ALLEGRO_EVENT_MOUSE_ENTER_DISPLAYthe mouse cursor entered a window opened by the program.  Fields: mouse.x, mouse.y, mouse.z.
ALLEGRO_EVENT_MOUSE_LEAVE_DISPLAYthe mouse cursor leave the boundaries of a window opened by the program.  Fields: mouse.x, mouse.y, mouse.z.
ALLEGRO_EVENT_TIMERa timer counter incremented.  Fields: timer.count.
ALLEGRO_EVENT_DISPLAY_EXPOSEThe display (or a portion thereof) has become visible.  Fields: display.x, display.y, display.width, display.height
ALLEGRO_EVENT_DISPLAY_RESIZEThe window has been resized.  Fields: display.x, display.y, display.width, display.height
ALLEGRO_EVENT_DISPLAY_CLOSEThe close button of the window has been pressed.
ALLEGRO_EVENT_DISPLAY_LOSTDisplays can be lost with some drivers (just Direct3D?).  This means that rendering is impossible.  The device will be restored as soon as it is possible.  The program should be able to ignore this event and continue rendering however it will have no effect.
ALLEGRO_EVENT_DISPLAY_FOUNDGenerated when a lost device is regained.  Drawing will no longer be a no-op.

Types

ALLEGRO_EVENT

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:

ALLEGRO_EVENT_TYPE      type;
ALLEGRO_EVENT_SOURCE * any.source;
double any.timestamp;

By examining the type field you can then access type-specific fields.  The any.source field tells you which event source generated that particular event.  The any.timestamp field tells you when the event was generated.  The time is referenced to the same starting point as al_current_time().

ALLEGRO_EVENT_SOURCE

An event source is any object which can generate events.  Event sources are usually referred to by distinct types, e.g.  ALLEGRO_KEYBOARD*, but can be casted to ALLEGRO_EVENT_SOURCE* when used in contexts that accept generic event sources.