Window Titles

In this lesson, we'll explore how to control window titles in SDL2 dynamically. We’ll cover how to set, update, and retrieve titles to provide a polished user experience.

As we’ve seen previously, the first argument to SDL_CreateWindow is a string, representing what we want the title to be. Below, we create a window whose title is "Sample Window":

1SDL_CreateWindow(
2  "Sample Window",
3  100, 100, 700, 300, 0
4);

SDL_SetWindowTitle()

We can change the title of an existing window using the SDL_SetWindowTitle() function. We pass the SDL_Window pointer for the window we want to update, and the new title we want it to use:

1SDL_SetWindowTitle(WindowPointer, "New Title");

SDL_GetWindowTitle()

We can get a window’s current title by passing its SDL_Window* to the SDL_GetWindowTitle() function:

1std::cout << SDL_GetWindowTitle(WindowPointer);

1New Title

Example

In this example, we’ll update the window title depending on whether or not the window has input focus.

We’ll initialize the window with focus, and then monitor SDL_WindowEvent events to update the title when the window gains and loses focus through the lifecycle of our program:

1#include <SDL.h>
2#include "Window.h"
3
4void HandleWindowEvent(
5  SDL_WindowEvent& E,
6  SDL_Window* Window
7) {
8  if (
9    E.event == SDL_WINDOWEVENT_FOCUS_LOST
10  ) {
11    SDL_SetWindowTitle(
12      Window, "My Program (Inactive)"
13    );
14  } else if (
15    E.event == SDL_WINDOWEVENT_FOCUS_GAINED
16  ) {
17    SDL_SetWindowTitle(
18      Window,  "My Program (Active)"
19    );
20  }
21}
22
23int main(int argc, char** argv) {
24  SDL_Init(SDL_INIT_VIDEO);
25  Window GameWindow;
26  SDL_Event E;
27
28  while (true) {
29    while (SDL_PollEvent(&E)) {
30      if (E.type == SDL_WINDOWEVENT) {
31        HandleWindowEvent(
32          E.window, GameWindow.SDLWindow
33        );
34      } else if (E.type == SDL_QUIT) {
35        SDL_Quit();
36        return 0;
37      }
38    }
39
40    GameWindow.Update();
41    GameWindow.Render();
42  }
43}

In the previous example, we passed the SDL_Window* to the event handler as an argument, but we can alternatively retrieve it from the event itself.

Most event types, including SDL_WindowEvent, include a windowID member that identifies the corresponding window. We can get the SDL_Window* associated with this ID by passing it to SDL_GetWindowFromID():

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

String Types: char* and std::string

SDL uses the char* data type to represent strings. Any SDL function that accepts a string argument or returns a string value is likely to be using this char* type. This includes the functions for managing window titles:

1// SDL_GetWindowTitle returns a char*
2const char* CurrentTitle{SDL_GetWindowTitle(Window)};
3
4// SDL_SetWindowTitle accepts a char*
5char* NewTitle{"New Title"};
6SDL_SetWindowTitle(Window, NewTitle);

A char* is a primitive way to represent strings, originating from the early days of the C language. For this reason, they are often referred to as C-style strings.

In modern programs, we typically prefer working with friendlier types, such as the C++ standard library’s std::string. This type offers useful capabilities in the form of member functions and overloaded operators:

1// Get the number of characters in a std::string
2// using the length() member function
3std::string SomeString{"Hello"};
4std::cout << "String Length: " << SomeString.length();
5
6// Compare two standard strings using the
7// overloaded == operator
8std::string Other{"Hello"};
9if (MyString == OtherString) {
10  std::cout << "\nStrings are the same";
11}

char* and std::string Interopability

To use std::string in our code, we need to be able to switch to and from the char* type when interacting with SDL’s API. The std::string type can help us with this.

When we have a std::string and need to get the corresponding char* to send to SDL, we can use the c_str() method. Let’s update our Window class with a SetTitle() method that accepts a std::string, and uses its c_str() method to update the SDL window’s title:

1#include <SDL.h>
2#include <string>
3
4class Window {
5public:
6  // ...
7  void SetTitle(const std::string& NewTitle) {
8    SDL_SetWindowTitle(SDLWindow,
9      NewTitle.c_str());
10  }
11  // ...
12
13private:
14  SDL_Window* SDLWindow{nullptr};
15  // ...
16}

Going in the opposite direction is even easier. The std::string type includes constructors and an = operator that accepts a char*.

So, when SDL returns a char*, we can directly use it to create or update a std::string:

1#include <SDL.h>
2#include <string>
3
4class Window {
5public:
6  // ...
7  std::string GetTitle() {
8    return SDL_GetWindowTitle(SDLWindow)
9  }
10  // ...
11
12private:
13  SDL_Window* SDLWindow{nullptr};
14  // ...
15}

Our C++ course has a full chapter on string data types and advanced techniques for working with text, starting with how individual characters are represented digitally:

Characters, Unicode and Encoding

An introduction to C++ character types, the Unicode standard, character encoding, and C-style strings

Summary

This lesson covered managing window titles with SDL2. You now know how to set, retrieve, and dynamically update titles. Key Takeaways:

• SDL_SetWindowTitle() updates titles during runtime.
• SDL_GetWindowTitle() retrieves the current title.
• Interfacing between std::string and char* improves modern C++ compatibility.

Next Lesson

Window Opacity

Discover how to use SDL2 functions for controlling and retrieving window transparency settings.

ContinueView Course