Event queues

An event queue buffers events generated by event sources that were registered with the queue.

Summary
An event queue buffers events generated by event sources that were registered with the queue.
Create a new, empty event queue, returning a pointer to object if successful.
Destroy the event queue specified.
Register the event source with the event queue specified.
Unregister an event source with an event queue.
Return true if the event queue specified is currently empty.
Take the next event packet out of the event queue specified, and copy the contents into RET_EVENT, returning true.
Copy the contents of the next event packet in the event queue specified into RET_EVENT and return true.
Drop the next event packet from the queue.
Drops all events, if any, from the queue.
Wait until the event queue specified is non-empty.
Wait until the event queue specified is non-empty.

Functions

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

bool al_event_queue_is_empty(ALLEGRO_EVENT_QUEUE *queue)

Return true if the event queue specified is currently empty.

al_get_next_event

bool al_get_next_event(ALLEGRO_EVENT_QUEUE *queue,
ALLEGRO_EVENT *ret_event)

Take the next event packet out of the event queue specified, and copy the contents into RET_EVENT, returning true.  The original event packet 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 packet 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_drop_next_event

void al_drop_next_event(ALLEGRO_EVENT_QUEUE *queue)

Drop the next event packet from the queue.  If the queue is empty, nothing happens.

al_flush_event_queue

void al_flush_event_queue(ALLEGRO_EVENT_QUEUE *queue)

Drops all events, if any, from the queue.

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 packet in the queue will be copied into RET_EVENT and removed from the queue.  If RET_EVENT is NULL the first event packet 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)

Wait until the event queue specified is non-empty.  If RET_EVENT is not NULL, the first event packet in the queue will be copied into RET_EVENT and removed from the queue.  If RET_EVENT is NULL the first event packet 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.

ALLEGRO_EVENT_QUEUE *al_create_event_queue(void)
Create a new, empty event queue, returning a pointer to object if successful.
void al_destroy_event_queue(ALLEGRO_EVENT_QUEUE *queue)
Destroy the event queue specified.
void al_register_event_source(ALLEGRO_EVENT_QUEUE *queue,
ALLEGRO_EVENT_SOURCE *source)
Register the event source with the event queue specified.
void al_unregister_event_source(ALLEGRO_EVENT_QUEUE *queue,
ALLEGRO_EVENT_SOURCE *source)
Unregister an event source with an event queue.
bool al_event_queue_is_empty(ALLEGRO_EVENT_QUEUE *queue)
Return true if the event queue specified is currently empty.
bool al_get_next_event(ALLEGRO_EVENT_QUEUE *queue,
ALLEGRO_EVENT *ret_event)
Take the next event packet out of the event queue specified, and copy the contents into RET_EVENT, returning true.
bool al_peek_next_event(ALLEGRO_EVENT_QUEUE *queue,
ALLEGRO_EVENT *ret_event)
Copy the contents of the next event packet in the event queue specified into RET_EVENT and return true.
void al_drop_next_event(ALLEGRO_EVENT_QUEUE *queue)
Drop the next event packet from the queue.
void al_flush_event_queue(ALLEGRO_EVENT_QUEUE *queue)
Drops all events, if any, from the queue.
void al_wait_for_event(ALLEGRO_EVENT_QUEUE *queue,
ALLEGRO_EVENT *ret_event)
Wait until the event queue specified is non-empty.
bool al_wait_for_event_timed(ALLEGRO_EVENT_QUEUE *queue,
ALLEGRO_EVENT *ret_event,
float secs)
Wait until the event queue specified is non-empty.