Window Events and Window IDs

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.

SDL_WindowEvent

SDL_Event objects that correspond to window events will have a type of SDL_WINDOWEVENT. If an SDL_Event has the SDL_WINDOWEVENT type, a more specific SDL_WindowEvent is available within the window variable:

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

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

Window events are used to report a wide range of actions, covering events like the window being resized, moved, and minimized. The nature of the event is available within the event variable of an SDL_WindowEvent. This variable has a type of SDL_WindowEventID, with possible values being listed in the official documentation.

We’ll cover many of these events and how to make use of them throughout the remainder of this chapter. In this example, we implement a basic reaction to just a few of them:

1#include <SDL.h>
2#include <iostream>
3#include "Window.h"
4
5void HandleWindowEvent(SDL_WindowEvent& E) {
6  if (E.event == SDL_WINDOWEVENT_MINIMIZED) {
7    std::cout << "Window Minimized\n";
8  } else if (E.event == SDL_WINDOWEVENT_MOVED) {
9    std::cout << "Window Moved\n";
10  } else if (E.event == SDL_WINDOWEVENT_ENTER) {
11    std::cout << "Cursor Entered the Window\n";
12  }
13}
14
main Function|Show
15int main(int argc, char** argv) {/*...*/}

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. We’ll use the SDL_SetWindowTitle() function to change the title based on these events:

1#include <SDL.h>
2#include <iostream>
3
4void HandleWindowEvent(SDL_WindowEvent& E, SDL_Window* Window) {
5  if (E.event == SDL_WINDOWEVENT_ENTER) {
6    SDL_SetWindowTitle(Window, "Mouse Inside the Window");
7  } else if (E.event == SDL_WINDOWEVENT_LEAVE) {
8    SDL_SetWindowTitle(Window, "Mouse Outside the Window");
9  }
10}
11
12int main(int argc, char** argv) {
13  SDL_Init(SDL_INIT_VIDEO);
14  Window GameWindow;
15  SDL_Event E;
16
17  while (true) {
18    while (SDL_PollEvent(&E)) {
19      if (E.type == SDL_WINDOWEVENT) {
20        HandleWindowEvent(E.window, GameWindow.SDLWindow);
21      } else if (E.type == SDL_QUIT) {
22        SDL_Quit();
23        return 0;
24      }
25    }
26    GameWindow.Update();
27    GameWindow.Render();
28  }
29}

Window IDs

In the previous example, our HandleWindowEvent() logic requires a pointer to the SDL_Window it needs to change the title of. We did this by passing it to the handler as a second argument, but it’s also possible to retrieve the SDL_Window from the SDL_WindowEvent.

Internally, SDL assigns a unique identifier to each window it creates, in the form of a simple integer. The ID of the window associated with the event is available on the windowID member of the SDL_WindowEvent:

1#include <SDL.h>
2#include <iostream>
3#include "Window.h"
4
5void HandleKeydownEvent(SDL_KeyboardEvent& E) {
6  if (E.keysym.sym == SDLK_SPACE) {
7    std::cout << "\nWindowID: " << E.windowID;
8  }
9}
10
main Function|Show
11int main(int argc, char** argv) {/*...*/}

1WindowID: 1

Above, we’re responding to an SDL_WindowEvent, but this 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 and SDL_MouseButtonEvent, where the ID will be the window the mouse is hovering over.

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 previous program to combine these techniques to position the SDL_Window directly, rather than passing a reference to our Window object to our event handler and using our Move() method:

1#include <SDL.h>
2#include <iostream>
3#include "Window.h"
4
5void HandleKeydownEvent(SDL_KeyboardEvent& E) {
6  if (E.keysym.sym == SDLK_SPACE) {
7    SDL_SetWindowPosition(
8      SDL_GetWindowFromID(E.windowID),
9      SDL_WINDOWPOS_CENTERED,
10      SDL_WINDOWPOS_CENTERED);
11  }
12}
13
main Function|Show
14int main(int argc, char** argv) {/*...*/}

The SDL_GetWindowFromID() approach is unnecessary in this case - it’s easier to use the initial technique where we simply provided a reference to our GameWindow to the event handler.

However, using SDL_GetWindowFromID() becomes valuable in multi-window applications, where we need to know which specific window should respond to user input. We cover multi-window applications and window IDs in more detail later in this chapter.

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 window ID associated with that SDL_Window:

1#include <SDL.h>
2#include <iostream>
3
4int main(int argc, char** argv) {
5  SDL_Init(SDL_INIT_VIDEO);
6
7  SDL_Window* Window = SDL_CreateWindow(
8      "Window ID Example",
9      SDL_WINDOWPOS_CENTERED,
10      SDL_WINDOWPOS_CENTERED,
11      800,
12      600,
13      SDL_WINDOW_SHOWN
14  );
15
16  int WindowID = SDL_GetWindowID(Window);
17  std::cout << "The ID of the created window is: "
18    << WindowID << '\n';
19
20  SDL_DestroyWindow(Window);
21  SDL_Quit();
22  return 0;
23}

1The ID of the created window is: 1

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 needed:

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

We can then retrieve the SDL_Window associated with the event within its handlers:

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

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

Custom User Events

Discover how to use the SDL2 event system to handle custom, game-specific interactions

Summary

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

• SDL_WindowEvent captures specific window-related actions like moving, resizing, or minimizing.
• Window IDs uniquely identify SDL windows.
• Use SDL_GetWindowFromID() to retrieve an SDL_Window* from a window ID and SDL_GetWindowID() to find the ID associated with an SDL_Window*.

Next Lesson

Managing Window Position

Learn how to control and monitor the position of SDL windows on screen

ContinueView Course