Window Titles
Learn how to set, get, and update window titles dynamically
In this lesson, we'll explore how to control window titles in SDL3 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":
SDL_CreateWindow(
"Sample Window",
700, 300, 0
);Starting Point
This lesson builds on our earlier work. A minimal project containing a Window class and a main function with a basic application loop is provided below if you want to follow along.
We've removed the border-specific logic from the previous lesson to keep the code focused on this lesson's topic.
Files
Setting Titles Using 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:
SDL_SetWindowTitle(WindowPointer, "New Title");Retrieving Titles Using SDL_GetWindowTitle()
We can get a window's current title by passing its SDL_Window* to the SDL_GetWindowTitle() function:
std::cout << SDL_GetWindowTitle(WindowPointer);New TitleExample: Changing Title on Input Focus
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 for SDL_EVENT_WINDOW_FOCUS_GAINED and SDL_EVENT_WINDOW_FOCUS_LOST events to update the title as the window's focus state changes throughout the program's lifecycle:
src/main.cpp
#include <SDL3/SDL.h>
#include <SDL3/SDL_main.h>
#include "Window.h"
void HandleWindowEvent(
const SDL_WindowEvent& E,
Window& GameWindow
) {
if (E.type == SDL_EVENT_WINDOW_FOCUS_LOST) {
SDL_SetWindowTitle(
GameWindow.GetRaw(), "My Program (Inactive)"
);
} else if (E.type == SDL_EVENT_WINDOW_FOCUS_GAINED) {
SDL_SetWindowTitle(
GameWindow.GetRaw(), "My Program (Active)"
);
}
}
int main(int, char**) {
SDL_Init(SDL_INIT_VIDEO);
Window GameWindow;
SDL_Event E;
bool IsRunning = true;
while (IsRunning) {
while (SDL_PollEvent(&E)) {
if (E.type >= SDL_EVENT_WINDOW_FIRST &&
E.type <= SDL_EVENT_WINDOW_LAST) {
HandleWindowEvent(E.window, GameWindow);
} else if (E.type == SDL_EVENT_QUIT) {
IsRunning = false;
}
}
GameWindow.Render();
GameWindow.Update();
}
SDL_Quit();
return 0;
}In the previous example, we passed the Window object to the event handler as an argument, but we can alternatively retrieve the SDL_Window* from the event itself. We covered this in more detail in our lesson on .
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():
void HandleWindowEvent(const SDL_WindowEvent& E) {
SDL_Window* Window{SDL_GetWindowFromID(
E.windowID
)};
// ...
}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:
// SDL_GetWindowTitle returns a char*
const char* CurrentTitle{SDL_GetWindowTitle(Window)};
// SDL_SetWindowTitle accepts a char*
const char* NewTitle{"New Title"};
SDL_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:
// Get the number of characters in a std::string
// using the length() member function
std::string SomeString{"Hello"};
std::cout << "String Length: " << SomeString.length();
// Compare two standard strings using the
// overloaded == operator
std::string Other{"Hello"};
if (SomeString == Other) {
std::cout << "\nStrings are the same";
}Interoperability Between char* and std::string
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:
src/Window.h
#pragma once
#include <SDL3/SDL.h>
#include <string>
class Window {
public:
//...
void SetTitle(const std::string& NewTitle) {
SDL_SetWindowTitle(SDLWindow, NewTitle.c_str());
}
//...
private:
SDL_Window* SDLWindow{nullptr};
};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:
src/Window.h
#pragma once
#include <SDL3/SDL.h>
#include <string>
class Window {
public:
//...
std::string GetTitle() const {
return SDL_GetWindowTitle(SDLWindow);
}
//...
private:
SDL_Window* SDLWindow{nullptr};
};Our C++ course has a full chapter on string data types and advanced techniques for working with text, starting with .
Summary
This lesson covered managing window titles. You now know how to set, retrieve, and dynamically update titles. Here are the key points:
SDL_SetWindowTitle()updates titles during runtime.SDL_GetWindowTitle()retrieves the current title.- Interfacing between
std::stringandchar*improves modern C++ compatibility.
Window Opacity
Discover how to use SDL3 functions for controlling and retrieving window transparency settings.