.TH "ALLEGRO_EVENT" "3" "" "Allegro reference manual" ""
.SH NAME
.PP
ALLEGRO_EVENT \- Allegro 5 API
.SH SYNOPSIS
.IP
.nf
\f[C]
#include\ <allegro5/allegro.h>

typedef\ union\ ALLEGRO_EVENT\ ALLEGRO_EVENT;
\f[]
.fi
.SH DESCRIPTION
.PP
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:
.TP
.B type (ALLEGRO_EVENT_TYPE)
Indicates the type of event.
.RS
.RE
.PP
any.source (ALLEGRO_EVENT_SOURCE *) : The event source which generated
the event.
.TP
.B any.timestamp (double)
When the event was generated.
.RS
.RE
.PP
By examining the \f[C]type\f[] field you can then access type\-specific
fields.
The \f[C]any.source\f[] field tells you which event source generated
that particular event.
The \f[C]any.timestamp\f[] field tells you when the event was generated.
The time is referenced to the same starting point as al_get_time(3).
.PP
Each event is of one of the following types, with the usable fields
given.
.SS ALLEGRO_EVENT_JOYSTICK_AXIS
.PP
A joystick axis value changed.
.PP
joystick.id (ALLEGRO_JOYSTICK *) : The joystick which generated the
event.
This is not the same as the event source \f[C]joystick.source\f[].
.TP
.B joystick.stick (int)
The stick number, counting from zero.
Axes on a joystick are grouped into "sticks".
.RS
.RE
.TP
.B joystick.axis (int)
The axis number on the stick, counting from zero.
.RS
.RE
.TP
.B joystick.pos (float)
The axis position, from \-1.0 to +1.0.
.RS
.RE
.SS ALLEGRO_EVENT_JOYSTICK_BUTTON_DOWN
.PP
A joystick button was pressed.
.PP
joystick.id (ALLEGRO_JOYSTICK *) : The joystick which generated the
event.
.TP
.B joystick.button (int)
The button which was pressed, counting from zero.
.RS
.RE
.SS ALLEGRO_EVENT_JOYSTICK_BUTTON_UP
.PP
A joystick button was released.
.PP
joystick.id (ALLEGRO_JOYSTICK *) : The joystick which generated the
event.
.TP
.B joystick.button (int)
The button which was released, counting from zero.
.RS
.RE
.SS ALLEGRO_EVENT_JOYSTICK_CONFIGURATION
.PP
A joystick was plugged in or unplugged.
See al_reconfigure_joysticks(3) for details.
.SS ALLEGRO_EVENT_KEY_DOWN
.PP
A keyboard key was pressed.
.TP
.B 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.
.RS
.RE
.PP
keyboard.display (ALLEGRO_DISPLAY *) : The display which had keyboard
focus when the event occurred.
.RS
.PP
\f[I]Note:\f[] this event is about the physical keys being pressed on
the keyboard.
Look for ALLEGRO_EVENT_KEY_CHAR events for character input.
.RE
.SS ALLEGRO_EVENT_KEY_UP
.PP
A keyboard key was released.
.TP
.B 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.
.RS
.RE
.PP
keyboard.display (ALLEGRO_DISPLAY *) : The display which had keyboard
focus when the event occurred.
.SS ALLEGRO_EVENT_KEY_CHAR
.PP
A character was typed on the keyboard, or a character was
auto\-repeated.
.TP
.B 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.
.RS
.RE
.TP
.B keyboard.unichar (int)
A Unicode code point (character).
This \f[I]may\f[] 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 \f[C]keycode\f[] field.
.RS
.PP
Some special keys will set the \f[C]unichar\f[] 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
\f[C]unichar\f[] field will have the values 1 to 26.
For example Ctrl\-A will set \f[C]unichar\f[] to 1 and Ctrl\-H will set
it to 8.
.PP
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 \f[C]keycode\f[] field.
.RE
.TP
.B 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.
.RS
.RE
.TP
.B keyboard.repeat (bool)
Indicates if this is a repeated character.
.RS
.RE
.PP
keyboard.display (ALLEGRO_DISPLAY *) : The display which had keyboard
focus when the event occurred.
.RS
.PP
\f[I]Note\f[]: in many input methods, characters are \f[I]not\f[]
entered one\-for\-one with physical key presses.
Multiple key presses can combine to generate a single character, e.g.
apostrophe + e may produce \[aq]é\[aq].
Fewer key presses can also generate more characters, e.g.
macro sequences expanding to common phrases.
.RE
.SS ALLEGRO_EVENT_MOUSE_AXES
.PP
One or more mouse axis values changed.
.TP
.B mouse.x (int)
x\-coordinate
.RS
.RE
.TP
.B mouse.y (int)
y\-coordinate
.RS
.RE
.TP
.B mouse.z (int)
z\-coordinate.
This usually means the vertical axis of a mouse wheel, where up is
positive and down is negative.
.RS
.RE
.TP
.B mouse.w (int)
w\-coordinate.
This usually means the horizontal axis of a mouse wheel.
.RS
.RE
.TP
.B mouse.dx (int)
Change in the x\-coordinate value since the previous
ALLEGRO_EVENT_MOUSE_AXES event.
.RS
.RE
.TP
.B mouse.dy (int)
Change in the y\-coordinate value since the previous
ALLEGRO_EVENT_MOUSE_AXES event.
.RS
.RE
.TP
.B mouse.dz (int)
Change in the z\-coordinate value since the previous
ALLEGRO_EVENT_MOUSE_AXES event.
.RS
.RE
.TP
.B mouse.dw (int)
Change in the w\-coordinate value since the previous
ALLEGRO_EVENT_MOUSE_AXES event.
.RS
.RE
.TP
.B mouse.pressure (float)
Pressure, ranging from \f[C]0.0\f[] to \f[C]1.0\f[].
.RS
.RE
.PP
mouse.display (ALLEGRO_DISPLAY *) : The display which had mouse focus.
.RS
.PP
\f[I]Note:\f[] Calling al_set_mouse_xy(3) also will result in a change
of axis values, but such a change is reported with
ALLEGRO_EVENT_MOUSE_WARPED(3) events instead which are identical except
for their type.
.RE
.RS
.PP
\f[I]Note:\f[] currently mouse.display may be NULL if an event is
generated in response to al_set_mouse_axis(3).
.RE
.SS ALLEGRO_EVENT_MOUSE_BUTTON_DOWN
.PP
A mouse button was pressed.
.TP
.B mouse.x (int)
x\-coordinate
.RS
.RE
.TP
.B mouse.y (int)
y\-coordinate
.RS
.RE
.TP
.B mouse.z (int)
z\-coordinate
.RS
.RE
.TP
.B mouse.w (int)
w\-coordinate
.RS
.RE
.TP
.B mouse.button (unsigned)
The mouse button which was pressed, numbering from 1.
.RS
.RE
.TP
.B mouse.pressure (float)
Pressure, ranging from \f[C]0.0\f[] to \f[C]1.0\f[].
.RS
.RE
.PP
mouse.display (ALLEGRO_DISPLAY *) : The display which had mouse focus.
.SS ALLEGRO_EVENT_MOUSE_BUTTON_UP
.PP
A mouse button was released.
.TP
.B mouse.x (int)
x\-coordinate
.RS
.RE
.TP
.B mouse.y (int)
y\-coordinate
.RS
.RE
.TP
.B mouse.z (int)
z\-coordinate
.RS
.RE
.TP
.B mouse.w (int)
w\-coordinate
.RS
.RE
.TP
.B mouse.button (unsigned)
The mouse button which was released, numbering from 1.
.RS
.RE
.TP
.B mouse.pressure (float)
Pressure, ranging from \f[C]0.0\f[] to \f[C]1.0\f[].
.RS
.RE
.PP
mouse.display (ALLEGRO_DISPLAY *) : The display which had mouse focus.
.SS ALLEGRO_EVENT_MOUSE_WARPED
.PP
al_set_mouse_xy(3) was called to move the mouse.
This event is identical to ALLEGRO_EVENT_MOUSE_AXES otherwise.
.SS ALLEGRO_EVENT_MOUSE_ENTER_DISPLAY
.PP
The mouse cursor entered a window opened by the program.
.TP
.B mouse.x (int)
x\-coordinate
.RS
.RE
.TP
.B mouse.y (int)
y\-coordinate
.RS
.RE
.TP
.B mouse.z (int)
z\-coordinate
.RS
.RE
.TP
.B mouse.w (int)
w\-coordinate
.RS
.RE
.PP
mouse.display (ALLEGRO_DISPLAY *) : The display which had mouse focus.
.SS ALLEGRO_EVENT_MOUSE_LEAVE_DISPLAY
.PP
The mouse cursor left the boundaries of a window opened by the program.
.TP
.B mouse.x (int)
x\-coordinate
.RS
.RE
.TP
.B mouse.y (int)
y\-coordinate
.RS
.RE
.TP
.B mouse.z (int)
z\-coordinate
.RS
.RE
.TP
.B mouse.w (int)
w\-coordinate
.RS
.RE
.PP
mouse.display (ALLEGRO_DISPLAY *) : The display which had mouse focus.
.SS ALLEGRO_EVENT_TOUCH_BEGIN
.PP
The touch input device registered a new touch.
.TP
.B touch.display (ALLEGRO_DISPLAY)
The display which was touched.
.RS
.RE
.TP
.B touch.id (int)
An identifier for this touch.
If supported by the device it will stay the same for events from the
same finger until the touch ends.
.RS
.RE
.TP
.B touch.x (float)
The x coordinate of the touch in pixels.
.RS
.RE
.TP
.B touch.y (float)
The y coordinate of the touch in pixels.
.RS
.RE
.TP
.B touch.dx (float)
Movement speed in pixels in x direction.
.RS
.RE
.TP
.B touch.dy (float)
Movement speed in pixels in y direction.
.RS
.RE
.TP
.B touch.primary (bool)
Whether this is the only/first touch or an additional touch.
.RS
.RE
.SH SINCE
.PP
5.1.0
.SS ALLEGRO_EVENT_TOUCH_END
.PP
A touch ended.
.PP
Has the same fields as ALLEGRO_EVENT_TOUCH_BEGIN(3).
.SH SINCE
.PP
5.1.0
.SS ALLEGRO_EVENT_TOUCH_MOVE
.PP
The position of a touch changed.
.PP
Has the same fields as ALLEGRO_EVENT_TOUCH_BEGIN(3).
.SH SINCE
.PP
5.1.0
.SS ALLEGRO_EVENT_TOUCH_CANCEL
.PP
A touch was cancelled.
This is device specific but could for example mean that a finger moved
off the border of the device or moved so fast that it could not be
tracked any longer.
.PP
Has the same fields as ALLEGRO_EVENT_TOUCH_BEGIN(3).
.SH SINCE
.PP
5.1.0
.SS ALLEGRO_EVENT_TIMER
.PP
A [timer]ALLEGRO_TIMER(3) counter incremented.
.PP
timer.source (ALLEGRO_TIMER *) : The timer which generated the event.
.TP
.B timer.count (int64_t)
The timer count value.
.RS
.RE
.SS ALLEGRO_EVENT_DISPLAY_EXPOSE
.PP
The display (or a portion thereof) has become visible.
.PP
display.source (ALLEGRO_DISPLAY *) : The display which was exposed.
.TP
.B display.x (int)
\ 
.RS
.RE
.TP
.B display.y (int)
\ 
.RS
.RE
The top\-left corner of the rectangle which was exposed.
.RS
.RE
.TP
.B display.width (int)
\ 
.RS
.RE
.TP
.B display.height (int)
The width and height of the rectangle which was exposed.
.RS
.RE
.RS
.PP
\f[I]Note:\f[] The display needs to be created with
ALLEGRO_GENERATE_EXPOSE_EVENTS flag for these events to be generated.
.RE
.SS ALLEGRO_EVENT_DISPLAY_RESIZE
.PP
The window has been resized.
.PP
display.source (ALLEGRO_DISPLAY *) : The display which was resized.
.TP
.B display.x (int)
\ 
.RS
.RE
.TP
.B display.y (int)
The position of the top\-level corner of the display.
.RS
.RE
.TP
.B display.width (int)
The new width of the display.
.RS
.RE
.TP
.B display.height (int)
The new height of the display.
.RS
.RE
.PP
You should normally respond to these events by calling
al_acknowledge_resize(3).
Note that further resize events may be generated by the time you process
the event, so these fields may hold outdated information.
.SS ALLEGRO_EVENT_DISPLAY_CLOSE
.PP
The close button of the window has been pressed.
.PP
display.source (ALLEGRO_DISPLAY *) : The display which was closed.
.SS ALLEGRO_EVENT_DISPLAY_LOST
.PP
When using Direct3D, displays can enter a "lost" state.
In that state, drawing calls are ignored, and upon entering the state,
bitmap\[aq]s pixel data can become undefined.
Allegro does its best to preserve the correct contents of bitmaps (see
the ALLEGRO_NO_PRESERVE_TEXTURE flag) and restore them when the device
is "found" (see ALLEGRO_EVENT_DISPLAY_FOUND(3)).
However, this is not 100% fool proof (see discussion in
al_create_bitmap(3)\[aq]s documentation).
.RS
.PP
\f[I]Note:\f[] This event merely means that the display was lost, that
is, DirectX suddenly lost the contents of all video bitmaps.
In particular, you can keep calling drawing functions \-\- they just
most likely won\[aq]t do anything.
If Allegro\[aq]s restoration of the bitmaps works well for you then no
further action is required when you receive this event.
.RE
.PP
display.source (ALLEGRO_DISPLAY *) : The display which was lost.
.SS ALLEGRO_EVENT_DISPLAY_FOUND
.PP
Generated when a lost device is restored to operating state.
See ALLEGRO_EVENT_DISPLAY_LOST(3).
.PP
display.source (ALLEGRO_DISPLAY *) : The display which was found.
.SS ALLEGRO_EVENT_DISPLAY_SWITCH_OUT
.PP
The window is no longer active, that is the user might have clicked into
another window or "tabbed" away.
.PP
display.source (ALLEGRO_DISPLAY *) : The display which was switched out
of.
.SS ALLEGRO_EVENT_DISPLAY_SWITCH_IN
.PP
The window is the active one again.
.PP
display.source (ALLEGRO_DISPLAY *) : The display which was switched
into.
.SS ALLEGRO_EVENT_DISPLAY_ORIENTATION
.PP
Generated when the rotation or orientation of a display changes.
.PP
display.source (ALLEGRO_DISPLAY *) : The display which generated the
event.
.TP
.B event.display.orientation
Contains one of the following values:
.RS
.IP \[bu] 2
ALLEGRO_DISPLAY_ORIENTATION_0_DEGREES
.IP \[bu] 2
ALLEGRO_DISPLAY_ORIENTATION_90_DEGREES
.IP \[bu] 2
ALLEGRO_DISPLAY_ORIENTATION_180_DEGREES
.IP \[bu] 2
ALLEGRO_DISPLAY_ORIENTATION_270_DEGREES
.IP \[bu] 2
ALLEGRO_DISPLAY_ORIENTATION_FACE_UP
.IP \[bu] 2
ALLEGRO_DISPLAY_ORIENTATION_FACE_DOWN
.RE
.SS ALLEGRO_EVENT_DISPLAY_HALT_DRAWING
.PP
When a display receives this event it should stop doing any drawing and
then call al_acknowledge_drawing_halt(3) immediately.
.PP
This is currently only relevant for Android and iOS.
It will be sent when the application is switched to background mode, in
addition to ALLEGRO_EVENT_DISPLAY_SWITCH_OUT(3).
The latter may also be sent in situations where the application is not
active but still should continue drawing, for example when a popup is
displayed in front of it.
.RS
.PP
\f[I]Note:\f[] This event means that the next time you call a drawing
function, your program will crash.
So you \f[I]must\f[] stop drawing and you \f[I]must\f[] immediately
reply with al_acknowledge_drawing_halt(3).
Allegro sends this event because it cannot handle this automatically.
Your program might be doing the drawing in a different thread from the
event handling, in which case the drawing thread needs to be signaled to
stop drawing before acknowledging this event.
.RE
.RS
.PP
\f[I]Note:\f[] Mobile devices usually never quit an application, so to
prevent the battery from draining while your application is halted it
can be a good idea to call al_stop_timer(3) on all your timers,
otherwise they will keep generating events.
If you are using audio, you can also stop all audio voices (or pass NULL
to al_set_default_voice(3) if you use the default mixer), otherwise
Allegro will keep streaming silence to the voice even if the stream or
mixer are stopped or detached.
.RE
.SH SINCE
.PP
5.1.0
.SH SEE ALSO
.PP
ALLEGRO_EVENT_DISPLAY_RESUME_DRAWING(3)
.SS ALLEGRO_EVENT_DISPLAY_RESUME_DRAWING
.PP
When a display receives this event, it may resume drawing again, and it
must call al_acknowledge_drawing_resume(3) immediately.
.PP
This is currently only relevant for Android and iOS.
The event will be sent when an application returns from background mode
and is allowed to draw to the display again, in addition to
ALLEGRO_EVENT_DISPLAY_SWITCH_IN(3).
The latter event may also be sent in a situation where the application
is already active, for example when a popup in front of it closes.
.RS
.PP
\f[I]Note:\f[] Unlike ALLEGRO_EVENT_DISPLAY_FOUND(3) it is not necessary
to reload any bitmaps when you receive this event.
.RE
.SH SINCE
.PP
5.1.0
.SH SEE ALSO
.PP
ALLEGRO_EVENT_DISPLAY_HALT_DRAWING(3)
.SS ALLEGRO_EVENT_DISPLAY_CONNECTED
.PP
This event is sent when a physical display is connected to the device
Allegro runs on.
Currently, on most platforms, Allegro supports only a single physical
display.
However, on iOS, a secondary physical display is suported.
.PP
display.source (ALLEGRO_DISPLAY *) : The display which was connected.
.SH SINCE
.PP
5.1.1
.SS ALLEGRO_EVENT_DISPLAY_DISCONNECTED
.PP
This event is sent when a physical display is disconnected from the
device Allegro runs on.
Currently, on most platforms, Allegro supports only a single physical
display.
However, on iOS, a secondary physical display is suported.
.PP
display.source (ALLEGRO_DISPLAY *) : The display which was disconnected.