Allegro 5 Tutorial/Events

From Allegro Wiki
Jump to: navigation, search

In this section we teach you about events, and how Allegro's event system works.

What are Events?

Events tell you that something has happened in your program such as a key being pressed, the mouse has moved, a timer has been ticked, and the display has synchronized. Allegro uses them to notify you of all types of events, but you may create your own customized events if required.

Why do I want Events?

Using Allegro's event queue system is the most efficient way to handle events; you simply wait for the arrival of new events and handle them when they occur. An alternative method of handling events is via polling -- constantly checking whether an event has occurred. The event system reduces processor usage compared to the polling method.

Event Sources

An event source is something that notifies the program when something has occurred. There are several standard Allegro event sources, including but not limited to Timers, Displays, and Inputs.

Event Queues

An event queue is where events are placed in a first-in-first-out container and are removed when the events are being handled by the main program. You may create multiple event queues and direct the event sources into the appropriate queues. However, using a single event queue is the simplest method.

Basic Example

Extending on the previous example, we will create a program that lets you exit by pressing the X (close) button on the example's window.

#include <stdio.h>
#include <allegro5/allegro.h>
 
int main(int argc, char **argv){
   
   ALLEGRO_DISPLAY *display = NULL;
   ALLEGRO_EVENT_QUEUE *event_queue = NULL;

   if(!al_init()) {
      fprintf(stderr, "failed to initialize allegro!\n");
      return -1;
   }

   display = al_create_display(640, 480);
   if(!display) {
      fprintf(stderr, "failed to create display!\n");
      return -1;
   }

   event_queue = al_create_event_queue();
   if(!event_queue) {
      fprintf(stderr, "failed to create event_queue!\n");
      al_destroy_display(display);
      return -1;
   }
 
   al_register_event_source(event_queue, al_get_display_event_source(display));

   al_clear_to_color(al_map_rgb(0,0,0));
 
   al_flip_display();
 
   while(1)
   {
      ALLEGRO_EVENT ev;
      ALLEGRO_TIMEOUT timeout;
      al_init_timeout(&timeout, 0.06);
      
      bool get_event = al_wait_for_event_until(event_queue, &ev, &timeout);

      if(get_event && ev.type == ALLEGRO_EVENT_DISPLAY_CLOSE) {
         break;
      }

      al_clear_to_color(al_map_rgb(0,0,0));
      al_flip_display();
   }
 
   al_destroy_display(display);
   al_destroy_event_queue(event_queue);

   return 0;
}

Walk through

This walk through includes code from the previous Display example. Refer to the previous tutorial's walk through for information on code that is not explained here.

   event_queue = al_create_event_queue();

al_create_event_queue will return a new ALLEGRO_EVENT_QUEUE object. Should this function fail, it will return NULL. While failure is unlikely in this simple example, you are better off checking every single function that could fail for any errors. You may have fewer hidden problems when the program becomes more complicated.

   al_register_event_source(event_queue, al_get_display_event_source(display));

Here we actually tie the Display to the event queue so we can be informed of events from the display such as the close event. Without this function call, the display events will not be placed in this queue and thus will not be handled.

   ALLEGRO_TIMEOUT timeout;
   al_init_timeout(&timeout, 0.06);
al_init_timeout initializes a previously defined ALLEGRO_TIMEOUT object. In this case we are initializing it to 0.06 seconds from now, or 60 milliseconds in the future.
   bool get_event = al_wait_for_event_until(event_queue, &ev, &timeout);

We tell Allegro to wait till an event arrives, or until the time out defined previously has elapsed, which ever occurs first. al_wait_for_event_until will return false if it didn't return an event before the timeout.

if(get_event && ev.type == ALLEGRO_EVENT_DISPLAY_CLOSE) {
   break;
}

Here we check if we received an event in the event queue. If it is a Display close event, we break out of the program loop.

That concludes our basic introduction to Events in Allegro.