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_DisplayEvent

display

display 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 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_MOUSEMOTION is, more than likely, the event we're looking for. Looking at the 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_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);

~+Relationships between event types and union members+~

Event Type

Event Structure

SDL_Event Field

SDL_AUDIODEVICEADDED
SDL_AUDIODEVICEREMOVED

SDL_AudioDeviceEvent

adevice

SDL_CONTROLLERAXISMOTION

SDL_ControllerAxisEvent

caxis

SDL_CONTROLLERBUTTONDOWN
SDL_CONTROLLERBUTTONUP

SDL_ControllerButtonEvent

cbutton

SDL_CONTROLLERDEVICEADDED
SDL_CONTROLLERDEVICEREMOVED
SDL_CONTROLLERDEVICEREMAPPED

SDL_ControllerDeviceEvent

cdevice

SDL_DOLLARGESTURE
SDL_DOLLARRECORD

SDL_DollarGestureEvent

dgesture

SDL_DROPFILE
SDL_DROPTEXT
SDL_DROPBEGIN
SDL_DROPCOMPLETE

SDL_DropEvent

drop

SDL_FINGERMOTION
SDL_FINGERDOWN
SDL_FINGERUP

SDL_TouchFingerEvent

tfinger

SDL_KEYDOWN
SDL_KEYUP

SDL_KeyboardEvent

key

SDL_JOYAXISMOTION

SDL_JoyAxisEvent

jaxis

SDL_JOYBALLMOTION

SDL_JoyBallEvent

jball

SDL_JOYHATMOTION

SDL_JoyHatEvent

jhat

SDL_JOYBUTTONDOWN
SDL_JOYBUTTONUP

SDL_JoyButtonEvent

jbutton

SDL_JOYDEVICEADDED
SDL_JOYDEVICEREMOVED

SDL_JoyDeviceEvent

jdevice

SDL_MOUSEMOTION

SDL_MouseMotionEvent

motion

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

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