Provided by: allegro5-doc_5.2.3.0-1_all bug

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

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

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

       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 except for their type.

              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.

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

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

   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
       discussion in al_create_bitmap(3alleg5)'s documentation).

              Note: 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'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  display.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_drawing_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), otherwise Allegro
              will keep streaming silence to the voice even if the stream or mixer are stopped or
              detached.

SINCE

       5.1.0

SEE ALSO

       ALLEGRO_EVENT_DISPLAY_RESUME_DRAWING(3alleg5)

   ALLEGRO_EVENT_DISPLAY_RESUME_DRAWING
       When  a  display  receives  this  event,  it  may  resume  drawing again, and it must call
       al_acknowledge_drawing_resume(3alleg5) immediately.

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

              Note: Unlike ALLEGRO_EVENT_DISPLAY_FOUND(3alleg5) it is not necessary to reload any
              bitmaps when you receive this event.

SINCE

       5.1.0

SEE ALSO

       ALLEGRO_EVENT_DISPLAY_HALT_DRAWING(3alleg5)

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

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

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 physical display is suported.

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