= SDL_Event =
A union that contains structures for the different event types.


== Data Fields ==
{|
|Uint32
|'''type'''
|event type, shared with all events
|-
|[[SDL_CommonEvent]]
|'''common'''
|common event data
|-
|[[SDL_WindowEvent]]
|'''window'''
|window event data
|-
|[[SDL_KeyboardEvent]]
|'''key'''
|keyboard event data
|-
|[[SDL_TextEditingEvent]]
|'''edit'''
|text editing event data
|-
|[[SDL_TextInputEvent]]
|'''text'''
|text input event data
|-
|[[SDL_MouseMotionEvent]]
|'''motion'''
|mouse motion event data
|-
|[[SDL_MouseButtonEvent]]
|'''button'''
|mouse button event data
|-
|[[SDL_MouseWheelEvent]]
|'''wheel'''
|mouse wheel event data
|-
|[[SDL_JoyAxisEvent]]
|'''jaxis'''
|joystick axis event data
|-
|[[SDL_JoyBallEvent]]
|'''jball'''
|joystick ball event data
|-
|[[SDL_JoyHatEvent]]
|'''jhat'''
|joystick hat event data
|-
|[[SDL_JoyButtonEvent]]
|'''jbutton'''
|joystick button event data
|-
|[[SDL_JoyDeviceEvent]]
|'''jdevice'''
|joystick device event data
|-
|[[SDL_ControllerAxisEvent]]
|'''caxis'''
|game controller axis event data
|-
|[[SDL_ControllerButtonEvent]]
|'''cbutton'''
|game controller button event data
|-
|[[SDL_ControllerDeviceEvent]]
|'''cdevice'''
|game controller device event data
|-
|[[SDL_AudioDeviceEvent]]
|'''adevice'''
|audio device event data (>= SDL 2.0.4)
|-
|[[SDL_QuitEvent]]
|'''quit'''
|quit request event data
|-
|[[SDL_UserEvent]]
|'''user'''
|custom event data
|-
|[[SDL_SysWMEvent]]
|'''syswm'''
|system dependent window event data
|-
|[[SDL_TouchFingerEvent]]
|'''tfinger'''
|touch finger event data
|-
|[[SDL_MultiGestureEvent]]
|'''mgesture'''
|multi finger gesture data
|-
|[[SDL_DollarGestureEvent]]
|'''dgesture'''
|multi finger gesture data
|-
|[[SDL_DropEvent]]
|'''drop'''
|drag and drop event data
|}

== Remarks ==
The [[SDL_Event]] structure is the core of all event handling in SDL. [[SDL_Event]] is a union of all event structures used in SDL.  Using it is a simple matter of knowing which event type corresponds to which union member. The [[#table|table]] below lists these relationships.

The [[SDL_Event]] structure has two uses:
* [[#reading|Reading events from the event queue]]
* [[#push|Placing events on the event queue]]

<span id="reading"></span>
~+'''Reading events from 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.
<syntaxhighlight lang='c++'>
SDL_Event test_event;
</syntaxhighlight>
[[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.
<syntaxhighlight lang='c++'>
while (SDL_PollEvent(&test_event)) {
</syntaxhighlight>
The [[SDL_PollEvent]]() function takes 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 separately we use a ```switch``` statement.
<syntaxhighlight lang='c++'>
  switch (test_event.type) {
</syntaxhighlight>
We need to know what kind of events we're looking for and the event types of those events. So let's 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. Looking at the [[#table|table]] below tells us 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:
<syntaxhighlight lang='c++'>
    case SDL_MOUSEMOTION:
</syntaxhighlight>
All we need to do now is read the information out of the '''motion''' member of test_event.
<syntaxhighlight lang='c++'>
      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");
</syntaxhighlight>


<span id="push"></span>
~+'''Placing events on the event queue'''+~

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.
<syntaxhighlight lang='c++'>
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);
</syntaxhighlight>

<span id="table"></span>
~+'''Relationships between event types and union members'''+~
{|
|''Event Type''
|''Event Structure''
|''SDL_Event Field''
|-
|SDL_AUDIODEVICEADDED<br/>SDL_AUDIODEVICEREMOVED
|[[SDL_AudioDeviceEvent]]
|'''adevice'''
|-
|SDL_CONTROLLERAXISMOTION
|[[SDL_ControllerAxisEvent]]
|'''caxis'''
|-
|SDL_CONTROLLERBUTTONDOWN<br/>SDL_CONTROLLERBUTTONUP
|[[SDL_ControllerButtonEvent]]
|'''cbutton'''
|-
|SDL_CONTROLLERDEVICEADDED<br/>SDL_CONTROLLERDEVICEREMOVED<br/>SDL_CONTROLLERDEVICEREMAPPED
|[[SDL_ControllerDeviceEvent]]
|'''cdevice'''
|-
|SDL_DOLLARGESTURE<br/>SDL_DOLLARRECORD
|[[SDL_DollarGestureEvent]]
|'''dgesture'''
|-
|SDL_DROPFILE<br/>SDL_DROPTEXT<br/>SDL_DROPBEGIN<br/>SDL_DROPCOMPLETE
|[[SDL_DropEvent]]
|'''drop'''
|-
|SDL_FINGERMOTION<br/>SDL_FINGERDOWN<br/>SDL_FINGERUP
|[[SDL_TouchFingerEvent]]
|'''tfinger'''
|-
|SDL_KEYDOWN<br/>SDL_KEYUP
|[[SDL_KeyboardEvent]]
|'''key'''
|-
|SDL_JOYAXISMOTION
|[[SDL_JoyAxisEvent]]
|'''jaxis'''
|-
|SDL_JOYBALLMOTION
|[[SDL_JoyBallEvent]]
|'''jball'''
|-
|SDL_JOYHATMOTION
|[[SDL_JoyHatEvent]]
|'''jhat'''
|-
|SDL_JOYBUTTONDOWN<br/>SDL_JOYBUTTONUP
|[[SDL_JoyButtonEvent]]
|'''jbutton'''
|-
|SDL_JOYDEVICEADDED<br/>SDL_JOYDEVICEREMOVED
|[[SDL_JoyDeviceEvent]]
|'''jdevice'''
|-
|SDL_MOUSEMOTION
|[[SDL_MouseMotionEvent]]
|'''motion'''
|-
|SDL_MOUSEBUTTONDOWN<br/>SDL_MOUSEBUTTONUP
|[[SDL_MouseButtonEvent]]
|'''button'''
|-
|SDL_MOUSEWHEEL
|[[SDL_MouseWheelEvent]]
|'''wheel'''
|-
|SDL_MULTIGESTURE
|[[SDL_MultiGestureEvent]]
|'''mgesture'''
|-
|SDL_QUIT
|[[SDL_QuitEvent]]
|'''quit'''
|-
|SDL_SYSWMEVENT
|[[SDL_SysWMEvent]]
|'''syswm'''
|-
|SDL_TEXTEDITING
|[[SDL_TextEditingEvent]]
|'''edit'''
|-
|SDL_TEXTINPUT
|[[SDL_TextInputEvent]]
|'''text'''
|-
|SDL_USEREVENT
|[[SDL_UserEvent]]
|'''user'''
|-
|SDL_WINDOWEVENT
|[[SDL_WindowEvent]]
|'''window'''
|-
|Other events
|SDL_CommonEvent
|none, use [[SDL_EventType|.type]]
|}

== Related Enumerations ==
:[[SDL_EventType]]

== Related Structures ==
:[[SDL_AudioDeviceEvent]]
:[[SDL_ControllerAxisEvent]]
:[[SDL_ControllerButtonEvent]]
:[[SDL_ControllerDeviceEvent]]
:[[SDL_DollarGestureEvent]]
:[[SDL_DropEvent]]
:[[SDL_JoyAxisEvent]]
:[[SDL_JoyBallEvent]]
:[[SDL_JoyButtonEvent]]
:[[SDL_JoyDeviceEvent]]
:[[SDL_JoyHatEvent]]
:[[SDL_KeyboardEvent]]
:[[SDL_MouseButtonEvent]]
:[[SDL_MouseMotionEvent]]
:[[SDL_MouseWheelEvent]]
:[[SDL_MultiGestureEvent]]
:[[SDL_QuitEvent]]
:[[SDL_SysWMEvent]]
:[[SDL_TextEditingEvent]]
:[[SDL_TextInputEvent]]
:[[SDL_TouchFingerEvent]]
:[[SDL_UserEvent]]
:[[SDL_WindowEvent]]


== Related Functions ==
:[[SDL_PeepEvents]]
:[[SDL_PollEvent]]
:[[SDL_PushEvent]]
:[[SDL_WaitEvent]]
:[[SDL_WaitEventTimeout]]

----
[[CategoryStruct]], [[CategoryEvents]]