Custom User Events

Previously, we’ve seen how SDL implements an event queue, which we can interact with using functions like SDL_PollEvent(). As standard, SDL will push events onto this queue to report actions like the user moving their mouse (SDL_MOUSEMOTION) or requesting the application close (SDL_QUIT).

However, we can also use SDL’s event system to manage custom events, that are specific to the game we’re making. For example, if we were making a first-person shooter, we could use this system to report when player fires their weapon or reloads.

In this lesson, we'll learn how to register and use custom events to create these game-specific behaviors.

We'll also look at how to organise our code around a custom event system, and see practical examples of how custom events can be used to manage game state and handle complex user interactions.

Creating and Pushing Events

An SDL_Event can be created like any other object:

1SDL_Event MyEvent;

Its most useful constructor allows us to specify the type. Below, we create an event with a type of SDL_QUIT. This is equivalent to what SDL creates internally when the player attempts to close the window from the menu bar, for example:

1#include <SDL.h>
2#include <iostream>
3
4int main(int argc, char** argv){
5  SDL_Event MyEvent{SDL_QUIT};
6
7  if (MyEvent.type == SDL_QUIT) {
8    std::cout << "That's a quit event";
9  }
10
11  return 0;
12}

1That's a quit event

SDL_PushEvent()

To add our event to SDL’s event queue, we pass a pointer to it to SDL_PushEvent(). It will then be available to our main application loop, like any other event:

1#include <iostream>
2#include <SDL.h>
3
4int main(int argc, char** argv){
5  SDL_Init(SDL_INIT_EVENTS);
6  SDL_Event Event;
7  bool shouldQuit{false};
8
9  while (!shouldQuit) {
10    while (SDL_PollEvent(&Event)) {
11      if (Event.type == SDL_QUIT) {
12        std::cout << "Quitting";
13        shouldQuit = true;
14      }
15    }
16    SDL_Event MyEvent{SDL_QUIT};
17    SDL_PushEvent(&MyEvent);
18  }
19
20  SDL_Quit();
21  return 0;
22}

1Quitting

In real use cases, we’re going to be pushing events from some other part of our application. For example, our UI might be rendering an exit button somewhere, and it is some function in that class that will be creating and pushing the event:

1#pragma once
2#include <SDL.h>
3
4class QuitButton : public Button {
5  void HandleLeftClick() {
6    SDL_Event QuitEvent{SDL_QUIT};
7    SDL_PushEvent(&QuitEvent);
8  }
9};

Event Storage Duration

The previous example may seem suspicious, as we’re providing SDL_PushEvent() a pointer to a local variable. QuitEvent’s memory location will be freed as soon as HandleLeftClick() ends, so it would seem possible that the event we receive in our main loop will be a dangling pointer.

However, this is not the case. Behind the scenes, SDL_PushEvent() copies the relevant data from the SDL_Event we provide into the event queue, so we do not need to worry about our local copy of the event expiring before it is processed in our main loop

Custom Events

Let’s see how we can now use SDL’s event system to handle custom events, whose type is specific to our program.

For example, our game might have a settings menu, and we’d like to use SDL’s event queue to report when the user requests to open that settings menu.

The first step of this process is to register our custom type with SDL. To do this, we call SDL_RegisterEvents(), passing an integer representing how many event types we want to register. In most cases, this will be 1:

1// Register new event type
2SDL_RegisterEvents(1);

This function will return a value that we can use as the type property when we create an SDL_Event. SDL event types are 32 bit unsigned integers and, behind the scenes, SDL_RegisterEvents() ensures that the integer it returns is unique.

That is, it does not conflict with any event types that SDL uses internally (such as SDL_QUIT) and it does not conflict with the type returned by any previous call to SDL_RegisterEvents()

Let’s save the value returned by our call, and use it to create an event:

1#include <iostream>
2#include <SDL.h>
3
4int main(int argc, char** argv){
5  SDL_Init(SDL_INIT_EVENTS);
6  SDL_Event Event;
7  bool shouldQuit{false};
8
9  Uint32 OPEN_SETTINGS{SDL_RegisterEvents(1)};
10  SDL_Event MyEvent{OPEN_SETTINGS};
11  SDL_PushEvent(&MyEvent);
12
13  while (!shouldQuit) {
14    while (SDL_PollEvent(&Event)) {
15      if (Event.type == SDL_QUIT) {
16        shouldQuit = true;
17      } else if (Event.type == OPEN_SETTINGS) {
18        std::cout << "The player wants to open"
19        " the settings menu\n";
20      }
21    }
22  }
23
24  SDL_Quit();
25  return 0;
26}

1The player wants to open the settings menu

As before, in real use cases, events will typically not be dispatched from our main.cpp file - rather, they’ll be dispatched from some object deeper within our game, such as a button on the UI.

However, with custom event types, this adds a little complexity. The files that push the custom event type and the files that use it all need access to the Uint32 representing it’s type - the OPEN_SETTINGS variable in the previous example.

To accommodate this, we can move our event registrations to a header file, and #include it where needed. It may also be helpful to put these variables in a namespace, with a name like UserEvents:

1//
2#pragma once
3#include <SDL.h>
4
5namespace UserEvents{
6  const inline Uint32 OPEN_SETTINGS{
7    SDL_RegisterEvents(1)};
8  const inline Uint32 CLOSE_SETTINGS{
9    SDL_RegisterEvents(1)};
10}

1#pragma once
2#include <SDL.h>
3#include "UserEvents.h"
4
5class ToggleSettingsButton: public Button {
6  void HandleLeftClick() {
7    SDL_Event Open{UserEvents::OPEN_SETTINGS};
8    SDL_PushEvent(&Open);
9  }
10  void HandleRightClick() {
11    SDL_Event Close{UserEvents::CLOSE_SETTINGS};
12    SDL_PushEvent(&Close);
13  }
14};

1#include <iostream>
2#include <SDL.h>
3#include "UserEvents.h"
4
5int main(int argc, char** argv){
6  SDL_Init(SDL_INIT_EVENTS);
7  SDL_Event Event;
8  bool shouldQuit{false};
9
10  while (!shouldQuit) {
11    while (SDL_PollEvent(&Event)) {
12      if (Event.type == SDL_QUIT) {
13        shouldQuit = true;
14      } else if (Event.type ==
15        UserEvents::OPEN_SETTINGS) {
16        std::cout << "The player wants to open"
17        " the settings menu\n";
18      } else if (Event.type ==
19        UserEvents::CLOSE_SETTINGS) {
20        std::cout << "The player wants to close"
21        " the settings menu\n";
22      }
23    }
24  }
25
26  SDL_Quit();
27  return 0;
28}

User Event Data

Just like the built in events can contain additional data (such as the x and y values of a SDL_MouseMotionEvent), so too can our custom events. Any event with a type returned from SDL_RegisterEvents() is considered a user event.

We can access the user event data from the user property of the SDL_Event. This will be a struct with a type of SDL_UserEvent:

1#include <SDL.h>
2#include <iostream>
3
4void PushUserEvent(Uint32 EventType){
5  SDL_Event MyEvent{EventType};
6  SDL_PushEvent(&MyEvent);
7}
8
9void HandleUserEvent(SDL_UserEvent& E){
10  std::cout << "That's a user event\n";
11}
12
13int main(int argc, char** argv) {
14  SDL_Init(SDL_INIT_EVENTS);
15  SDL_Event Event;
16  bool shouldQuit{false};
17
18  Uint32 OPEN_SETTINGS{SDL_RegisterEvents(1)};
19  PushUserEvent(OPEN_SETTINGS);
20
21  while (!shouldQuit) {
22    while (SDL_PollEvent(&Event)) {
23      if (Event.type == SDL_QUIT) {
24        shouldQuit = true;
25      } else if (Event.type == OPEN_SETTINGS) {
26        HandleUserEvent(Event.user);
27      }
28    }
29  }
30
31  SDL_Quit();
32  return 0;
33}

1That's a user event

An SDL_UserEvent struct has three members that we can attach data to:

• code - a 32 bit integer
• data1 - a void pointer (void*)
• data2 - a void pointer (void*)

The two void pointers tend to be the most useful. A void pointer can point to any type of data, so we can store anything we might need in the data1 and data2 members.

Note, however, that we must ensure that the objects that these pointers point to remain alive long enough so anything that receives our event can make use of them.

Below, we attach a pointer to an int and a float to our event. Both variables are global, so they remain alive even after our PushUserEvent() call ends:

1int SomeInt{42};
2float SomeFloat{9.8f};
3
4void PushUserEvent(Uint32 EventType){
5  SDL_Event MyEvent{EventType};
6  MyEvent.user.data1 = &SomeInt;
7  MyEvent.user.data2 = &SomeFloat;
8  SDL_PushEvent(&MyEvent);
9}

Accessing Void Pointers and Type Safety

To meaningfully use a void pointer, we first need to statically cast it to the correct type:

1void HandleUserEvent(SDL_UserEvent& E){
2  std::cout << "That's a user event - data1: "
3    << *static_cast<int*>(E.data1)
4    << ", data2: "
5    << *static_cast<float*>(E.data2) << '\n';

1That's a user event - data1: 42, data2: 9.8

Void pointers are considered somewhat unsafe by modern standards, as the compiler is unable to verify that we’re casting to the correct type.

If we update our code with the mistaken belief that data2 is an int, we don’t get any compiler error. Instead, our program simply has unexpected behavior at run time:

1void HandleUserEvent(SDL_UserEvent& E){
2  std::cout << "That's a user event - data1: "
3    << *static_cast<int*>(E.data1)
4    << ", data2: "
5    << *static_cast<int*>(E.data2) << '\n';

1That's a user event - data1: 42, data2: 1092406477

We introduce modern, safer alternatives to void* in our advanced course, such as std::variant and std::any. However, in this case, we’re forced to use void pointers, so we just have to be cautious.

One obvious strategy that can be helpful here is to ensure that the types pointed at by data1 and data2 are consistent for any given event type. For example, we don’t want OPEN_SETTINGS events to sometimes have data1 pointing at an int, and sometimes pointing at a float.

Every component that pushes OPEN_SETTINGS events onto the queue should by attaching the same type of data to the event.

Storing this in the User Event

We’re not restricted to storing simple primitive types in the data1 or data2 pointers. We can store pointers to any data type, including custom data types created specifically to support the respective event type, if needed.

A common pattern is for the event to include a pointer to the object that created it. This is particularly useful when we have multiple instances of some class that can push events. Code that handles those events will often need to know which specific instance the event came from.

We can do this using the this pointer:

1#pragma once
2#include <SDL.h>
3#include "UserEvents.h"
4
5class OpenSettingsButton: public Button {
6public:
7  std::string GetLocation() {
8    return "Sidebar";
9  }
10  int GetId() {
11    return 42;
12  }
13  void HandleLeftClick() {
14    SDL_Event Event{UserEvents::OPEN_SETTINGS};
15    Event.user.data1 = this;
16    SDL_PushEvent(&Event);
17  }
18};

This allows any function that receives the event to access the public methods of the object that sent it, which can be helpful for determing how it needs to react:

1void HandleUserEvent(SDL_UserEvent& E){
2  if (E.type != UserEvents::OPEN_SETTINGS) {
3    return;
4  }
5  auto Button = static_cast<OpenSettingsButton*>(
6    E.data1
7  );
8  std::cout << "Open Settings Event Received\n"
9    << "Button Location: "
10    << Button->GetLocation()
11    << ", id: " << Button->GetId() << '\n';
12}

1Open Settings Event Received
2Button Location: Sidebar, id: 42

Summary

In this lesson, we explored how to create and manage custom events in SDL2. We learned how to create and push events onto SDL's event queue using SDL_PushEvent(). We then delved into creating custom event types using SDL_RegisterEvents() and how to handle these events in our main loop.

The lesson also covered how to attach additional data to user events using the SDL_UserEvent struct, including the common pattern of storing a pointer to the object that created the event.

Next Lesson

Loading and Displaying Images

Learn how to load, display, and optimize image rendering in your applications

ContinueView Course