Get Started for Free

Learn C++ and SDL development by creating hands on, practical projects inspired by classic retro games

Game Dev with SDL2





<Excerpt>


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


```c++
SDL_CreateWindow(
  "Sample Window",//<h>
  100, 100, 700, 300, 0
);
```


</Excerpt>


## `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:


```c++
SDL_SetWindowTitle(WindowPointer, "New Title");
```


## `SDL_GetWindowTitle()`


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


```c++
std::cout << SDL_GetWindowTitle(WindowPointer);
```


```c++
//<o>
New 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:


```c++
#include <SDL.h>
#include "Window.h"

void HandleWindowEvent(
  SDL_WindowEvent& E,
  SDL_Window* Window
) {
  if (
    E.event == SDL_WINDOWEVENT_FOCUS_LOST
  ) {
    SDL_SetWindowTitle(//<h>
      Window, "My Program (Inactive)"//<h>
    );//<h>
  } else if (
    E.event == SDL_WINDOWEVENT_FOCUS_GAINED
  ) {
    SDL_SetWindowTitle(//<h>
      Window,  "My Program (Active)"//<h>
    );//<h>
  }
}

int main(int argc, char** argv) {
  SDL_Init(SDL_INIT_VIDEO);
  Window GameWindow;
  SDL_Event E;

  while (true) {
    while (SDL_PollEvent(&E)) {
      if (E.type == SDL_WINDOWEVENT) {
        HandleWindowEvent(//<h>
          E.window, GameWindow.SDLWindow//<h>
        );//<h>
      } else if (E.type == SDL_QUIT) {
        SDL_Quit();
        return 0;
      }
    }

    GameWindow.Update();
    GameWindow.Render();
  }
}
```


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()`:


```c++
void HandleWindowEvent(SDL_WindowEvent& E) {
  SDL_Window* Window{SDL_GetWindowFromID(//<h>
    E.windowID//<h>
  )};//<h>
  // ...
}
```


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


```c++
// SDL_GetWindowTitle returns a char*
const char* CurrentTitle{SDL_GetWindowTitle(Window)};

// SDL_SetWindowTitle accepts a char*
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:


```c++
// 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 (MyString == OtherString) {
  std::cout << "\nStrings are the same";
}
```


### `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:


```c++
#include <SDL.h>
#include <string>

class Window {
public:
  // ...
  void SetTitle(const std::string& NewTitle) {
    SDL_SetWindowTitle(SDLWindow,
      NewTitle.c_str());//<h>
  }
  // ...

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


```c++
#include <SDL.h>
#include <string>

class Window {
public:
  // ...
  std::string GetTitle() {//<h>
    return SDL_GetWindowTitle(SDLWindow)//<h>
  }//<h>
  // ...

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 how individual characters are represented digitally:


<LessonPromo slug=”character-encoding” />


## 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.

<FAQ>


```javascript
//<m>
{
  slug: 'sdl-setwindowtitle-usecase',
  title: 'Use of `SDL_SetWindowTitle()`',
  question: 'What practical use cases are there for changing the window title during runtime?',
}
```


Changing the window title at runtime can provide useful feedback to users or developers and improve the experience of your application. Here are a few practical scenarios:


### Debugging


During development, you might display diagnostic information in the window title. For example, you can show the current frames per second (FPS) or debug messages without cluttering the game window.


```c++
void UpdateWindowTitle(
  SDL_Window* window, int fps
) {
  std::string title = "Game - FPS: "
    + std::to_string(fps);
  SDL_SetWindowTitle(
    window, title.c_str());
}
```


### User Feedback


You can use the title to convey important information, like the player’s score, the current level, or game state changes. For instance:


```c++
void SetGameOverTitle(SDL_Window* window) {
  SDL_SetWindowTitle(window,
    "Game Over - Thanks for Playing!");
}
```


### Multi-Window Applications


If your application uses multiple windows, dynamic titles can help users distinguish between them. For example, a level editor might display the name of the level currently being edited.


```c++
void SetWindowTitle(
  SDL_Window* window,
  const std::string& levelName
) {
  SDL_SetWindowTitle(
    window,
    ("Editing: " + levelName).c_str()
  );
}
```


### Localization


You can update the title dynamically to match the user’s language preference:


```c++
void SetLocalizedTitle(
  SDL_Window* window,
  const std::string& language
) {
  if (language == "en") {
    SDL_SetWindowTitle(window, "Game");
  } else if (language == "es") {
    SDL_SetWindowTitle(window, "Juego");
  }
}
```


Dynamic window titles add polish to your application and can greatly enhance usability.


</FAQ>


<FAQ>


```javascript
//<m>
{
  slug: "unicode-in-sdl-window-titles",
  title: "Using Unicode in SDL Titles",
  question: "Can I use Unicode characters in a window title?",
}
```


Yes, you can use Unicode characters in a window title, but there are some caveats to keep in mind. SDL2 natively supports UTF-8 encoding, which means you can include Unicode characters in strings passed to `SDL_SetWindowTitle()` or `SDL_CreateWindow()`.


However, the proper display of these characters depends on your system's font and encoding support.


### Example: Setting a Unicode Title


Here’s an example of how you can set a window title with Unicode characters:


```c++
#include <SDL.h>
#include <string>

int main(int, char**) {
  SDL_Init(SDL_INIT_VIDEO);

  // Convert the UTF-8 string to a const char*
  const char* title = reinterpret_cast<const
    char*>(u8"🌟 My Game 🎮");

  SDL_Window* window =
    SDL_CreateWindow(title,
                     SDL_WINDOWPOS_CENTERED,
                     SDL_WINDOWPOS_CENTERED,
                     800, 600,
                     SDL_WINDOW_SHOWN);

  // Keep the window open for 3 seconds
  SDL_Delay(3000);
  SDL_DestroyWindow(window);
  SDL_Quit();

  return 0;
}
```


```c++
//<o>
The window title will display "🌟 My Game 🎮" if your system supports the emojis and UTF-8.
```


### Common Issues

1. **System Limitations**: Some operating systems may not support certain Unicode characters in window titles, especially emojis or non-Latin scripts. In such cases, you may see placeholders (like `?`) or missing characters.
2. **Font Support**: If the system’s default font doesn’t include the characters you’re using, they won’t render correctly.
3. **Encoding Errors**: Ensure your source file is saved with UTF-8 encoding and that string literals include the `u8` prefix for compatibility.

Using Unicode can improve localization and user experience, but always test your titles on the platforms you target.


</FAQ>
<FAQ>


```javascript
//<m>
{
  slug: "localizing-sdl-window-titles",
  title: "Localizing SDL Titles",
  question: "How do I localize window titles for different languages?",
}
```


Localizing window titles involves dynamically changing the text based on the user’s preferred language. SDL doesn’t provide built-in localization, so you’ll need to handle this in your application by using a translation system or resource files.


### Example: Simple Localization with a Map


A straightforward way to localize window titles is by mapping language codes to translations:


```c++
#include <SDL.h>
#include <map>
#include <string>

std::string GetLocalizedTitle(
  const std::string& lang) {
  static std::map<std::string, std::string>
    translations{
      {"en", "Welcome to My Game"},
      {"es", "Bienvenido a Mi Juego"},
      {"fr", "Bienvenue dans Mon Jeu"}};
  return translations.count(lang)
           ? translations[lang]
           : translations["en"];
}

int main() {
  SDL_Init(SDL_INIT_VIDEO);

  // User's preferred language
  std::string lang = "es";

  std::string title = GetLocalizedTitle(lang);

  SDL_Window* window =
    SDL_CreateWindow(title.c_str(),
                     SDL_WINDOWPOS_CENTERED,
                     SDL_WINDOWPOS_CENTERED,
                     800, 600,
                     SDL_WINDOW_SHOWN);

  // Keep the window open for 3 seconds
  SDL_Delay(3000);

  SDL_DestroyWindow(window);
  SDL_Quit();
}
```


```c++
//<o>
The window title will display "Bienvenido a Mi Juego" if "es" is the language.
```


### Best Practices

- **Use External Files**: Store translations in a file (e.g., JSON, XML) to make updates easier.
- **Default Language**: Always fall back to a default language (like English) if the preferred language isn’t supported.
- **Testing**: Test your titles in various languages, especially those with special characters, like Japanese or Arabic.

This approach ensures your window titles enhance the user experience for diverse audiences.


</FAQ>
<FAQ>


```javascript
//<m>
{
  slug: "styling-sdl-window-titles",
  title: "Styling SDL Titles",
  question: "Is it possible to style the window title (e.g., bold text)?",
}
```


Unfortunately, SDL does not support styling window titles. The title displayed in a window's border is entirely controlled by the operating system’s window manager. This means you cannot apply styles like bold, italic, or color changes.


### Workarounds for Styled Titles


If you need styled text, consider displaying it inside the window itself, rather than relying on the title bar. Use SDL rendering or a library like SDL_ttf for custom text rendering.


```c++
#include <SDL.h>
#include <SDL_ttf.h>
#include <string>

int main() {
  SDL_Init(SDL_INIT_VIDEO);
  TTF_Init();

  SDL_Window* window = SDL_CreateWindow(
    "Styled Title Example",
    SDL_WINDOWPOS_CENTERED,
    SDL_WINDOWPOS_CENTERED,
    800,
    600,
    SDL_WINDOW_SHOWN
  );

  SDL_Renderer* renderer = SDL_CreateRenderer(
    window, -1, SDL_RENDERER_ACCELERATED);
  TTF_Font* font =
    TTF_OpenFont("Arial.ttf", 24);
    
  // White text
  SDL_Color color = {255, 255, 255, 255};
  
  SDL_Surface* surface = TTF_RenderText_Blended(
    font, "Bold Title Inside Window", color);
    
  SDL_Texture* texture =
    SDL_CreateTextureFromSurface(
      renderer, surface);

  SDL_Rect dst = {
    200, 250, surface->w, surface->h};
  SDL_FreeSurface(surface);

  SDL_RenderClear(renderer);
  SDL_RenderCopy(renderer, texture, nullptr,
                 &dst);
  SDL_RenderPresent(renderer);

  SDL_Delay(3000);
  SDL_DestroyTexture(texture);
  TTF_CloseFont(font);
  SDL_DestroyRenderer(renderer);
  SDL_DestroyWindow(window);

  TTF_Quit();
  SDL_Quit();
}
```


```c++
//<o>
Displays "Bold Title Inside Window" rendered in the window.
```


For styling, always work within your window’s content area.


</FAQ>
<FAQ>


```javascript
//<m>
{
  slug: "dynamic-sdl-window-titles",
  title: "Dynamic Titles in SDL",
  question: "Can I make the title reflect real-time data, like a countdown timer?",
}
```


Yes, you can update the window title dynamically during runtime to reflect real-time data like a countdown timer. Use `SDL_SetWindowTitle()` inside your game or application’s main loop to change the title.


In this example, we maintain a countdown timer in the title:


```c++
#include <SDL.h>
#include <string>
#include <chrono>
#include <thread>

int main() {
  SDL_Init(SDL_INIT_VIDEO);

  SDL_Window* window = SDL_CreateWindow(
    "Timer Example",
    SDL_WINDOWPOS_CENTERED,
    SDL_WINDOWPOS_CENTERED,
    800,
    600,
    SDL_WINDOW_SHOWN
  );

  for (int i = 10; i >= 0; --i) {
    std::string title = "Time Remaining: "
      + std::to_string(i) + " seconds";
    SDL_SetWindowTitle(window, title.c_str());
    std::this_thread::sleep_for(
      std::chrono::seconds(1));
  }

  SDL_DestroyWindow(window);
  SDL_Quit();
}
```


```c++
//<o>
The title updates every second to show the countdown.
```


Dynamic updates are useful for showing scores, FPS, or debugging data during development.


</FAQ>
<FAQ>


```javascript
//<m>
{
  slug: "sdl-getwindowfromid-benefits",
  title: "Using `SDL_GetWindowFromID()`",
  question: "Why should I use `SDL_GetWindowFromID()` instead of passing the `SDL_Window*`?",
}
```


Using `SDL_GetWindowFromID()` allows you to retrieve an `SDL_Window*` based on the `windowID` associated with events like `SDL_WindowEvent`. 


This is particularly helpful when working with multiple windows, as it ensures you’re acting on the correct window without needing to manually track pointers.


Here’s how we retrieve a window from its ID within an event handler:


```c++
void HandleWindowEvent(const SDL_WindowEvent& e) {
  SDL_Window* window =
    SDL_GetWindowFromID(e.windowID);
  if (window) {
    SDL_SetWindowTitle(window, "Event Handled");
  }
}
```


### Benefits

- **Event-Driven Code**: Avoids manually managing window pointers in global variables.
- **Simpler Multi-Window Logic**: Automatically finds the right window based on the event.
- **Error Handling**: Returns `nullptr` if the ID is invalid, allowing you to handle errors gracefully.

Using `SDL_GetWindowFromID()` simplifies multi-window management and reduces bugs in complex applications.


</FAQ>



Learn how to set, get, and update window titles dynamically

Use of `SDL_SetWindowTitle()`

Using Unicode in SDL Titles

Localizing SDL Titles

Styling SDL Titles

Dynamic Titles in SDL

Using `SDL_GetWindowFromID()`

Expanded window management lesson to a full chapter

`SDL_CreateWindow()`

`SDL_SetWindowTitle()`

`SDL_GetWindowTitle()`

`std::basic_string`

UPDATED FOR C++23 | Understand and use SDL2 functions for dynamic window title management | Clear explanations and simple code examples

Using `SDL_GetWindowFromID()`

Why should I use `SDL_GetWindowFromID()` instead of passing the `SDL_Window*`?

Benefits

Window Titles

What practical use cases are there for changing the window title during runtime?

Can I use Unicode characters in a window title?

How do I localize window titles for different languages?

Is it possible to style the window title (e.g., bold text)?

Can I make the title reflect real-time data, like a countdown timer?

Window Titles

Game Dev with SDL2

This course includes:

Professional C++

Using SDL_GetWindowFromID()

Why should I use SDL_GetWindowFromID() instead of passing the SDL_Window*?

Benefits

Window Titles

What practical use cases are there for changing the window title during runtime?

Can I use Unicode characters in a window title?

How do I localize window titles for different languages?

Is it possible to style the window title (e.g., bold text)?

Can I make the title reflect real-time data, like a countdown timer?

Window Titles

Game Dev with SDL2

This course includes:

Professional C++

Using `SDL_GetWindowFromID()`

Why should I use `SDL_GetWindowFromID()` instead of passing the `SDL_Window*`?