# Events

These functions are declared in the main Allegro header file:

    #include <allegro5/allegro.h>

## API: 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_current_time().

Each event is of one of the following types:

*   ALLEGRO_EVENT_JOYSTICK_AXIS - a joystick axis value changed.

    Fields are:
    -   joystick.stick,
    -   joystick.axis,
    -   joystick.pos (-1.0 to 1.0).

*   ALLEGRO_EVENT_JOYSTICK_BUTTON_DOWN - a joystick button was pressed.

    Fields are:
    -   joystick.button.
  
*   ALLEGRO_EVENT_JOYSTICK_BUTTON_UP - a joystick button was released.

    Fields are:
    -   joystick.button.

*   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 - Displays can be lost with some drivers (just
    Direct3D?). This means that rendering is impossible. The device will be
    restored as soon as it is possible. The program should be able to ignore
    this event and continue rendering however it will have no effect.

*   ALLEGRO_EVENT_DISPLAY_FOUND - Generated when a lost device is regained.
    Drawing will no longer be a no-op.

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

See also: [ALLEGRO_EVENT_SOURCE], [ALLEGRO_EVENT_TYPE], [ALLEGRO_USER_EVENT]

## API: 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;

See also: [al_emit_user_event]

## API: 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.

See also: [al_create_event_queue], [al_destroy_event_queue]

## API: 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.

See also: [ALLEGRO_EVENT], [al_init_user_event_source], [al_emit_user_event]

## API: ALLEGRO_EVENT_TYPE

An integer used to distinguish between different types of events.

See also: [ALLEGRO_EVENT], [ALLEGRO_GET_EVENT_TYPE],
[ALLEGRO_EVENT_TYPE_IS_USER]

## API: ALLEGRO_GET_EVENT_TYPE

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.

See also: [ALLEGRO_EVENT], [ALLEGRO_EVENT_TYPE_IS_USER]

## API: ALLEGRO_EVENT_TYPE_IS_USER

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

## API: al_create_event_queue

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

See also: [ALLEGRO_EVENT_QUEUE]

## API: al_init_user_event_source

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.

See also: [ALLEGRO_EVENT_SOURCE], [al_emit_user_event],
[al_destroy_user_event_source]

## API: al_destroy_event_queue

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

See also: [ALLEGRO_EVENT_QUEUE]

## API: al_destroy_user_event_source

Destroy an event source initialised with [al_init_user_event_source].

See also: [ALLEGRO_EVENT_SOURCE]

## API: al_drop_next_event

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

## API: al_emit_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.

See also: [ALLEGRO_USER_EVENT]

## API: al_event_queue_is_empty

Return true if the event queue specified is currently empty.

## API: al_flush_event_queue

Drops all events, if any, from the queue.

## API: al_get_event_source_data

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

See also: [al_set_event_source_data]

## API: al_get_next_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.

See also: [ALLEGRO_EVENT]

## API: al_peek_next_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.

See also: [ALLEGRO_EVENT]

## API: al_register_event_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.

See also: [ALLEGRO_EVENT_QUEUE], [ALLEGRO_EVENT_SOURCE]

## API: al_set_event_source_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.

See also: [al_get_event_source_data]

## API: al_unref_user_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.

See also: [al_emit_user_event].

## API: al_unregister_event_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.

## API: al_wait_for_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.

See also: [ALLEGRO_EVENT], [al_wait_for_event_timed],
[al_wait_for_event_until]

## API: al_wait_for_event_timed

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.

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

See also: [ALLEGRO_EVENT], [al_wait_for_event], [al_wait_for_event_until]

## API: al_wait_for_event_until

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.

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

See also: [ALLEGRO_EVENT], [ALLEGRO_TIMEOUT], [al_init_timeout],
[al_wait_for_event], [al_wait_for_event_timed]

