Events

These functions are declared in the main Allegro header file:

#include <allegro5/allegro.h>

ALLEGRO_EVENT

typedef union ALLEGRO_EVENT 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_get_time.

Each event is of one of the following types:

ALLEGRO_EVENT_JOYSTICK_AXIS - a joystick axis value changed.
Fields are:
- joystick.id,
- joystick.stick,
- joystick.axis,
- joystick.pos (-1.0 to 1.0).
ALLEGRO_EVENT_JOYSTICK_BUTTON_DOWN - a joystick button was pressed.
Fields are:
- joystick.id,
- joystick.button.
ALLEGRO_EVENT_JOYSTICK_BUTTON_UP - a joystick button was released.
Fields are:
- joystick.id,
- joystick.button.
ALLEGRO_EVENT_JOYSTICK_CONFIGURATION - a joystick was plugged in or unplugged.
ALLEGRO_EVENT_KEY_DOWN - a keyboard key was pressed.
Fields:
- keyboard.keycode,
- keyboard.unichar,
- keyboard.modifiers,
- keyboard.display.
ALLEGRO_EVENT_KEY_REPEAT - a typed character auto-repeated.
Fields:
- keyboard.keycode (ALLEGRO_KEY_*),
- keyboard.unichar (unicode character),
- keyboard.modifiers (ALLEGRO_KEYMOD_*),
- keyboard.display.
ALLEGRO_EVENT_KEY_UP - a keyboard key was released.
Fields:
- keyboard.keycode,
- keyboard.display.
ALLEGRO_EVENT_MOUSE_AXES - one or more mouse axis values changed.
Fields:
- mouse.x,
- mouse.y,
- mouse.z,
- mouse.dx,
- mouse.dy,
- mouse.dz,
- mouse.display.
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.
Note: currently mouse.display may be NULL if an event is generated in response to al_set_mouse_axis.
ALLEGRO_EVENT_MOUSE_BUTTON_DOWN - a mouse button was pressed.
Fields:
- mouse.x,
- mouse.y,
- mouse.z,
- mouse.button,
- mouse.display.
ALLEGRO_EVENT_MOUSE_BUTTON_UP - a mouse button was released.
Fields:
- mouse.x,
- mouse.y,
- mouse.z,
- mouse.button,
- mouse.display.
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.
Fields:
- mouse.x,
- mouse.y,
- mouse.z,
- mouse.display.
ALLEGRO_EVENT_MOUSE_LEAVE_DISPLAY - the mouse cursor leave the boundaries of a window opened by the program.
Fields:
- mouse.x,
- mouse.y,
- mouse.z,
- mouse.display.
ALLEGRO_EVENT_TIMER - a timer counter incremented.
Fields:
- timer.count.
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.
Fields:
- display.x,
- display.y,
- display.width,
- display.height
ALLEGRO_EVENT_DISPLAY_RESIZE - The window has been resized.
Fields:
- display.x,
- display.y,
- display.width,
- display.height
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 ALLEGRO_NO_PRESERVE_TEXTURE) and restore them when the device is "found" (see ALLEGRO_EVENT_DISPLAY_FOUND) However, this is not 100% fool proof. To ensure that all bitmap contents are restored accurately, one must take additional steps; the best procedure to follow if bitmap constancy is important to you is as follows: first, always have the ALLEGRO_NO_PRESERVE_TEXTURE flag set to true when creating bitmaps, as it incurs pointless overhead when using this method. Second, create a mechanism in your game for easily reloading all of your bitmaps -- for example, wrap them in a class or data structure and have a "bitmap manager" that can reload them back to the desired state. Then, when you receive an ALLEGRO_EVENT_DISPLAY_FOUND event, tell the bitmap manager (or whatever your mechanism is) to restore your bitmaps.
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_USER_EVENT

typedef struct ALLEGRO_USER_EVENT ALLEGRO_USER_EVENT;

An event structure that can be emitted by user event sources. These are the public fields:

ALLEGRO_EVENT_SOURCE *source;
intptr_t data1;
intptr_t data2;
intptr_t data3;
intptr_t data4;

ALLEGRO_EVENT_QUEUE

typedef struct ALLEGRO_EVENT_QUEUE ALLEGRO_EVENT_QUEUE;

An event queue holds events that have been generated by event sources that are registered with the queue. Events are stored in the order they are generated. Access is in a strictly FIFO (first-in-first-out) order.

ALLEGRO_EVENT_SOURCE

typedef struct ALLEGRO_EVENT_SOURCE ALLEGRO_EVENT_SOURCE;

An event source is any object which can generate events. For example, an ALLEGRO_DISPLAY can generate events, and you can get the ALLEGRO_EVENT_SOURCE pointer from an ALLEGRO_DISPLAY with al_get_display_event_source.

You may create your own "user" event sources that emit custom events.

ALLEGRO_EVENT_TYPE

typedef unsigned int ALLEGRO_EVENT_TYPE;

An integer used to distinguish between different types of events.

ALLEGRO_GET_EVENT_TYPE

#define ALLEGRO_GET_EVENT_TYPE(a, b, c, d)   AL_ID(a, b, c, d)

Make an event type identifier, which is a 32-bit integer. Usually this will be made from four 8-bit character codes, for example:

#define MY_EVENT_TYPE   ALLEGRO_GET_EVENT_TYPE('M','I','N','E')

You should try to make your IDs unique so they don't clash with any 3rd party code you may be using.

IDs less than 1024 are reserved for Allegro or its addons.

ALLEGRO_EVENT_TYPE_IS_USER

#define ALLEGRO_EVENT_TYPE_IS_USER(t)        ((t) >= 512)

A macro which evaluates to true if the event type is not a builtin event type, i.e. one of those described in ALLEGRO_EVENT_TYPE.

al_create_event_queue

ALLEGRO_EVENT_QUEUE *al_create_event_queue(void)

Create a new, empty event queue, returning a pointer to object if successful. Returns NULL on error.

al_init_user_event_source

void al_init_user_event_source(ALLEGRO_EVENT_SOURCE *src)

Initialise an event source for emitting user events. The space for the event source must already have been allocated.

One possible way of creating custom event sources is to derive other structures with ALLEGRO_EVENT_SOURCE at the head, e.g.

typedef struct THING THING;

struct THING {
    ALLEGRO_EVENT_SOURCE event_source;
    int field1;
    int field2;
    /* etc. */
};

THING *create_thing(void)
{
    THING *thing = malloc(sizeof(THING));

    if (thing) {
        al_init_user_event_source(&thing->event_source);
        thing->field1 = 0;
        thing->field2 = 0;
    }

    return thing;
}

The advantage here is that the THING pointer will be the same as the ALLEGRO_EVENT_SOURCE pointer. Events emitted by the event source will have the event source pointer as the source field, from which you can get a pointer to a THING by a simple cast (after ensuring checking the event is of the correct type).

However, it is only one technique and you are not obliged to use it.

al_destroy_event_queue

void al_destroy_event_queue(ALLEGRO_EVENT_QUEUE *queue)

Destroy the event queue specified. All event sources currently registered with the queue will be automatically unregistered before the queue is destroyed.

al_destroy_user_event_source

void al_destroy_user_event_source(ALLEGRO_EVENT_SOURCE *src)

Destroy an event source initialised with al_init_user_event_source.

al_drop_next_event

bool al_drop_next_event(ALLEGRO_EVENT_QUEUE *queue)

Drop the next event from the queue. If the queue is empty, nothing happens. Returns true iff an event was dropped.

al_emit_user_event

bool al_emit_user_event(ALLEGRO_EVENT_SOURCE *src,
   ALLEGRO_EVENT *event, void (*dtor)(ALLEGRO_USER_EVENT *))

Emit a user event. The event source must have been initialised with al_init_user_event_source. Some fields of the event being passed in may be modified. Returns false if the event source isn't registered with any queues, hence the event wouldn't have been delivered into any queues.

Reference counting will be performed on the event if dtor is non-NULL. When the reference count drops to zero dtor will be called with a copy of the event as an argument. It should free the resources associated with the event. If dtor is NULL then reference counting will not be performed.

You need to call al_unref_user_event when you are done with a reference counted user event that you have gotten from al_get_next_event, al_peek_next_event, al_wait_for_event, etc. You may, but do not need to, call al_unref_user_event on non-reference counted user events.

al_is_event_queue_empty

bool al_is_event_queue_empty(ALLEGRO_EVENT_QUEUE *queue)

Return true if the event queue specified is currently empty.

al_flush_event_queue

void al_flush_event_queue(ALLEGRO_EVENT_QUEUE *queue)

Drops all events, if any, from the queue.

al_get_event_source_data

intptr_t al_get_event_source_data(const ALLEGRO_EVENT_SOURCE *source)

Returns the abstract user data associated with the event source. If no data was previously set, returns NULL.

al_get_next_event

bool al_get_next_event(ALLEGRO_EVENT_QUEUE *queue, ALLEGRO_EVENT *ret_event)

Take the next event out of the event queue specified, and copy the contents into ret_event, returning true. The original event will be removed from the queue. If the event queue is empty, return false and the contents of ret_event are unspecified.

al_peek_next_event

bool al_peek_next_event(ALLEGRO_EVENT_QUEUE *queue, ALLEGRO_EVENT *ret_event)

Copy the contents of the next event in the event queue specified into ret_event and return true. The original event packet will remain at the head of the queue. If the event queue is actually empty, this function returns false and the contents of ret_event are unspecified.

al_register_event_source

void al_register_event_source(ALLEGRO_EVENT_QUEUE *queue,
   ALLEGRO_EVENT_SOURCE *source)

Register the event source with the event queue specified. An event source may be registered with any number of event queues simultaneously, or none. Trying to register an event source with the same event queue more than once does nothing.

al_set_event_source_data

void al_set_event_source_data(ALLEGRO_EVENT_SOURCE *source, intptr_t data)

Assign the abstract user data to the event source. Allegro does not use the data internally for anything; it is simply meant as a convenient way to associate your own data or objects with events.

al_unref_user_event

void al_unref_user_event(ALLEGRO_USER_EVENT *event)

Unreference a user-defined event. This must be called on any user event that you get from al_get_next_event, al_peek_next_event, al_wait_for_event, etc. which is reference counted. This function does nothing if the event is not reference counted.

al_unregister_event_source

void al_unregister_event_source(ALLEGRO_EVENT_QUEUE *queue,
   ALLEGRO_EVENT_SOURCE *source)

Unregister an event source with an event queue. If the event source is not actually registered with the event queue, nothing happens.

If the queue had any events in it which originated from the event source, they will no longer be in the queue after this call.

al_wait_for_event

void al_wait_for_event(ALLEGRO_EVENT_QUEUE *queue, ALLEGRO_EVENT *ret_event)

Wait until the event queue specified is non-empty. If ret_event is not NULL, the first event in the queue will be copied into ret_event and removed from the queue. If ret_event is NULL the first event is left at the head of the queue.

al_wait_for_event_timed

bool al_wait_for_event_timed(ALLEGRO_EVENT_QUEUE *queue,
   ALLEGRO_EVENT *ret_event, float secs)

timeout_msecs determines approximately how many seconds to wait. If the call times out, false is returned. Otherwise true is returned.

al_wait_for_event_until

bool al_wait_for_event_until(ALLEGRO_EVENT_QUEUE *queue,
   ALLEGRO_EVENT *ret_event, ALLEGRO_TIMEOUT *timeout)

timeout determines how long to wait. If the call times out, false is returned. Otherwise true is returned.

Allegro version 4.9.22 (WIP) - Last updated: 2010-09-26 11:48:24 UTC