Previously, we've seen how we can retrieve aspects of our window's configuration by checking its window flags. However, we don't need to continuously monitor our SDL_Window to understand its state.

For most use cases, monitoring the event loop makes more sense. SDL dispatches a wide variety of events reporting actions performed on our window. In this lesson, we'll explore this in a bit more detail.

Starting Point

This lesson builds on the concepts from the previous lesson. To focus on window events, we will start with a minimal project containing a Window class and a main function with a basic application loop.

Files

src

Select a file to view its content

Window Events in SDL3

A major change from SDL2 to SDL3 is how window events are handled. In SDL2, all window-related events were bundled under a single SDL_WINDOWEVENT type. You had to first check for this general type, and then inspect a sub-event to find out what specifically happened.

In SDL3, this has been simplified. Window events are now top-level events, just like SDL_EVENT_KEY_DOWN or SDL_EVENT_QUIT. This means we can check for them directly in our event loop.

For example, to detect if a window has been minimized, we now check for SDL_EVENT_WINDOW_MINIMIZED directly on the SDL_Event's type member:

1while (SDL_PollEvent(&E)) {
2  if (E.type == SDL_EVENT_WINDOW_MINIMIZED) {
3    // The window was minimized
4  }
5}

Although the event type is now top-level, the detailed information about the event is still stored in the window member of the SDL_Event union, which is an SDL_WindowEvent struct.

Detecting Any Window Event

Behind the scenes, the type value of an SDL_Event is just an integer, and SDL3 has arranged these integers such that all window events fall within a specific range.

This gives us a way to detect any window event, if we prefer a design that closer matches the SDL2 pattern. To do this, SDL3 provides the SDL_EVENT_WINDOW_FIRST and SDL_EVENT_WINDOW_LAST variables, giving us visibility of where the range of window events begins and ends.

Therefore, we can check if the event was any window even by checking if its type falls within this range:

1if (E.type >= SDL_EVENT_WINDOW_FIRST &&
2    E.type <= SDL_EVENT_WINDOW_LAST) {
3  // This is a window event
4}

Let's create a handler function that takes an SDL_WindowEvent and logs a message. In our main loop, we'll check if an event is a window event and, if so, pass E.window to our handler.

src/main.cpp

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include <iostream>
4#include "Window.h"
5
6void HandleWindowEvent(const SDL_WindowEvent& E) {
7  std::cout << "Detected Window Event\n";
8}
9
10int main(int, char**) {
11  SDL_Init(SDL_INIT_VIDEO);
12  Window GameWindow;
13  SDL_Event E;
14
15  bool IsRunning = true;
16  while (IsRunning) {
17    while (SDL_PollEvent(&E)) {
18      if (E.type >= SDL_EVENT_WINDOW_FIRST &&
19          E.type <= SDL_EVENT_WINDOW_LAST
20        ) {
21        HandleWindowEvent(E.window);
22      } else if (E.type == SDL_EVENT_QUIT) {
23        IsRunning = false;
24      }
25    }
26    GameWindow.Render();
27    GameWindow.Update();
28  }
29
30  SDL_Quit();
31  return 0;
32}

1Detected Window Event
2Detected Window Event
3Detected Window Event

Reacting to Specific Window Events

Within our window event handler, we can still check the exact nature of the event with a more specific type check. For example, here's how we can react to a few common window events:

src/main.cpp

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include <iostream>
4#include "Window.h"
5
6void HandleWindowEvent(const SDL_WindowEvent& E) {
7  if (E.type == SDL_EVENT_WINDOW_MINIMIZED) {
8    std::cout << "Window Minimized\n";
9  } else if (E.type == SDL_EVENT_WINDOW_MOVED) {
10    std::cout << "Window Moved\n";
11  } else if (E.type == SDL_EVENT_WINDOW_MOUSE_ENTER) {
12    std::cout << "Cursor Entered the Window\n";
13  }
14}
15
16int main(int, char**) {/*...*/}

1Cursor Entered the Window
2Window Moved
3Window Minimized

Example: Mouse Entering and Leaving Window

In this example, we'll react to the user's cursor entering and leaving our window by using the SDL_SetWindowTitle() function to change the title based on these events:

src/main.cpp

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include <iostream>
4#include "Window.h"
5
6void HandleWindowEvent(
7  const SDL_WindowEvent& E, SDL_Window* Window
8) {
9  if (E.type == SDL_EVENT_WINDOW_MOUSE_ENTER) {
10    SDL_SetWindowTitle(
11      Window, "Mouse Inside the Window"
12    );
13  } else if (E.type == SDL_EVENT_WINDOW_MOUSE_LEAVE) {
14    SDL_SetWindowTitle(
15      Window, "Mouse Outside the Window"
16    );
17  }
18}
19
20int main(int, char**) {
21  SDL_Init(SDL_INIT_VIDEO);
22  Window GameWindow;
23  SDL_Event E;
24
25  bool IsRunning = true;
26  while (IsRunning) {
27    while (SDL_PollEvent(&E)) {
28      if (E.type >= SDL_EVENT_WINDOW_FIRST &&
29          E.type <= SDL_EVENT_WINDOW_LAST
30      ) {
31        HandleWindowEvent(
32          E.window, GameWindow.GetRaw()
33        );
34      } else if (E.type == SDL_EVENT_QUIT) {
35        IsRunning = false;
36      }
37    }
38    GameWindow.Render();
39    GameWindow.Update();
40  }
41
42  SDL_Quit();
43  return 0;
44}

Window IDs

In the previous example, our HandleWindowEvent() logic requires a pointer to the SDL_Window it needs to change the title of. We passed it as a second argument, but it's also possible to retrieve the SDL_Window directly from the SDL_WindowEvent.

Internally, SDL assigns a unique identifier to each window it creates. This ID is available on the windowID member of the SDL_WindowEvent struct. The type for this ID is SDL_WindowID, which is an alias for a Uint32.

1void HandleWindowEvent(const SDL_WindowEvent& E) {
2  SDL_WindowID id = E.windowID;
3  // ...
4}

The windowID variable exists on every event type that relates to a specific window. This includes types like SDL_KeyboardEvent, where the windowID will be the window with input focus, and SDL_MouseMotionEvent, where the ID will be the window the mouse is hovering over.

Getting an `SDL_Window*` Using `SDL_GetWindowFromID()`

By passing this window ID to SDL_GetWindowFromID(), we get the corresponding SDL_Window pointer:

1SDL_Window* Win{SDL_GetWindowFromID(E.windowID)};

Below, we update our program to use this technique, removing the need to pass our GameWindow pointer to the event handler. This makes the handler more self-contained.

src/main.cpp

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include <iostream>
4#include "Window.h"
5
6void HandleWindowEvent(const SDL_WindowEvent& E) {
7  SDL_Window* Window{
8    SDL_GetWindowFromID(E.windowID)
9  };
10  if (!Window) return;
11
12  if (E.type == SDL_EVENT_WINDOW_MOUSE_ENTER) {
13    SDL_SetWindowTitle(
14      Window, "Mouse Inside the Window"
15    );
16  } else if (E.type == SDL_EVENT_WINDOW_MOUSE_LEAVE) {
17    SDL_SetWindowTitle(
18      Window, "Mouse Outside the Window"
19    );
20  }
21}
22
23int main(int, char**) {/*...*/}

While not strictly necessary for a single-window application, this technique becomes essential in multi-window applications, where you need to know which specific window an event belongs to.

Getting a Window ID Using `SDL_GetWindowID()`

We can perform this conversion in the opposite direction using SDL_GetWindowID(). We pass it the SDL_Window pointer, and it returns the SDL_WindowID associated with that SDL_Window:

src/main.cpp

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include <iostream>
4
5int main(int, char**) {
6  SDL_Init(SDL_INIT_VIDEO);
7
8  SDL_Window* Window = SDL_CreateWindow(
9    "Window ID Example", 600, 300, 0
10  );
11
12  SDL_WindowID WindowID{SDL_GetWindowID(Window)};
13  std::cout << "The ID of the created window is: "
14    << WindowID << '\n';
15    
16  SDL_Event E;
17  bool IsRunning = true;
18  while (IsRunning) {
19    while (SDL_PollEvent(&E)) {
20      if (E.type == SDL_EVENT_QUIT) {
21        IsRunning = false;
22      }
23    }
24    GameWindow.Render();
25    GameWindow.Update();
26  }
27  
28  SDL_DestroyWindow(Window);
29  SDL_Quit();
30  return 0;
31}

1The ID of the created window is: 4

One scenario where this might be useful is when we're using SDL's event system for custom events within our game. SDL provides the SDL_UserEvent type for this purpose, and it includes a windowID member which we can provide if it would be useful to consumers:

1Uint32 GAME_OVER{SDL_RegisterEvents(1)};
2
3SDL_Event MyEvent{};
4MyEvent.type = GAME_OVER;
5MyEvent.user.windowID = SDL_GetWindowID(Window);
6
7SDL_PushEvent(&MyEvent);

Consumers can then retrieve the SDL_Window associated with the event in the usual way:

1void HandleGameOverEvent(const SDL_UserEvent& E){
2  SDL_Window* Window{
3    SDL_GetWindowFromID(E.windowID)
4  };
5  // ...
6}

We covered user events in a dedicated lesson earlier in the course:

Summary

In this lesson, we explored more of SDL3's window management systems, focusing on window events and unique identifiers. Key takeaways:

In SDL3, window events like SDL_EVENT_WINDOW_MINIMIZED are top-level events, simplifying event handling.
SDL_WindowEvent still provides detailed information about the event via event.window.
Window IDs uniquely identify SDL windows, which is crucial for multi-window applications.
Use SDL_GetWindowFromID() to retrieve an SDL_Window* from a window ID and SDL_GetWindowID() to find the ID associated with an SDL_Window*.

Window Events and Window IDs

Starting Point

Files

Window Events in SDL3

Detecting Any Window Event

src/main.cpp

Reacting to Specific Window Events

src/main.cpp

Example: Mouse Entering and Leaving Window

src/main.cpp

Window IDs

Getting an `SDL_Window*` Using `SDL_GetWindowFromID()`

src/main.cpp

Getting a Window ID Using `SDL_GetWindowID()`

src/main.cpp

Summary

Managing Window Position

Game Development with SDL3

Window Events and Window IDs

Starting Point

Files

Window Events in SDL3

Detecting Any Window Event

src/main.cpp

Reacting to Specific Window Events

src/main.cpp

Example: Mouse Entering and Leaving Window

src/main.cpp

Window IDs

Getting an SDL_Window* Using SDL_GetWindowFromID()

src/main.cpp

Getting a Window ID Using SDL_GetWindowID()

src/main.cpp

Summary

Managing Window Position

Getting an `SDL_Window*` Using `SDL_GetWindowFromID()`

Getting a Window ID Using `SDL_GetWindowID()`