NewAPI/Events

From Allegro Wiki

Overview

An "event" is a thing that happens at some instant in time. The fact that this event occurred is captured in a piece of data, known also as an "event". In the documentation we sometimes use "event packet" for the latter meaning. The API uses "event" exclusively, for brevity.

Event packets can be created by some certain types of objects, collectively known as "event sources", and then placed into "event queues", in chronological order. The user can take event packets out of event queues, also in chronological order, and examine them. When the user no longer needs the event packet, the event packet can be "released" and the memory it uses will be reclaimed.

Figure: A simplified view

      event source 1 \       / event queue ----->---- user
                       \    /
      event source 2 ---->---- event queue ----->---- user
                       /    \
      event source 3 /       \ event queue ----->---- user

                   Event packets          The user takes event
                   are generated          packets out of the
                   and placed into        queue, examines them,
                   event queues.          then releases them.

Notes

• As of Allegro 4.3.1, events are limited to the built-in event sources. There is no method in place to allow the user to create his own event sources.

• Events are not the only way to process input. State based APIs similar to 4.2's are available. eg. Keyboard, Mouse, and Joystick.

Event Queues

Creating a Queue

Event queues are responsible for queuing up registered events in chronological order. There is no implicit queue, so you must create one in order to begin processing events. Any number of queues can be active at one time.

// create an empty queue
ALLEGRO_EVENT_QUEUE *event_queue = al_create_event_queue();

Registering Event Sources

An event queue with no registered event sources will just sit empty. An event source can be anything: a joystick, a mouse, a timer, etc. Each queue can monitor multiple sources, and each source can be registered to multiple event queues. (Nothing happens if you try to add an event source to the same event queue more than once.)

// add the keyboard to the event_queue
al_register_event_source(event_queue, (ALLEGRO_EVENT_SOURCE *)al_get_keyboard());

Note that the type casts to (ALLEGRO_EVENT_SOURCE *) are required.

Monitoring the Queue

The simplest way to process events is to wait until the queue has something in it.

ALLEGRO_EVENT event;
if (al_wait_for_event(event_queue, &event, 0.1))
{
        // process event
}

In the above example, Allegro will wait up to 100 milliseconds for an event. If one exists in that time frame, the function will immediately return true, and the event will be copied into event and removed from the queue.

There are two special cases:

• Passing 0 as the time will cause Allegro to wait indefinitely for an event.
• If you don't want to remove the event from the queue, you can pass NULL as event.

See the Event section for details on the event itself.

Unregistering Event Sources

If you no longer want to process events from a source, you can unregister it. If there are any events in the queue associated with that source, they will be lost. Trying to remove a source that doesn't exist in the queue will do nothing.

al_unregister_event_source(queue, (ALLEGRO_EVENT_SOURCE *)source);

Destroying an Event Queue

When you are done with a queue, you should destroy it. All of its registered sources will automatically be unregistered.

al_destroy_event_queue(queue);

Note that Allegro will automatically destroy event queues at shutdown, so it's not explicitly required.

For more information, see the Event Queue API.

Events

The event is stored as an ALLEGRO_EVENT union. All events have the following fields in common:

ALLEGRO_EVENT_TYPE       type;
ALLEGRO_EVENT_SOURCE *   any.source;
unsigned long       any.timestamp;

After examining the type field, you can 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().

For example, you could process the keyboard like:

if (event.type == ALLEGRO_EVENT_KEY_DOWN)
{
        // quit when the ESC key is pressed.
        if (event.keyboard.keycode == ALLEGRO_KEY_ESCAPE) return;
}

A complete list of events is available here.

See Also

• naturaldocs
• exnew_events.c