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": ```c++ 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. ```c++ #include #include #include "Window.h" int main(int, char**) { SDL_Init(SDL_INIT_VIDEO); Window GameWindow; SDL_Event Event; bool IsRunning = true; while (IsRunning) { while (SDL_PollEvent(&Event)) { if (Event.type == SDL_EVENT_QUIT) { IsRunning = false; } } GameWindow.Render(); GameWindow.Update(); } SDL_Quit(); return 0; } ``` ```c++ #pragma once #include class Window { public: Window() { SDLWindow = SDL_CreateWindow( "My Program", 600, 300, 0 ); } SDL_Window* GetRaw() const { return SDLWindow; } void Render() { const auto* Fmt = SDL_GetPixelFormatDetails( GetSurface()->format ); SDL_FillSurfaceRect( GetSurface(), nullptr, SDL_MapRGB(Fmt, nullptr, 50, 50, 50) ); } void Update() { SDL_UpdateWindowSurface(SDLWindow); } SDL_Surface* GetSurface() const { return SDL_GetWindowSurface(SDLWindow); } Window(const Window&) = delete; Window& operator=(const Window&) = delete; ~Window() { if (SDLWindow && SDL_WasInit(SDL_INIT_VIDEO)) { SDL_DestroyWindow(SDLWindow); } } private: SDL_Window* SDLWindow{nullptr}; }; ``` ## 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: ```c++ 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: ```c++ std::cout << SDL_GetWindowTitle(WindowPointer); ``` ```c++ // New Title ``` ## Example: 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: ```c++ #include #include #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 Window Events and Window IDs. 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(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: ```c++ // 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: ```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 (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: ```c++ #pragma once #include #include 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`: ```c++ #pragma once #include #include 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 character encoding. ## 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::string` and `char*` improves modern C++ compatibility.

Window Titles

Understanding the Basics

Practical Applications

Common Mistakes

Next Steps

Additional Resources

Assessment Preparation