Creating Custom Events

This lesson builds upon the foundation we previously established, featuring a main loop, window management (Window.h), and basic UI elements (UI.h, Rectangle.h, Button.h).

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

Using SDL_PushEvent()

To add our event to SDL's event queue, we use SDL_PushEvent(), passing a pointer to our SDL_Event. It will then show up in our event loop, like any other event.

In the following example, we push an SDL_QUIT event when a Button instance is left-clicked:

1// Button.h
2#pragma once
3#include <SDL.h>
4#include "Rectangle.h"
5
6class UI;
7
8class Button : public Rectangle {
9 public:
10  Button(UI& UIManager, const SDL_Rect& Rect)
11  : Rectangle{Rect},
12    UIManager{UIManager}
13  {
14    SetColor({255, 165, 0, 255});
15  }
16
17  void OnLeftClick() override {
18    SDL_Event MyEvent{SDL_QUIT};
19    SDL_PushEvent(&MyEvent);
20  }
21
22private:
23  UI& UIManager;
24};

We're currently constructing a button in our UIManager, which we can click on to verify our code works.

Event Storage Duration

The previous example may seem suspicious, as we're passing SDL_PushEvent() a pointer to a local variable. Passing points to local variables is something we should always be suspicious of, as that local SDL_Event object will be destroyed as soon as the OnLeftClick() function ends.

Therefore, we should wonder if the event we later receive in our event loop will be a dangling pointer.

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

The event is copied into the queue, and the caller may dispose of the memory pointed to after SDL_PushEvent() returns.

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 almost all 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() since SDL was initialized.

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
7  Uint32 OPEN_SETTINGS{SDL_RegisterEvents(1)};
8  SDL_Event MyEvent{OPEN_SETTINGS};
9  SDL_PushEvent(&MyEvent);
10
11  SDL_Event Event;
12  while (true) {
13    while (SDL_PollEvent(&Event)) {
14      if (Event.type == SDL_QUIT) {
15        SDL_Quit();
16        return 0;
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  return 0;
25}

1The player wants to open the settings menu

Sharing Custom Event Types

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// UserEvents.h
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}

The inline specifier in this example allows us to #include this header file in multiple source files without violating the one definition rule. We covered namespaces, the one definition rule, and inline in more detail in this lesson in our introductory course:

Let's see a larger, more practical example of custom events in action. We'll have our Button to toggle a settings menu open and closed when clicked. Our program is very small and we could easily manage this without using the event queue, but let's stick with the contrivance so we can learn the concepts - they'll be important for larger projects.

A simple, but slightly flawed implementation of our Button might look like this:

1// Button.h
2// ...
3#include "UserEvents.h"
4// ...
5
6class Button : public Rectangle {
7 public:
8  // ...
9
10  void OnLeftClick() override {
11    SDL_Event Event{isSettingsOpen
12      ? UserEvents::CLOSE_SETTINGS
13      : UserEvents::OPEN_SETTINGS
14    };
15    SDL_PushEvent(&Event);
16    isSettingsOpen = !isSettingsOpen;
17  }
18
19private:
20  UI& UIManager;
21  bool isSettingsOpen{false};
22};

The flaw here is that our Button assumes it is the only component that can open and close a settings menu. If there is another component that can dispatch similar events, the isSettingsOpen boolean within our Button will fall out of sync.

An improvement here would be to have our button both send and react to CLOSE_SETTINGS and OPEN_SETTINGS events. That could look like this:

1// Button.h
2// ...
3
4class Button : public Rectangle {
5 public:
6  // ...
7  
8  void HandleEvent(SDL_Event& E) {
9    Rectangle::HandleEvent(E);
10    using namespace UserEvents;
11    if (E.type == CLOSE_SETTINGS) {
12      isSettingsOpen = false;
13    } else if (E.type == OPEN_SETTINGS) {
14      isSettingsOpen = true;
15    }
16  }
17
18  void OnLeftClick() override {
19    SDL_Event Event{isSettingsOpen
20      ? UserEvents::CLOSE_SETTINGS
21      : UserEvents::OPEN_SETTINGS
22    };
23
24    SDL_PushEvent(&Event);
25    isSettingsOpen = !isSettingsOpen;
26  }
27  
28  // ...
29};

Now, when any object opens or closes the settings menu, every Button is notified through the HandleEvent() calls flowing through our hierarchy, and they can keep their individual isSettingsOpen values in sync.

A better design would be to remove these isSettingsOpen variables entirely, and store that state in a single location that is easily accessible to all interested parties. That might be our UIManager object, for example, but we'll stick with our event-based implementation for now as that's what we're focusing on.

Let's also create a hypothetical SettingsMenu element that will monitor these events. It will become active when it encounters an OPEN_SETTINGS event, and inactive when it encounters a CLOSE_SETTINGS event:

1// SettingsMenu.h
2#pragma once
3#include <SDL.h>
4#include "UserEvents.h"
5
6class SettingsMenu {
7 public:
8  void HandleEvent(SDL_Event& E) {
9    if (E.type == UserEvents::OPEN_SETTINGS) {
10      isOpen = true;
11    }
12
13    // If the settings menu isn't open, we ignore
14    // all other events
15    if (!isOpen) return;
16
17    if (E.type == UserEvents::CLOSE_SETTINGS) {
18      isOpen = false;
19    }
20    // Handle other events - mouse motion, mouse
21    // buttons etc
22    // ...
23  }
24
25  void Render(SDL_Surface* Surface) const {
26    // Don't render if I'm not open
27    if (!isOpen) return;
28    
29    SDL_FillRect(
30      Surface,
31      &Rect,
32      SDL_MapRGB(
33        Surface->format,
34        Color.r, Color.g, Color.b
35      ));
36  }
37
38 private:
39  bool isOpen{false};
40  SDL_Rect Rect{100, 50, 200, 200};
41  SDL_Color Color{150, 150, 150, 255};
42};

We can add both of these elements to our UI manager in the normal way:

1#pragma once
2#include <SDL.h>
3#include "Button.h"
4#include "SettingsMenu.h"
5
6class UI {
7public:
8  void Render(SDL_Surface* Surface) const {
9    SettingsButton.Render(Surface);
10    Settings.Render(Surface);
11  }
12
13  void HandleEvent(SDL_Event& E) {
14    SettingsButton.HandleEvent(E);
15    Settings.HandleEvent(E);
16  }
17
18private:
19  Button SettingsButton{*this, {50, 50, 50, 50}};
20  SettingsMenu Settings;
21};

Clicking our button should now toggle our hypthetical SettingsMenu open and closed:

Just like SDL's 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// SettingsMenu.h
2#pragma once
3#include <SDL.h>
4#include "UserEvents.h"
5
6class SettingsMenu {
7 public:
8  void HandleEvent(SDL_Event& E) {
9    if (E.type == UserEvents::OPEN_SETTINGS ||
10        E.type == UserEvents::CLOSE_SETTINGS) {
11      HandleUserEvent(E.user);
12    }
13  }
14
15  // ...
16
17 private:
18  void HandleUserEvent(SDL_UserEvent& E) {
19    std::cout << "That's a user event\n";
20    using namespace UserEvents;
21    if (E.type == OPEN_SETTINGS) {
22      isOpen = true;
23    } else if (E.type == CLOSE_SETTINGS) {
24      isOpen = false;
25    }
26  }
27
28  // ...
29};

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 a pointer to 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.

The following approach will not work, as SomeInt is deleted as soon as OnLeftClick() ends, meaning data1 will be a dangling pointer:

1// Button.h
2// ...
3
4class Button : public Rectangle {
5 public:
6  // ...
7
8  void OnLeftClick() override {
9    using namespace UserEvents;
10    SDL_Event Event{
11      isSettingsOpen
12        ? CLOSE_SETTINGS
13        : OPEN_SETTINGS
14    };
15
16    int SomeInt{42};
17    Event.user.data1 = &SomeInt;
18
19    SDL_PushEvent(&Event);
20
21    // SomeInt is deleted here
22  }
23  // ...
24};

Let's attach some more durable values. In the following example, both SomeInt and SomeFloat are member variables, so they remain alive as long as the Button remains alive.

In this program, our Button is a member of our UIManager, and our UIManager is a local variable of our main function. As such, it remains alive until our program ends, so we don't need to worry about these variables getting deleted too soon:

1// Button.h
2// ...
3
4class Button : public Rectangle {
5 public:
6  // ...
7
8  void OnLeftClick() override {
9    using namespace UserEvents;
10    SDL_Event Event{
11      isSettingsOpen
12        ? CLOSE_SETTINGS
13        : OPEN_SETTINGS
14    };
15
16    Event.user.data1 = &SomeInt;
17    Event.user.data2 = &SomeFloat;
18
19    SDL_PushEvent(&Event);
20  }
21
22private:
23  int SomeInt{42};
24  float SomeFloat{9.8};
25  // ...
26};

Accessing Void Pointers and Type Safety

Over in SettingsMenu, let's read the values stored in the event. To meaningfully use a void pointer, we first need to statically cast it to the correct type:

1// SettingsMenu.h
2// ...
3
4class SettingsMenu {
5 public:
6  // ...
7
8 private:
9  void HandleUserEvent(SDL_UserEvent& E) {
10    std::cout << "That's a user event\n";
11
12    int* data1{static_cast<int*>(E.data1)};
13    std::cout << "data1: " << *data1 << '\n';
14
15    float* data2{static_cast<float*>(E.data2)};
16    std::cout << "data2: " << *data2;
17
18    using namespace UserEvents;
19    if (E.type == OPEN_SETTINGS) {
20      isOpen = true;
21    } else if (E.type == CLOSE_SETTINGS) {
22      isOpen = false;
23    }
24  }
25  
26  // ...
27};

1That's a user event
2data1: 42
3data2: 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:

1// SettingsMenu.h
2// ...
3
4class SettingsMenu {
5 // ...
6 
7 private:
8  void HandleUserEvent(SDL_UserEvent& E) {
9    std::cout << "That's a user event\n";
10
11    int* data1{static_cast<int*>(E.data1)};
12    std::cout << "data1: " << *data1 << '\n';
13
14    int* data2{static_cast<int*>(E.data2)};
15    std::cout << "data2: " << *data2;
16
17    using namespace UserEvents;
18    if (E.type == OPEN_SETTINGS) {
19      isOpen = true;
20    } else if (E.type == CLOSE_SETTINGS) {
21      isOpen = false;
22    }
23  }
24  
25  // ...
26};

1That's a user event
2data1: 42
3data2: 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.

The main strategy to mitigate this risk is to ensure that the types pointed at by data1 and data2 are consistent for any given event type. For example, we wouldn't want OPEN_SETTINGS events to sometimes have data1 pointing at an int, and sometimes pointing at a float. That unpredictability would make the data1 member very difficult to use for any component interested in the event.

Instead, every component that pushes OPEN_SETTINGS events onto the queue should by attaching the same type of data to the event. Then, any code that needs to react to that event knows that, if the event has a type of OPEN_SETTINGS, then the data1 and data2 types can be reliably inferred.

Storing Complex Types in User Events

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

Below, we add a new OpenSettingsConfig object, which lets the creator of an OPEN_SETTINGS request specify which part of the settings menu should be opened, and where it should be positioned:

1// UserEvents.h
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
11  enum class SettingsPage {
12    GAMEPLAY, GRAPHICS, AUDIO
13  };
14
15  struct SettingsConfig {
16    SettingsPage Page;
17    int x;
18    int y;
19  };
20}

Let's have our Button attach a pointer to a SettingsConfig object when it pushes an OpenSettings event:

1// Button.h
2#pragma once
3#include <SDL.h>
4#include "Rectangle.h"
5#include "UserEvents.h"
6
7class UI;
8
9class Button : public Rectangle {
10 public:
11  // ...
12
13  void OnLeftClick() override {
14    using namespace UserEvents;
15    SDL_Event Event{
16      isSettingsOpen
17        ? CLOSE_SETTINGS
18        : OPEN_SETTINGS
19    };
20
21    if (Event.type == OPEN_SETTINGS) {
22      Event.user.data1 = &Config;
23    }
24
25    SDL_PushEvent(&Event);
26  }
27
28private:
29  UserEvents::SettingsConfig Config{
30    UserEvents::SettingsPage::GAMEPLAY,
31    50, 100
32  };
33
34  // ...
35};

And let's have our SettingsMenu react to it:

1// SettingsMenu.h
2// ...
3
4class SettingsMenu {
5 public:
6  // ...
7
8 private:
9  void HandleUserEvent(SDL_UserEvent& E) {
10    using namespace UserEvents;
11    if (E.type == OPEN_SETTINGS) {
12      isOpen = true;
13
14      auto* Config{
15        static_cast<SettingsConfig*>(E.data1)
16      };
17
18      Rect.x = Config->x;
19      Rect.y = Config->y;
20      if (Config->Page == SettingsPage::GAMEPLAY) {
21        std::cout << "Page: Gameplay Settings\n";
22      }
23    } else if (E.type == CLOSE_SETTINGS) {
24      isOpen = false;
25    }
26  }
27
28  bool isOpen{false};
29  SDL_Rect Rect{100, 50, 200, 200};
30  SDL_Color Color{150, 150, 150, 255};
31};

Now, any component that requests the settings menu to open can control where it gets positioned, and what page it opens at:

1Page: Gameplay Settings

Storing this in the User Event

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// Button.h
2#pragma once
3#include <SDL.h>
4#include <string>
5
6#include "Rectangle.h"
7#include "UserEvents.h"
8
9class UI;
10
11class Button : public Rectangle {
12 public:
13  Button(UI& UIManager, const SDL_Rect& Rect)
14  : Rectangle{Rect},
15    UIManager{UIManager}
16  {
17    SetColor({255, 165, 0, 255});
18  }
19
20  void HandleEvent(SDL_Event& E) {
21    Rectangle::HandleEvent(E);
22    using namespace UserEvents;
23    if (E.type == CLOSE_SETTINGS) {
24      isSettingsOpen = false;
25    } else if (E.type == OPEN_SETTINGS) {
26      isSettingsOpen = true;
27    }
28  }
29
30  void OnLeftClick() override {
31    using namespace UserEvents;
32    SDL_Event Event{
33      isSettingsOpen
34        ? CLOSE_SETTINGS
35        : OPEN_SETTINGS
36    };
37
38    if (Event.type == OPEN_SETTINGS) {
39      Event.user.data1 = this;
40    }
41
42    SDL_PushEvent(&Event);
43  }
44
45  UserEvents::SettingsConfig GetConfig() {
46    return Config;
47  }
48
49  // Where is this button located?
50  std::string GetLocation() {
51    return "the main menu";
52  }
53
54private:
55  UserEvents::SettingsConfig Config{
56    UserEvents::SettingsPage::GAMEPLAY,
57    50, 100
58  };
59
60  UI& UIManager;
61  bool isSettingsOpen{false};
62};

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

1// SettingsMenu.h
2#pragma once
3#include <SDL.h>
4#include <iostream>
5#include "UserEvents.h"
6#include "Button.h"
7
8class SettingsMenu {
9 // ...
10
11 private:
12  void HandleUserEvent(SDL_UserEvent& E) {
13    using namespace UserEvents;
14    if (E.type == OPEN_SETTINGS) {
15      isOpen = true;
16
17      auto* Instigator{
18        static_cast<Button*>(E.data1)
19      };
20
21     std::cout << "I was opened from a button in "
22        << Instigator->GetLocation() << "\n";
23
24      Rect.x = Instigator->GetConfig().x;
25      Rect.y = Instigator->GetConfig().y;
26      if (
27        Instigator->GetConfig().Page ==
28          SettingsPage::GAMEPLAY
29      ) {
30        std::cout << "Page: Gameplay Settings\n";
31      }
32    } else if (E.type == CLOSE_SETTINGS) {
33      isOpen = false;
34    }
35  }
36
37  bool isOpen{false};
38  SDL_Rect Rect{100, 50, 200, 200};
39  SDL_Color Color{150, 150, 150, 255};
40};

1I was opened from a button in the main menu
2Page: Gameplay Settings

We should always be mindful of the type safety concerns around void pointers. Above, our SettingsMenu assumes that data1 of a OPEN_SETTINGS event always points to a Button.

As such, any time we push an OPEN_SETTINGS event, from anywhere in our application, we should ensure that a Button pointer is included. If that's not viable, we need to rethink our design and devise an alternative way for the SettingsMenu to get the data it needs.

Here's the complete code incorporating custom events for opening and closing a settings menu, including passing data with the event.

Note that this specific implementation, while demonstrating custom events, won't be directly carried forward. Our next lessons on text and image rendering will start from a simpler base to focus on those new concepts.

In this lesson, we explored SDL's capability for handling custom, application-specific events.

We learned the process of registering new event types with SDL_RegisterEvents(), pushing these events using SDL_PushEvent(), and handling them within the standard event loop.

We also covered attaching custom data, such as configuration objects or this pointers, to events using the user field, facilitating decoupled communication patterns.

Key Takeaways:

• SDL_RegisterEvents(1) reserves a unique Uint32 ID for a custom event.
• SDL_PushEvent() adds a copy of your SDL_Event to the queue.
• Custom events are processed in the main loop alongside standard SDL events.
• The SDL_Event union's user member (SDL_UserEvent) holds custom data.
• user.data1 and user.data2 are void pointers for arbitrary data.
• Safe use of user.data1 and user.data2 requires careful type casting (static_cast) and lifetime management.
• Custom events enable components to interact without direct dependencies.
• Storing event type IDs (Uint32) in a shared header (e.g., UserEvents.h) improves organization.