Record ALLEGRO_EVENT

Hierarchy
Methods
Properties

Unit

Declaration

type ALLEGRO_EVENT = record

Description

An ALLEGRO_EVENT is an 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_SOURCEptr) 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.

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

  • ALLEGRO_EVENT_JOYSTICK_AXIS A joystick axis value changed.

  • ALLEGRO_EVENT_JOYSTICK_BUTTON_DOWN A joystick button was pressed.

  • ALLEGRO_EVENT_JOYSTICK_BUTTON_UP A joystick button was released.

  • ALLEGRO_EVENT_JOYSTICK_CONFIGURATION A joystick was plugged in or unplugged. See al_reconfigure_joysticks for details.

  • ALLEGRO_EVENT_KEY_DOWN A keyboard key was pressed.

    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.

  • ALLEGRO_EVENT_KEY_CHAR A character was typed on the keyboard, or a character was auto-repeated.

    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.

    Note: Calling al_set_mouse_xy also will result in a change of axis values, but such a change is reported with ALLEGRO_EVENT_MOUSE_WARPED events instead which are identical except for their type.

    Note: currently mouse.display may be Nil if an event is generated in response to al_set_mouse_axis.

  • ALLEGRO_EVENT_MOUSE_BUTTON_DOWN A mouse button was pressed.

  • ALLEGRO_EVENT_MOUSE_BUTTON_UP A mouse button was released.

  • ALLEGRO_EVENT_MOUSE_WARPED al_set_mouse_xy 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.

  • ALLEGRO_EVENT_MOUSE_LEAVE_DISPLAY The mouse cursor left the boundaries of a window opened by the program.

  • ALLEGRO_EVENT_TOUCH_BEGIN The touch input device registered a new touch.

  • ALLEGRO_EVENT_TOUCH_END A touch ended.

  • ALLEGRO_EVENT_TOUCH_MOVE The position of a touch changed.

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

  • ALLEGRO_EVENT_TIMER A timer counter incremented.

  • ALLEGRO_EVENT_DISPLAY_EXPOSE The display (or a portion thereof) has become visible.

    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.

    You should normally respond to these events by calling al_acknowledge_resize. 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.

  • 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). However, this is not 100% fool proof (see discussion in al_create_bitmap'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.

  • ALLEGRO_EVENT_DISPLAY_FOUND Generated when a lost device is restored to operating state. See ALLEGRO_EVENT_DISPLAY_LOST.

  • ALLEGRO_EVENT_DISPLAY_SWITCH_OUT The window is no longer active, that is the user might have clicked into another window or "tabbed" away.

  • ALLEGRO_EVENT_DISPLAY_SWITCH_IN The window is the active one again.

  • ALLEGRO_EVENT_DISPLAY_ORIENTATION Generated when the rotation or orientation of a display changes.

  • ALLEGRO_EVENT_DISPLAY_HALT_DRAWING When a display receives this event it should stop doing any drawing and then call al_acknowledge_drawing_halt 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. 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. 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 on all your timers, otherwise they will keep generating events. If you are using audio, you can also stop all audio voices (or pass Nil to al_set_default_voice 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.

  • ALLEGRO_EVENT_DISPLAY_RESUME_DRAWING When a display receives this event, it may resume drawing again, and it must call al_acknowledge_drawing_resume 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. 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 it is not necessary to reload any bitmaps when you receive this event.

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

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

Overview

Fields

_type: ALLEGRO_EVENT_TYPE
any: ALLEGRO_ANY_EVENT
display: ALLEGRO_DISPLAY_EVENT
joystick: ALLEGRO_JOYSTICK_EVENT
keyboard: ALLEGRO_KEYBOARD_EVENT
mouse: ALLEGRO_MOUSE_EVENT
timer: ALLEGRO_TIMER_EVENT
touch: ALLEGRO_TOUCH_EVENT
user: ALLEGRO_USER_EVENT

Description

Fields

_type: ALLEGRO_EVENT_TYPE

The event type.

any: ALLEGRO_ANY_EVENT

any is to allow the user to access the other fields which are common to all event types, without using some specific type structure.

display: ALLEGRO_DISPLAY_EVENT

Information of display events.

joystick: ALLEGRO_JOYSTICK_EVENT

Information of joysitck events.

keyboard: ALLEGRO_KEYBOARD_EVENT

Information of keyboard events.

mouse: ALLEGRO_MOUSE_EVENT

Information of mouse events.

timer: ALLEGRO_TIMER_EVENT

Information of timer events.

touch: ALLEGRO_TOUCH_EVENT

Information of touch events.

user: ALLEGRO_USER_EVENT

Information of user events.


Generated by PasDoc 0.14.0. Generated on 2017-01-03 17:39:12.