Multiple Windows and Utility Windows

When a window is closed (e.g., by the user clicking the 'X' button), an SDL_EVENT_WINDOW_CLOSE_REQUESTED event is pushed to the queue.

In single-window applications, we generally don't need to care about this event. This is because, by default, SDL also dispatches an SDL_EVENT_QUIT when the last (or only) window is closed, and we're currently shutting down our application when we detect that event.

However, in multi-window programs, we need to react to these individual SDL_EVENT_WINDOW_CLOSE_REQUESTED events, too.

In the following example, we open two windows and, when a user requests one be closed, we dutifully destroy it. We'll offload this complexity to a WindowManager in the next section, but a basic implementation might look something like this:

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include "Window.h"
4
5int main(int, char**) {
6  SDL_Init(SDL_INIT_VIDEO);
7
8  SDL_Window* Window1{SDL_CreateWindow(
9    "Window 1", 600, 300, 0
10  )};
11
12  SDL_Window* Window2{SDL_CreateWindow(
13    "Window 2", 600, 300, 0
14  )};
15
16  SDL_Event E;
17  bool IsRunning = true;
18  while (IsRunning) {
19    while (SDL_PollEvent(&E)) {
20      if (E.type == SDL_EVENT_WINDOW_CLOSE_REQUESTED) {
21        SDL_Window* WindowToDestroy{SDL_GetWindowFromID(
22          E.window.windowID
23        )};
24        if (WindowToDestroy == Window1) {
25          Window1 = nullptr;
26        } else if (WindowToDestroy == Window2) {
27          Window2 = nullptr;
28        }
29        SDL_DestroyWindow(WindowToDestroy);
30      } else if (E.type == SDL_EVENT_QUIT) {
31        IsRunning = false;
32      }
33    }
34
35
36    if (Window1) {
37      // Render and update...
38    }
39
40    if (Window2) {
41      // Render and update...
42    }
43  }
44
45  SDL_Quit();
46  return 0;
47}

Disabling QUIT_ON_LAST_WINDOW_CLOSE

In some programs, we may want to keep our application running even if it currently has no windows. Perhaps we want to continue running in the background, and we may open a new window at some point in the future.

To prevent SDL from sending an SDL_EVENT_QUIT when the last window closes, we can set the SDL_HINT_QUIT_ON_LAST_WINDOW_CLOSE hint to "0":

1SDL_SetHint(
2  SDL_HINT_QUIT_ON_LAST_WINDOW_CLOSE,
3  "0"
4);

Alternatively, we can continue to allow the SDL_EVENT_QUIT to be sent, but change how we react to it based on conditional checks.

We don't necessarily need to end our application loop in receipt of such an event - we can choose what the most appropriate reaction should be based on the current situation.

Previously, we saw that when our program is managing a lot of objects, it can be helpful to introduce intermediate objects to hide that complexity.

Similarly, when our program manages multiple windows, creating a dedicated type to manage this can be helpful. This helps to remove logic from important parts of our code, such as the event loop and main function, thereby keeping them as clear as possible:

1#include <SDL3/SDL.h>
2#include "WindowManager.h"
3#include "UIManager.h"
4#include "WorldManager.h"
5
6int main(int, char**) {
7  // Initialization
8  SDL_Init(SDL_INIT_VIDEO);
9  UIManager UI;
10  WorldManager World;
11  WindowManager Windows;
12  Windows.CreateWindow();
13  Windows.CreateWindow();
14
15  // Event Handling
16  SDL_Event E;
17  bool IsRunning = true;
18  while (IsRunning ) {
19    while (SDL_PollEvent(&E)) {
20      World.HandleEvent(E);
21      UI.HandleEvent(E);
22      Windows.HandleEvent(E);
23      if (E.type == SDL_EVENT_QUIT) {
24        IsRunning = false;
25      }
26    }
27
28    // Ticking
29    World.Tick();
30    UI.Tick();
31    Windows.Tick();
32
33    // Rendering
34    Windows.Render();
35    World.Render();
36    UI.Render();
37    
38    // Buffer Swap
39    Windows.Update();
40  }
41  
42  SDL_Quit();
43  return 0;
44}

A starting implementation of a window manager might look something like this:

1#pragma once
2#include <iostream>
3#include <SDL3/SDL.h>
4#include <vector>
5
6class WindowManager {
7public:
8  WindowManager() = default;
9
10  void CreateWindow() {
11    SDL_Window* NewWindow{SDL_CreateWindow(
12      "Window", 200, 200, 0
13    )};
14    if (!NewWindow) {
15      std::cout << "Error creating window: "
16        << SDL_GetError();
17      return;
18    }
19    Windows.push_back(NewWindow);
20  }
21
22  void DestroyWindow(SDL_WindowID WindowID) {
23    std::erase_if(Windows, [WindowID](SDL_Window* Window) {
24      if (Window && SDL_GetWindowID(Window) == WindowID) {
25        SDL_DestroyWindow(Window);
26        return true;
27      }
28      return false;
29    });
30  }
31
32  void HandleEvent(SDL_Event& E) {
33    if (E.type == SDL_EVENT_WINDOW_CLOSE_REQUESTED) {
34      DestroyWindow(E.window.windowID);
35    }
36  }
37
38  void Tick() {
39    for (SDL_Window* Window : Windows) {
40      if (Window) {
41        // ...
42      }
43    }
44  }
45
46  void Render() {
47    for (SDL_Window* Window : Windows) {
48      if (Window) {
49        // ...
50      }
51    }
52  }
53
54  void Update() {
55    for (SDL_Window* Window : Windows) {
56      if (Window) {
57        // ...
58      }
59    }
60  }
61
62  WindowManager(const WindowManager&) = delete;
63  WindowManager& operator=(const WindowManager&) = delete;
64
65  ~WindowManager() {
66    for (SDL_Window* Window : Windows) {
67      if (Window) {
68        SDL_DestroyWindow(Window);
69      }
70    }
71  }
72
73private:
74  std::vector<SDL_Window*> Windows;
75};

Programs often support multiple windows to enhance user productivity by, for example, letting our program span across multiple monitors.

However, there is a more common scenario where we might create additional windows: to support UI elements that extend beyond the boundaries of our main window, such as tooltips or right-click menus:

SDL refers to these as Utility Windows. We can flag a window as a utility window through the SDL_WindowFlags. In SDL3, SDL_WINDOW_UTILITY is the primary flag for this purpose, replacing the older SDL_WINDOW_SKIP_TASKBAR flag.

Tooltip and Popup Menu Windows

For common UI elements like tooltips and menus, SDL3 provides dedicated flags: SDL_WINDOW_TOOLTIP and SDL_WINDOW_POPUP_MENU. A significant change from SDL2 is that these types of windows must now be created with a parent window.

This is done using SDL_CreatePopupWindow(), which takes the parent SDL_Window* as its first argument:

1SDL_Window* ParentWindow = SDL_CreateWindow(
2  "Primary Window", 600, 300, 0);
3
4// Create a popup menu attached to the parent
5SDL_Window* Popup = SDL_CreatePopupWindow(
6  ParentWindow,
7  100, 100, // Position relative to parent
8  200, 200, // Size
9  SDL_WINDOW_POPUP_MENU
10);

Using these specific flags helps SDL and the underlying platform manage the window's behavior appropriately. For example, a tooltip window can't grab input focus.

Combining Utility Windows with Other Flags

We often combine utility window flags with other flags to achieve the desired behavior. For example, a popup menu should typically be borderless and always-on-top:

1SDL_Window* Popup = SDL_CreatePopupWindow(
2  ParentWindow, 100, 100, 200, 200,
3  SDL_WINDOW_POPUP_MENU 
4  | SDL_WINDOW_BORDERLESS
5  | SDL_WINDOW_ALWAYS_ON_TOP
6);

In most programs, we also want utility windows to be initially hidden. We then later display the utility window based on user actions:

1// The utility window is initially hidden
2SDL_Window* Tooltip = SDL_CreatePopupWindow(
3  ParentWindow, 100, 100, 200, 50,
4  SDL_WINDOW_TOOLTIP | SDL_WINDOW_HIDDEN
5);
6
7// And later it becomes visible
8SDL_ShowWindow(Tooltip);

Let's use a utility window to create a dropdown menu that opens at the user's mouse position when they right-click. A performant approach is to create the window once and then show or hide it as needed.

Let's create a DropdownWindow class to manage this:

1#pragma once
2#include <SDL3/SDL.h>
3#include <iostream>
4
5class DropdownWindow {
6public:
7  DropdownWindow(SDL_Window* Parent) {
8    SDLWindow = SDL_CreatePopupWindow(
9      Parent, 100, 200, 120, 200,
10      SDL_WINDOW_POPUP_MENU |
11      SDL_WINDOW_ALWAYS_ON_TOP |
12      SDL_WINDOW_BORDERLESS |
13      SDL_WINDOW_HIDDEN
14    );
15
16    if (!SDLWindow) {
17      std::cout << SDL_GetError();
18    }
19  }
20
21  ~DropdownWindow() {
22    SDL_DestroyWindow(SDLWindow);
23  }
24
25  DropdownWindow(const DropdownWindow&) = delete;
26  DropdownWindow& operator=(const DropdownWindow&) = delete;
27
28  void Open() {
29    float MouseX, MouseY;
30    SDL_GetGlobalMouseState(&MouseX, &MouseY);
31
32    int ParentX, ParentY;
33    SDL_GetWindowPosition(
34      SDL_GetWindowParent(SDLWindow), &ParentX, &ParentY
35    );
36
37    int RelativeX{int(MouseX) - ParentX};
38    int RelativeY{int(MouseY) - ParentY};
39
40    SDL_SetWindowPosition(SDLWindow, RelativeX, RelativeY);
41    SDL_ShowWindow(SDLWindow);
42
43    isOpen = true;
44  }
45
46  void Close() {
47    SDL_HideWindow(SDLWindow);
48    isOpen = false;
49  }
50
51  void HandleEvent(const SDL_Event& Event) {
52    if (Event.type == SDL_EVENT_MOUSE_BUTTON_DOWN) {
53      if (Event.button.button == SDL_BUTTON_RIGHT) {
54        Open();
55      } else if (Event.button.button == SDL_BUTTON_LEFT) {
56        Close();
57      }
58    }
59  }
60
61  SDL_Surface* GetSurface() const {
62    return SDL_GetWindowSurface(SDLWindow);
63  }
64
65  void Render() {
66    if (!isOpen) return;
67    
68    const auto* Fmt = SDL_GetPixelFormatDetails(
69      GetSurface()->format
70    );
71    
72    SDL_FillSurfaceRect(
73      GetSurface(),
74      nullptr,
75      SDL_MapRGB(Fmt, nullptr, 50, 50, 255)
76    );
77  }
78
79  void Update() {
80    if (!isOpen) return;
81    SDL_UpdateWindowSurface(SDLWindow);
82  }
83
84private:
85  SDL_Window* SDLWindow{nullptr};
86  bool isOpen{false};
87};

This class combines many of the window management techniques we covered through the rest of this chapter. However, the Open() method has some new concepts:

1void Open() {
2  float MouseX, MouseY;
3  SDL_GetGlobalMouseState(&MouseX, &MouseY);
4
5  int ParentX, ParentY;
6  SDL_GetWindowPosition(
7    SDL_GetWindowParent(SDLWindow), &ParentX, &ParentY
8  );
9
10  int RelativeX{int(MouseX) - ParentX};
11  int RelativeY{int(MouseY) - ParentY};
12
13  SDL_SetWindowPosition(SDLWindow, RelativeX, RelativeY);
14  SDL_ShowWindow(SDLWindow);
15
16  isOpen = true;
17}

We want to open the dropdown menu next to the mouse, so we eventually want to use SDL_SetWindowPosition() to update the position of our DropdownMenu. However, we need to do some work to get the positional arguments for this function.

1. We use the SDL_GetGlobalMouseState() function to retrieve the mouse position. We cover this function, and mouse management more generally, later in the course.
2. When we're setting the position of a popup window, the positional arguments are relative to its parent, not the overall screen. So, we now need to get the parent window's position. We do this by calling SDL_GetWindowParent(), and passing it to SDL_GetWindowPosition().
3. Finally, we use our global mouse position and parent window position to calculate the mouse's position relative to the parent window. We then use this to update the position of our popup window.

In many use cases, this logic could be simplified by controlling how mouse focus is handled. We'll cover this in chapter dedicated to mouse handling later in the course.

Creating a DropdownWindow

In our main function, we can now create a DropdownWindow and pass it our main GameWindow's raw pointer:

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include "Window.h"
4#include "Dropdown.h"
5
6int main(int, char**) {
7  SDL_Init(SDL_INIT_VIDEO);
8  Window GameWindow;
9  DropdownWindow Menu(GameWindow.GetRaw());
10
11  SDL_Event E;
12  bool IsRunning = true;
13  while (IsRunning) {
14    while (SDL_PollEvent(&E)) {
15      Menu.HandleEvent(E);
16      if (E.type == SDL_EVENT_QUIT) {
17        IsRunning = false;
18      }
19    }
20    GameWindow.Render();
21    GameWindow.Update();
22    Menu.Render();
23    Menu.Update();
24  }
25
26  SDL_Quit();
27  return 0;
28}

Right-clicking in our program will now open a dropdown menu. Because the dropdown is a standalone window, it can extend beyond the boundaries of our primary window, similar to the behavior we're familiar with from other programs:

In this lesson, we explored techniques for managing multiple windows, including creating, destroying, and handling events for them.

We introduced the concept of utility windows, such as tooltips and dropdown menus, and demonstrated how to use window flags and SDL_CreatePopupWindow() for specialized behaviors.

Key Takeaways:

• SDL3 supports multiple windows via SDL_CreateWindow() and SDL_CreatePopupWindow().
• Utility windows must be created with a parent window in SDL3.
• Managing multiple windows often involves using identifiers like windowID and adding helper classes like WindowManager.
• Utility windows are often hidden instead of destroyed for performance reasons.
• Event handling can identify specific windows using SDL_GetWindowFromID().
• The SDL_EVENT_WINDOW_CLOSE_REQUESTED event lets you handle window closures.