Multiple Windows and Utility Windows

In this lesson, we’ll explore how to manage multiple windows using SDL2. We’ll also introduce one of the primary use cases for these techniques, which is creating menus and tooltips.

As we might expect, our program can manage multiple windows by performing multiple invocations to SDL_CreateWindow():

1#include <SDL.h>
2#include "Window.h"
3
4int main(int argc, char** argv) {
5  SDL_Init(SDL_INIT_VIDEO);
6  Window GameWindow1;
7  Window GameWindow2;
8  
9  SDL_Event E;
10  while (true) {
11    while (SDL_PollEvent(&E)) {
12      if (E.type == SDL_QUIT) {
13        SDL_Quit();
14        return 0;
15      }
16    }
17
18    GameWindow1.Update();
19    GameWindow2.Update();
20    
21    GameWindow1.Render();
22    GameWindow2.Render();
23  }
24}

Our windows do not need to be created at the same time. We can open additional windows in response to user events. Below, our program opens a second window when the user presses their space bar, and closes it when they press escape:

1#include <SDL.h>
2#include "Window.h"
3
4SDL_Window* ExtraWindow{nullptr};
5
6void HandleKeyboardEvent(SDL_KeyboardEvent& E) {
7  if (E.keysym.sym == SDLK_SPACE && !ExtraWindow) {
8    ExtraWindow = SDL_CreateWindow(
9      "Extra Window", 100, 200, 300, 400, 0);
10  } else if (E.keysym.sym == SDLK_ESCAPE) {
11    SDL_DestroyWindow(ExtraWindow);
12    ExtraWindow = nullptr;
13  }
14}
15
16int main(int argc, char** argv) {
17  SDL_Init(SDL_INIT_VIDEO);
18  Window GameWindow;
19  SDL_Event E;
20
21  while (true) {
22    while (SDL_PollEvent(&E)) {
23      if (E.type == SDL_KEYDOWN) {
24        HandleKeyboardEvent(E.key);
25      } else if (E.type == SDL_QUIT) {
26        SDL_Quit();
27        return 0;
28      }
29    }
30
31    GameWindow.Update();
32    GameWindow.Render();
33  }
34}

Events and Window IDs

When our program is managing multiple windows, it is often helpful to understand which window is associated with an event that shows up in our event loop.

To help with this, most SDL event types, such as SDL_MouseButtonEvent and SDL_WindowEvent, include a windowID member.

This is a basic integer variable that SDL uses to uniquely identify each window. We can get the SDL_Window pointer corresponding to a window ID by passing it to the SDL_GetWindowFromID() function:

1void HandleWindowEvent(SDL_WindowEvent& E) {
2  SDL_Window* EventWindow{
3    SDL_GetWindowFromID(E.windowID)};
4  // ...
5}

This technique becomes increasingly important when our program is managing multiple windows, as it is the primary way we identify which window is associated with an event:

1#include <SDL.h>
2
3void HandleWindowEvent(SDL_WindowEvent& E) {
4  if (E.event != SDL_WINDOWEVENT_ENTER) return;
5
6  SDL_Window* EventWindow{
7    SDL_GetWindowFromID(E.windowID)};
8
9  std::cout << "\nMouse entered "
10    << SDL_GetWindowTitle(EventWindow);
11}
12
13int main(int argc, char** argv) {
14  SDL_Init(SDL_INIT_VIDEO);
15  SDL_CreateWindow(
16    "Window 1", 100, 200, 100, 100, 0);
17  SDL_CreateWindow(
18    "Window 2", 300, 200, 100, 100, 0);
19
20  SDL_Event E;
21  while (true) {
22    while (SDL_PollEvent(&E)) {
23      if (E.type == SDL_WINDOWEVENT) {
24        HandleWindowEvent(E.window);
25      } else if (E.type == SDL_QUIT) {
26        SDL_Quit();
27        return 0;
28      }
29    }
30  }
31}

1Mouse entered Window 1
2Mouse entered Window 2
3Mouse entered Window 1

We covered window events and window IDs in more detail in a dedicated lesson earlier in the course:

Window Events and Window IDs

Discover how to monitor and respond to window state changes in SDL applications

Creating a Window Manager

Previously, we saw when our program is managing a lot of objects, it can be helpful to introduce intermediate objects to manage that complexity. This might include a UIManager for managing interface elements and a WorldMananger for managing objects being simulated in our world.

Similarly, when our program manages multiple windows, creating a dedicated type to manage this complexity 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 <SDL.h>
2#include "WindowManager.h"
3#include "UIManager.h"
4#include "WorldManager.h"
5
6int main(int argc, char** argv) {
7  // Initialization
8  SDL_Init(SDL_INIT_VIDEO);
9  WindowManager Windows;
10  UIManager UI;
11  WorldManager World;
12  Windows.CreateWindow();
13  Windows.CreateWindow();
14  Windows.CreateWindow();
15  
16  // Event Handling
17  SDL_Event E;
18  while (true) {
19    while (SDL_PollEvent(&E)) {
20      World.HandleEvent(E);
21      UI.HandleEvent(E);
22      Windows.HandleEvent(E);
23      if (E.type == SDL_QUIT) {
24        SDL_Quit();
25        return 0;
26      }
27    }
28    
29    // Ticking
30    World.Tick();
31    UI.Tick();
32    Windows.Tick();
33    
34    // Rendering
35    World.Render();
36    UI.Render();
37    Windows.Render();
38  }
39}

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

1// WindowManager.h
2#pragma once
3#include <iostream>
4#include <SDL.h>
5#include <unordered_map>
6
7class WindowManager {
8public:
9  WindowManager() = default;
10
11  Uint32 CreateWindow() {
12    SDL_Window* NewWindow{
13      SDL_CreateWindow(
14        "Window", 100, 100, 200, 200, 0)};
15
16    if (!NewWindow) {
17      std::cout << "Error creating window: "
18        << SDL_GetError();
19      return 0;
20    }
21
22    Uint32 WindowID{SDL_GetWindowID(NewWindow)};
23    Windows[WindowID] = NewWindow;
24    return WindowID;
25  }
26
27  void DestroyWindow(Uint32 WindowID) {
28    if (Windows[WindowID]) {
29      SDL_DestroyWindow(Windows[WindowID]);
30      Windows.erase(WindowID);
31    }
32  }
33
34  void HandleEvent(SDL_Event& E) {
35    // ...
36  }
37
38  void Tick() {
39    // ...
40  }
41
42  void Render() {
43    // ...
44  }
45  
46  // Prevent copying of WindowManager objects
47  WindowManager(const WindowManager&) = delete;
48  WindowManager& operator=(const WindowManager&) = delete;
49
50  ~WindowManager() {
51    for (auto [id, Window] : Windows) {
52      if (Window) { SDL_DestroyWindow(Window); }
53    }
54  }
55
56private:
57  std::unordered_map<Uint32, SDL_Window*> Windows;
58};

Utility Windows

Programs often support multiple windows to enhance user productivity, particularly in software with complex, customizable UIs. Managing multiple windows allows users to organize their workspaces freely, leveraging features like multi-monitor setups for greater flexibility.

However, there is a subtle and more common scenario where our program should consider creating additional windows. This is to support UI elements that may need to extend beyond the boundaries of our main window.

This is common for elements that are expected to be near the user’s cursor, such as tooltips or right-click menus:

We may not consider these elements to be windows at all, but this is typically how they’re implemented. The SDL API calls these Utility Windows. We can flag a window as a utility window through the SDL_WindowFlags:

1SDL_CreateWindow(
2  "Primary Window", 100, 100, 200, 200, 0);
3
4SDL_CreateWindow(
5  "Utility Window", 100, 100, 200, 200,
6  SDL_WINDOW_UTILITY
7);

Utility windows share the same capabilities as regular windows. The reason we flag them as utility windows is so the underlying platform understands they’re secondary, supporting windows, and can handle and style them appropriately.

Tooltip and Popup Menu Window Flags

The use-case for utility windows being used to create tooltips and popup menus is so common that SDL includes dedicated window flags for them: SDL_WINDOW_TOOLTIP and SDL_WINDOW_POPUP_MENU

Using these flags to explain the intent of our window can help SDL manage them more effectively. For example, a tooltip window can’t grab input focus or be minimized:

1SDL_CreateWindow(
2  "Utility Window", 100, 100, 200, 200,
3  SDL_WINDOW_TOOLTIP
4);
5
6SDL_CreateWindow(
7  "Utility Window", 100, 100, 200, 200,
8  SDL_WINDOW_DROPDOWN
9);

Combining Utility Windows with Other Flags

When creating a utility window, we often combine it with other window flags to create behaviors that are appropriate to our use case. For example, we often do not want a utility window to be included in the user’s taskbar.

To do this, we can combine the SDL_WINDOW_UTILITY flag with SDL_WINDOW_SKIP_TASKBAR:

1SDL_CreateWindow(
2  "Utility Window", 100, 100, 200, 200,
3  SDL_WINDOW_UTILITY | SDL_WINDOW_SKIP_TASKBAR
4);

It’s also common that we would want utility windows to be borderless and/or always-on-top:

1SDL_CreateWindow(
2  "Utility Window", 100, 100, 200, 200,
3  SDL_WINDOW_UTILITY | SDL_WINDOW_BORDERLESS
4);
5
6SDL_CreateWindow(
7  "Utility Window", 100, 100, 200, 200,
8  SDL_WINDOW_UTILITY | SDL_WINDOW_ALWAYS_ON_TOP
9);

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* Window{SDL_CreateWindow(
3  "Utility Window", 100, 100, 200, 200,
4  SDL_WINDOW_UTILITY | SDL_WINDOW_HIDDEN
5)};
6
7// And later it becomes visible
8SDL_ShowWindow(UtilityWindow);

Example: Dropdown Menu

Let’s use a utility window to create the basic foundations of a dropdown menu that opens at the user’s mouse position when they right-click. There are two main ways we can approach this:

1. Create a dropdown window when the user opens the menu, and destroy it when they’re done
2. Keep a dropdown window alive, and switch it between being shown and hidden as appropriate

The first option can be problematic for performance reasons. Creating a window and getting everything in place to start rendering its contents can be an expensive process. We don’t want to incur that cost at the exact moment the user is performing an interaction, as it can make our program feel less responsive.

The second option is usually preferred in most situations. Let’s create a basic class that implements the showing and hiding approach:

1// Dropdown.h
2#pragma once
3#include <SDL.h>
4#include <iostream>
5
6class DropdownWindow {
7public:
8  DropdownWindow() {
9    SDLWindow = SDL_CreateWindow(
10      "Dropdown", 100, 200, 120, 200,
11      SDL_WINDOW_POPUP_MENU |
12      SDL_WINDOW_ALWAYS_ON_TOP |
13      SDL_WINDOW_SKIP_TASKBAR |
14      SDL_WINDOW_BORDERLESS |
15      SDL_WINDOW_HIDDEN);
16
17    if (!SDLWindow) {
18      std::cout << SDL_GetError();
19    }
20  }
21
22  ~DropdownWindow() {
23    SDL_DestroyWindow(SDLWindow);
24  }
25
26  DropdownWindow(const DropdownWindow&) = delete;
27  DropdownWindow& operator=(
28    const DropdownWindow&) = delete;
29
30  void Open() {
31    // Get the mouse position
32    int x, y;
33    SDL_GetGlobalMouseState(&x, &y);
34    
35    // Move the window next to the mouse and show it
36    SDL_SetWindowPosition(SDLWindow, x, y);
37    SDL_ShowWindow(SDLWindow);
38    
39    isOpen = true;
40    
41    // Enable mouse button events for clicks that
42    // change input focus
43    SDL_SetHint(
44      SDL_HINT_MOUSE_FOCUS_CLICKTHROUGH, "1");
45  }
46
47  void Close() {
48    SDL_HideWindow(SDLWindow);
49    isOpen = false;
50    
51    // Disable mouse button events for clicks that
52    // change input focus
53    SDL_SetHint(
54      SDL_HINT_MOUSE_FOCUS_CLICKTHROUGH, "0");
55  }
56
57  void HandleEvent(SDL_Event& Event) {
58    if (Event.type == SDL_MOUSEBUTTONDOWN) {
59      SDL_MouseButtonEvent E{Event.button};
60      if (E.button == SDL_BUTTON_RIGHT) {
61        Open();
62      } else if (E.button == SDL_BUTTON_LEFT) {
63        Close();
64      }
65    }
66  }
67
68  SDL_Surface* GetSurface() {
69    return SDL_GetWindowSurface(SDLWindow);
70  }
71
72  void Render() {
73    if (!isOpen) return;
74    SDL_FillRect(
75      GetSurface(), nullptr, SDL_MapRGB(
76        GetSurface()->format, 150, 50, 50
77      )
78    );
79  }
80
81  void Update() {
82    if (!isOpen) return;
83    SDL_UpdateWindowSurface(SDLWindow);
84  }
85
86  SDL_Window* SDLWindow;
87
88private:
89  bool isOpen{false};
90};

This class uses some more advanced mouse techniques than we’ve covered so far, including the SDL_GetGlobalMouseState() function and SDL_HINT_MOUSE_FOCUS_CLICKTHROUGH hint. We cover these in more detail in our dedicated mouse management chapter later in the course.

In our main function, we can create a DropdownWindow and connect it to our application and event loops in the usual way:

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

Right-clicking in our program will now open a dropdown menu. And, because the dropdown menu is a standalone window, it can expand beyond the boundaries of our primary window:

Summary

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

We introduced the concept of utility windows, such as tooltips and dropdown menus, and demonstrated how to leverage SDL’s window flags for specialized behaviors.

Additionally, we implemented a WindowManager class to simplify window management and created a dropdown menu system as a practical example of using utility windows.

Key Takeaways

• SDL2 supports multiple windows via SDL_CreateWindow().
• Utility windows (e.g., tooltips, dropdown menus) are created with specific window flags like SDL_WINDOW_TOOLTIP.
• Managing multiple windows efficiently involves using identifiers like windowID and helper classes like WindowManager.
• Utility windows are often hidden instead of destroyed for performance reasons.
• Event handling can identify specific windows using SDL_GetWindowFromID().

Next Lesson

Video Displays

Learn how to handle multiple monitors in SDL, including creating windows on specific displays.

ContinueView Course