SDL Wiki

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_GamepadAxisEvent

caxis

game controller axis event data

SDL_GamepadButtonEvent

cbutton

game controller button event data

SDL_GamepadDeviceEvent

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 below lists these relationships.

The SDL_Event structure has two uses:

~+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_EVENT_MOUSE_MOTION is, more than likely, the event we're looking for. Looking at the table below tells us that SDL_EVENT_MOUSE_MOTION events are handled within the SDL_MouseMotionEvent structure which is the motion member of SDL_Event. We can check for the SDL_EVENT_MOUSE_MOTION event type within our ```switch``` statement like so:

    case SDL_EVENT_MOUSE_MOTION:

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_GamepadAxisEvent

caxis

SDL_EVENT_GAMEPAD_BUTTON_DOWN
SDL_EVENT_GAMEPAD_BUTTON_UP

SDL_GamepadButtonEvent

cbutton

SDL_EVENT_GAMEPAD_ADDED
SDL_EVENT_GAMEPAD_REMOVED
SDL_EVENT_GAMEPAD_REMAPPED

SDL_GamepadDeviceEvent

cdevice |-dg

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 .type

SDL_EventType
SDL_AudioDeviceEvent
SDL_GamepadAxisEvent
SDL_GamepadButtonEvent
SDL_GamepadDeviceEvent
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
SDL_PeepEvents
SDL_PollEvent
SDL_PushEvent
SDL_WaitEvent
SDL_WaitEventTimeout

CategoryStruct, CategoryEvents


[ edit | delete | history | feedback | raw ]

[ front page | index | search | recent changes | git repo | offline html ]

All wiki content is licensed under Creative Commons Attribution 4.0 International (CC BY 4.0).
Wiki powered by ghwikipp.