# Event system and events

These functions are declared in the main Allegro header file:

~~~~c
 #include <allegro5/allegro.h>
~~~~

Events are generated by event sources. Most notably, each of the input
subsystems provides an event source, but also timers, displays, and audio
streams will generate events.

Event sources are registered to event queues which aggregate events from
multiple sources. A single event source can also be registered to multiple
event queues.

Event queues can then be queried for events. In particular, it is possible
to wait until events become available in order to save CPU time. You can combine
this with [timers][ALLEGRO_TIMER] to make your main-loop run at a specific speed
without wasting CPU time or missing events.

In addition to the predefined event types, Allegro also allows for user-defined
events that can be generated by user-defined event sources.

The appropriate reaction to an event is determined by examining the fields of
the [ALLEGRO_EVENT] union according to the event type.

In addition to the events sent by Allegro core, there's also events send by the addons,
see [ALLEGRO_AUDIO_EVENT_TYPE] and [ALLEGRO_VIDEO_EVENT_TYPE].

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

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

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] 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] 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 NULL if an event is generated in
response to [al_set_mouse_axis].

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

Since: 5.1.0

### ALLEGRO_EVENT_TOUCH_MOVE

The position of a touch changed.

Has the same fields as [ALLEGRO_EVENT_TOUCH_BEGIN].

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

Since: 5.1.0

### ALLEGRO_EVENT_TIMER

A [timer][ALLEGRO_TIMER] 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)
:   The X position of the top-left corner of the rectangle which was exposed.

display.y (int)
:   The Y position of the top-left corner of the rectangle which was exposed.

display.width (int)
:   The width of the rectangle which was exposed.

display.height (int)
:   The 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)
:   The X position of the top-left corner of the display.

display.y (int)
:   The Y position of the top-left 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].
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]). 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.

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

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

Since: 5.1.0

See also: [ALLEGRO_EVENT_DISPLAY_RESUME_DRAWING]

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

Since: 5.1.0

See also: [ALLEGRO_EVENT_DISPLAY_HALT_DRAWING]

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

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

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

### ALLEGRO_EVENT_DROP

If a display is created with the ALLEGRO_DRAG_AND_DROP flag it will
generate ALLEGRO_EVENT_DROP events when files or text are dropped over
the display.

drop.x (int)
:    X coordinate that something is being dragged to

drop.y (int)
:    Y coordinate that something is being dragged to

drop.text (char *)
:    the filename or text that was dropped - this will be NULL while the
     item is being dragged and only set at the final drop.

     > *Note*: if the *text* field is not NULL ownership transfers to the event
               receiver and it must eventually be freed with al_free.

drop.is_file (bool)
:    if text is not NULL whether the text is a filename or just plain
     text.

drop.row (int)
:    if there is multiple files or multiple rows of text this will
     number them, starting with 0.

drop.is_complete (bool)
:    indicates that this event will be the last one sent for the drag&drop
     action. If *is_complete* is set before receiving an event
     where *text* was not NULL it means the user aborted the drag&drop.

Since: 5.2.9

> *[Unstable API]:* This is an experimental feature and currently only works for
the X11 backend.

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

Like all other event types this structure is a part of the ALLEGRO_EVENT union.
To access the fields in an ALLEGRO_EVENT variable `ev`, you would use:

-   ev.user.source
-   ev.user.data1
-   ev.user.data2
-   ev.user.data3
-   ev.user.data4

To create a new user event you would do this:

~~~~c
ALLEGRO_EVENT_SOURCE my_event_source;
ALLEGRO_EVENT my_event;
float some_var;

al_init_user_event_source(&my_event_source);

my_event.user.type = ALLEGRO_GET_EVENT_TYPE('M','I','N','E');
my_event.user.data1 = 1;
my_event.user.data2 = &some_var;

al_emit_user_event(&my_event_source, &my_event, NULL);
~~~~

Event type identifiers for user events are assigned by the user.
Please see the documentation for [ALLEGRO_GET_EVENT_TYPE] for the rules you
should follow when assigning identifiers.

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

## 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, but not necessarily, this will be made from four 8-bit character
codes, for example:

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

IDs less than 1024 are reserved for Allegro or its addons.
Don't use anything lower than `ALLEGRO_GET_EVENT_TYPE(0, 0, 4, 0)`.

You should try to make your IDs unique so they don't clash with any 3rd party
code you may be using.  Be creative.  Numbering from 1024 is not creative.

If you need multiple identifiers, you could define them like this:

~~~~c
#define BASE_EVENT   ALLEGRO_GET_EVENT_TYPE('M','I','N','E')
#define BARK_EVENT   (BASE_EVENT + 0)
#define MEOW_EVENT   (BASE_EVENT + 1)
#define SQUAWK_EVENT (BASE_EVENT + 2)

/* Alternatively */
enum {
   BARK_EVENT = ALLEGRO_GET_EVENT_TYPE('M','I','N','E'),
   MEOW_EVENT,
   SQUAWK_EVENT
};
~~~~

See also: [ALLEGRO_EVENT], [ALLEGRO_USER_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 the newly created
object if successful. Returns NULL on error.

See also: [al_register_event_source], [al_destroy_event_queue],
[ALLEGRO_EVENT_QUEUE]

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

This function does nothing if `queue` is NULL. (since 5.2.9)

See also: [al_create_event_queue], [ALLEGRO_EVENT_QUEUE]

## 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: [al_unregister_event_source], [ALLEGRO_EVENT_SOURCE]

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

See also: [al_register_event_source]

## API: al_is_event_source_registered

Return true if the event source is registered.

See also: [al_register_event_source]

Since: 5.2.0

## API: al_pause_event_queue

Pause or resume accepting new events into the event queue (to resume, pass false
for `pause`). Events already in the queue are unaffected.

While a queue is paused, any events which would be entered into the
queue are simply ignored.
This is an alternative to unregistering then re-registering all event
sources from the event queue, if you just need to prevent events piling
up in the queue for a while.

See also: [al_is_event_queue_paused]

Since: 5.1.0

## API: al_is_event_queue_paused

Return true if the event queue is paused.

See also: [al_pause_event_queue]

Since: 5.1.0

## API: al_is_event_queue_empty

Return true if the event queue specified is currently empty.

See also: [al_get_next_event], [al_peek_next_event]

## 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], [al_peek_next_event], [al_wait_for_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], [al_get_next_event], [al_drop_next_event]

## API: al_drop_next_event

Drop (remove) the next event from the queue.  If the queue is empty,
nothing happens.
Returns true if an event was dropped.

See also: [al_flush_event_queue], [al_is_event_queue_empty]

## API: al_flush_event_queue

Drops all events, if any, from the queue.

See also: [al_drop_next_event], [al_is_event_queue_empty]

## 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], [al_get_next_event]

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

`secs` determines approximately how many seconds to wait. If the call times
out, false is returned.  Otherwise, if an event ocurred, true is returned.

For compatibility with all platforms, `secs` must be 2,147,483.647 seconds or less.

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, if an event ocurred, true is returned.

For compatibility with all platforms, `timeout` must be 2,147,483.647 seconds or less.

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



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

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

The user event source will never be destroyed automatically.
You must destroy it manually with [al_destroy_user_event_source].

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

## API: al_destroy_user_event_source

Destroy an event source initialised with [al_init_user_event_source].

This does not free the memory, as that was user allocated to begin with.

See also: [ALLEGRO_EVENT_SOURCE]

## API: al_emit_user_event

Emit an event from a user event source.
The event source must have been initialised with [al_init_user_event_source].
Returns `false` if the event source isn't registered with any queues,
hence the event wouldn't have been delivered into any queues.

Events are *copied* in and out of event queues, so after this function
returns the memory pointed to by `event` may be freed or reused.
Some fields of the event being passed in may be modified by the function.

Reference counting will be performed if `dtor` is not NULL.
Whenever a copy of the event is made, the reference count increases.
You need to call [al_unref_user_event] to decrease the reference count
once you are done with a user event that you have received from
[al_get_next_event], [al_peek_next_event], [al_wait_for_event], etc.

Once 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, but *not* the event itself (since it is just a copy).

If `dtor` is NULL then reference counting will not be performed.
It is safe, but unnecessary, to call [al_unref_user_event] on non-reference
counted user events.

You can use al_emit_user_event to emit both user and non-user events from your
user event source. Note that emitting input events will not update the
corresponding input device states. For example, you may emit an event of type
[ALLEGRO_EVENT_KEY_DOWN], but it will not update the [ALLEGRO_KEYBOARD_STATE]
returned by [al_get_keyboard_state].

See also: [ALLEGRO_USER_EVENT], [al_unref_user_event]

## API: al_unref_user_event

Decrease the reference count of 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], [ALLEGRO_USER_EVENT]



## 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_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]
