SDL Library Documentation
Prev |  | Next

# SDL_Event

## Name

SDL_Event -- General event structure

## Structure Definition

    typedef union{
      Uint8 type;
      SDL_ActiveEvent active;
      SDL_KeyboardEvent key;
      SDL_MouseMotionEvent motion;
      SDL_MouseButtonEvent button;
      SDL_JoyAxisEvent jaxis;
      SDL_JoyBallEvent jball;
      SDL_JoyHatEvent jhat;
      SDL_JoyButtonEvent jbutton;
      SDL_ResizeEvent resize;
      SDL_ExposeEvent expose;
      SDL_QuitEvent quit;
      SDL_UserEvent user;
      SDL_SysWMEvent syswm;
    } SDL_Event;

## Structure Data

`type` | The type of event
`active` | Activation event
`key` | Keyboard event
`motion` | Mouse motion event
`button` | Mouse button event
`jaxis` | Joystick axis motion event
`jball` | Joystick trackball motion event
`jhat` | Joystick hat motion event
`jbutton` | Joystick button event
`resize` | Application window resize event
`expose` | Application window expose event
`quit` | Application quit request event
`user` | User defined event
`syswm` | Undefined window manager event

## Description

The SDL_Event union is the core to all event handling is SDL, its probably the most important structure after SDL_Surface. SDL_Event is a union of all event structures used in SDL, using it is a simple matter of knowing which union member relates to which event `type`.

Event `type` | Event Structure
--- | ---
`SDL_ACTIVEEVENT` | SDL_ActiveEvent
`SDL_KEYDOWN/UP` | SDL_KeyboardEvent
`SDL_MOUSEMOTION` | SDL_MouseMotionEvent
`SDL_MOUSEBUTTONDOWN/UP` | SDL_MouseButtonEvent
`SDL_JOYAXISMOTION` | SDL_JoyAxisEvent
`SDL_JOYBALLMOTION` | SDL_JoyBallEvent
`SDL_JOYHATMOTION` | SDL_JoyHatEvent
`SDL_JOYBUTTONDOWN/UP` | SDL_JoyButtonEvent
`SDL_QUIT` | SDL_QuitEvent
`SDL_SYSWMEVENT` | SDL_SysWMEvent
`SDL_VIDEORESIZE` | SDL_ResizeEvent
`SDL_VIDEOEXPOSE` | SDL_ExposeEvent
`SDL_USEREVENT` | SDL_UserEvent

## Use

The SDL_Event structure has two uses

- Reading events on the event queue

- Placing events on the event queue

Reading events from the event queue is done with either `SDL_PollEvent` or `SDL_PeepEvents`. We'll use `SDL_PollEvent` and step through an example.

First off, we create an empty SDL_Event structure.

    SDL_Event test_event;

`SDL_PollEvent` removes the next event from the event queue, if there are no events on the queue it returns 0 otherwise it returns 1. We use a `while` loop to process each event in turn.

    while(SDL_PollEvent(&test_event)) {

The `SDL_PollEvent` function take a pointer to an SDL_Event structure that is to be filled with event information. We know that if `SDL_PollEvent` removes an event from the queue then the event information will be placed in our test_event structure, but we also know that the type of event will be placed in the `type` member of test_event. So to handle each event `type` seperately we use a `switch` statement.

      switch(test_event.type) {

We need to know what kind of events we're looking for and the event `type`'s of those events. So lets assume we want to detect where the user is moving the mouse pointer within our application. We look through our event types and notice that `SDL_MOUSEMOTION` is, more than likely, the event we're looking for. A little more research tells use that `SDL_MOUSEMOTION` events are handled within the SDL_MouseMotionEvent structure which is the `motion` member of SDL_Event. We can check for the `SDL_MOUSEMOTION` event `type` within our `switch` statement like so:

        case SDL_MOUSEMOTION:

All we need do now is read the information out of the `motion` member of test_event.

          printf("We got a motion event.\n");
          printf("Current mouse position is: (%d, %d)\n", test_event.motion.x, test_event.motion.y);
          break;
        default:
          printf("Unhandled Event!\n");
          break;
      }
    }
    printf("Event queue empty.\n");

It is also possible to push events onto the event queue and so use it as a two-way communication path. Both `SDL_PushEvent` and `SDL_PeepEvents` allow you to place events onto the event queue. This is usually used to place a `SDL_USEREVENT` on the event queue, however you could use it to post fake input events if you wished. Creating your own events is a simple matter of choosing the event type you want, setting the `type` member and filling the appropriate member structure with information.

    SDL_Event user_event;

    user_event.type=SDL_USEREVENT;
    user_event.user.code=2;
    user_event.user.data1=NULL;
    user_event.user.data2=NULL;
    SDL_PushEvent(&user_event);

## See Also

`SDL_PollEvent`, `SDL_PushEvent`, `SDL_PeepEvents`

Prev | Home | Next
SDL Event Structures. | Up | SDL_ActiveEvent