Ubuntu Manpage: ALLEGRO_EVENT

NAME

       ALLEGRO_EVENT - Allegro 5 API

SYNOPSIS

              #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.source (ALLEGRO_EVENT_SOURCE *)
              The event source which generated the event.

       any.timestamp (double)
              When the event was generated.

       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_get_time(3alleg5).

       Each event is of one of the following types, with the usable fields given.

   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.

       keyboard.display (ALLEGRO_DISPLAY *)
              The display which had keyboard focus when the event occurred.

              Note:  this  event  is  about  the  physical  keys  being pressed on the keyboard.  Look for ALLE‐
              GRO_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.

       keyboard.display (ALLEGRO_DISPLAY *)
              The display which had keyboard focus when the event occurred.

   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 key‐
              code field.

              Some special keys will set the unichar field to their standard ASCII values: Tab=9, Return=13, Es‐
              cape=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.

       keyboard.display (ALLEGRO_DISPLAY *)
              The display which had keyboard focus when the event occurred.

              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 com‐
              mon 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.

       mouse.pressure (float)
              Pressure, ranging from 0.0 to 1.0.

       mouse.display (ALLEGRO_DISPLAY *)
              The display which had mouse focus.

              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(3alleg5) events instead which are identical ex‐
              cept for their type.

              Note: currently mouse.display may be NULL if an event is generated in response to al_set_mouse_ax‐
              is(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.

       mouse.pressure (float)
              Pressure, ranging from 0.0 to 1.0.

       mouse.display (ALLEGRO_DISPLAY *)
              The display which had mouse focus.

   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.

       mouse.pressure (float)
              Pressure, ranging from 0.0 to 1.0.

       mouse.display (ALLEGRO_DISPLAY *)
              The display which had mouse focus.

   ALLEGRO_EVENT_MOUSE_WARPED
       al_set_mouse_xy(3alleg5)   was   called   to   move   the  mouse.   This  event  is  identical  to  ALLE‐
       GRO_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

       mouse.display (ALLEGRO_DISPLAY *)
              The display which had mouse focus.

   ALLEGRO_EVENT_MOUSE_LEAVE_DISPLAY
       The mouse cursor left 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

       mouse.display (ALLEGRO_DISPLAY *)
              The display which had mouse focus.

   ALLEGRO_EVENT_TOUCH_BEGIN
       The touch input device registered a new touch.

       touch.display (ALLEGRO_DISPLAY)
              The display which was touched.

       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.

       touch.x (float)
              The x coordinate of the touch in pixels.

       touch.y (float)
              The y coordinate of the touch in pixels.

       touch.dx (float)
              Movement speed in pixels in x direction.

       touch.dy (float)
              Movement speed in pixels in y direction.

       touch.primary (bool)
              Whether this is the only/first touch or an additional touch.

SINCE

       5.1.0

   ALLEGRO_EVENT_TOUCH_END
       A touch ended.

       Has the same fields as ALLEGRO_EVENT_TOUCH_BEGIN(3alleg5).

SINCE

       5.1.0

   ALLEGRO_EVENT_TOUCH_MOVE
       The position of a touch changed.

       Has the same fields as ALLEGRO_EVENT_TOUCH_BEGIN(3alleg5).

SINCE

       5.1.0

   ALLEGRO_EVENT_TOUCH_CANCEL
       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.

       Has the same fields as ALLEGRO_EVENT_TOUCH_BEGIN(3alleg5).

SINCE

5.1.0

ALLEGRO_EVENT_TIMER
A [timer]ALLEGRO_TIMER(3alleg5) 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)

The top-left corner of the rectangle which was exposed.

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.

You should normally respond to these events by calling al_acknowledge_resize(3alleg5). Note that further
resize events may be generated by the time you process the event, so these fields may hold outdated in‐
formation.

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 the ALLEGRO_NO_PRESERVE_TEXTURE flag) and restore them when the device
is "found" (see ALLEGRO_EVENT_DISPLAY_FOUND(3alleg5)). However, this is not 100% fool proof (see discus‐
sion in al_create_bitmap(3alleg5)'s documentation).

Note: This event merely means that the display was lost, that is, DirectX suddenly lost the con‐
tents of all video bitmaps. In particular, you can keep calling drawing functions -- they just
most likely won't do anything. If Allegro's restoration of the bitmaps works well for you then no
further action is required when you receive this event.

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(3alleg5).

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.
In response to this event you might want to call al_clear_keyboard_state(3alleg5) (possibly passing dis‐
play.source as its argument) in order to prevent Allegro's keyboard state from getting out of sync.

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

ALLEGRO_EVENT_DISPLAY_HALT_DRAWING
When a display receives this event it should stop doing any drawing and then call al_acknowledge_draw‐
ing_halt(3alleg5) immediately.

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(3alleg5). 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.

Note: This event means that the next time you call a drawing function, your program will crash.
So you must stop drawing and you must immediately reply with al_acknowledge_drawing_halt(3alleg5).
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.

Note: 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(3alleg5) 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(3alleg5) if you use the default mixer), other‐
wise Allegro will keep streaming silence to the voice even if the stream or mixer are stopped or
detached.

SINCE

       5.1.0

SINCE

       5.1.0

SINCE

       5.1.1

   ALLEGRO_EVENT_DISPLAY_DISCONNECTED
       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 physi‐
       cal display is suported.

       display.source (ALLEGRO_DISPLAY *)
              The display which was disconnected.

Allegro reference manual                                                                  ALLEGRO_EVENT(3alleg5)

NAME

SYNOPSIS

DESCRIPTION

SINCE

SINCE

SINCE

SINCE

SINCE

SEE ALSO

SINCE

SEE ALSO

SINCE