= 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_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_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]]
~+'''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.
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 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.
switch (test_event.type) {
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:
case SDL_MOUSEMOTION:
All we need to 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");
~+'''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_EVENT_USER 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_EVENT_USER;
user_event.user.code = 2;
user_event.user.data1 = NULL;
user_event.user.data2 = NULL;
SDL_PushEvent(&user_event);
~+'''Relationships between event types and union members'''+~
{|
|''Event Type''
|''Event Structure''
|''SDL_Event Field''
|-
|SDL_EVENT_AUDIO_DEVICE_ADDED
SDL_EVENT_AUDIO_DEVICE_REMOVED
|[[SDL_AudioDeviceEvent]]
|'''adevice'''
|-
|SDL_EVENT_GAMEPAD_AXIS_MOTION
|[[SDL_ControllerAxisEvent]]
|'''caxis'''
|-
|SDL_EVENT_GAMEPAD_BUTTON_DOWN
SDL_EVENT_GAMEPAD_BUTTON_UP
|[[SDL_ControllerButtonEvent]]
|'''cbutton'''
|-
|SDL_EVENT_GAMEPAD_ADDED
SDL_EVENT_GAMEPAD_REMOVED
SDL_EVENT_GAMEPAD_REMAPPED
|[[SDL_ControllerDeviceEvent]]
|'''cdevice'''
|-dg
|SDL_EVENT_DROP_FILE
SDL_EVENT_DROP_TEXT
SDL_EVENT_DROP_BEGIN
SDL_EVENT_DROP_COMPLETE
|[[SDL_DropEvent]]
|'''drop'''
|-
|SDL_EVENT_FINGER_MOTION
SDL_EVENT_FINGER_DOWN
SDL_EVENT_FINGER_UP
|[[SDL_TouchFingerEvent]]
|'''tfinger'''
|-
|SDL_EVENT_KEY_DOWN
SDL_EVENT_KEY_UP
|[[SDL_KeyboardEvent]]
|'''key'''
|-
|SDL_EVENT_JOYSTICK_AXIS_MOTION
|[[SDL_JoyAxisEvent]]
|'''jaxis'''
|-
|SDL_EVENT_JOYSTICK_HAT_MOTION
|[[SDL_JoyHatEvent]]
|'''jhat'''
|-
|SDL_EVENT_JOYSTICK_BUTTON_DOWN
SDL_EVENT_JOYSTICK_BUTTON_UP
|[[SDL_JoyButtonEvent]]
|'''jbutton'''
|-
|SDL_EVENT_JOYSTICK_ADDED
SDL_EVENT_JOYSTICK_REMOVED
|[[SDL_JoyDeviceEvent]]
|'''jdevice'''
|-
|SDL_EVENT_MOUSE_MOTION
|[[SDL_MouseMotionEvent]]
|'''motion'''
|-
|SDL_EVENT_MOUSE_BUTTONDOWN
SDL_EVENT_MOUSE_BUTTONUP
|[[SDL_MouseButtonEvent]]
|'''button'''
|-
|SDL_EVENT_MOUSE_WHEEL
|[[SDL_MouseWheelEvent]]
|'''wheel'''
|-
|SDL_EVENT_QUIT
|[[SDL_QuitEvent]]
|'''quit'''
|-
|SDL_EVENT_SYSWM
|[[SDL_SysWMEvent]]
|'''syswm'''
|-
|SDL_EVENT_TEXT_EDITING
|[[SDL_TextEditingEvent]]
|'''edit'''
|-
|SDL_EVENT_TEXT_INPUT
|[[SDL_TextInputEvent]]
|'''text'''
|-
|SDL_EVENT_USER
|[[SDL_UserEvent]]
|'''user'''
|-
|SDL_EVENT_WINDOW_HIDDEN
SDL_EVENT_WINDOW_EXPOSED
SDL_EVENT_WINDOW_MOVED
SDL_EVENT_WINDOW_RESIZED
SDL_EVENT_WINDOW_SIZE_CHANGED
SDL_EVENT_WINDOW_MINIMIZED
SDL_EVENT_WINDOW_MAXIMIZED
SDL_EVENT_WINDOW_RESTORED
SDL_EVENT_WINDOW_MOUSE_ENTER
SDL_EVENT_WINDOW_MOUSE_LEAVE
SDL_EVENT_WINDOW_FOCUS_GAINED
SDL_EVENT_WINDOW_FOCUS_LOST
SDL_EVENT_WINDOW_CLOSE_REQUESTED
SDL_EVENT_WINDOW_TAKE_FOCUS
SDL_EVENT_WINDOW_HIT_TEST
SDL_EVENT_WINDOW_ICCPROF_CHANGED
SDL_EVENT_WINDOW_DISPLAY_CHANGED
|[[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_DropEvent]]
:[[SDL_JoyAxisEvent]]
:[[SDL_JoyButtonEvent]]
:[[SDL_JoyDeviceEvent]]
:[[SDL_JoyHatEvent]]
:[[SDL_KeyboardEvent]]
:[[SDL_MouseButtonEvent]]
:[[SDL_MouseMotionEvent]]
:[[SDL_MouseWheelEvent]]
:[[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]]