---
name: "SDL_Event"
section: "3"
platform: "linux"
package: "libsdl1.2-dev"
version: "1.2.15+dfsg2-8"
release: "Debian 12 (Bookworm)"
platforms: ["linux"]
url: "https://new.carta.tech/SDL_Event"
---

# SDL\_Event(3)

General event structure

## 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.
");
      printf("Current mouse position is: (%d, %d)
", test_event.motion.x, test_event.motion.y);
      break;
    default:
      printf("Unhandled Event!
");
      break;
  }
}
printf("Event queue empty.
");
```

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**