Window Decorations and Borders

As we likely noticed, platforms typically add additional decorations to our windows, such as a title bar. These decorations include things like title bars and borders. But what if you need a clean, borderless look?

In this lesson, we’ll cover everything you need to know about customizing SDL2 window styles, from removing decorations to dynamically adding them back.

The following screenshot is from Windows 11. It shows a decorated window on the left and an equivalent window without those decorations on the right:

SDL refers to these decorations as borders but, as we can see above, they can also include things like the title bar on desktop platforms.

By default, SDL asks the platform to include these decorations for our window. We can opt to exclude them by passing the SDL_WINDOW_BORDERLESS window flag:

1SDL_Window* Window{SDL_CreateWindow(
2  "Window", 100, 200, 300, 200,
3  SDL_WINDOW_BORDERLESS
4)};

SDL_SetWindowBordered()

We can add or remove decorations from an existing window using the SDL_SetWindowBordered() function. We pass the SDL_Window pointer as the first argument, and SDL_TRUE or SDL_FALSE as the second argument:

1SDL_Window* Window{SDL_CreateWindow(
2  "Window", 100, 200, 300, 200, 0
3)};
4
5// Adding Borders
6SDL_SetWindowBordered(Window, SDL_TRUE);
7
8// Removing Borders
9SDL_SetWindowBordered(Window, SDL_FALSE);

We can check if a window currently has borders using SDL_GetWindowFlags() and testing if the SDL_WINDOW_BORDERLESS flag is set:

1SDL_Window* Window{SDL_CreateWindow(
2  "Window", 100, 200, 300, 200,
3   SDL_WINDOW_BORDERLESS
4)};
5
6if (SDL_GetWindowFlags(Window) &
7  SDL_WINDOW_BORDERLESS) {
8  std::cout << "Window is borderless\n";
9}
10
11SDL_SetWindowBordered(Window, SDL_TRUE);
12
13if (!(SDL_GetWindowFlags(Window) &
14  SDL_WINDOW_BORDERLESS)) {
15  std::cout << "Not any more!";
16}

1Window is borderless
2Not any more!

Client Area and Border Size

When setting the position or size of a window in SDL, we are defining the dimensions of the client area. The client area refers to the region of the window where the application's content is displayed, excluding any decorations like the title bar or window borders.

Decorations are added outside the client area. For instance, if you specify a window height of 200, the client area will be exactly 200 pixels tall, but the total window height will also include the additional pixels occupied by decorations such as the title bar and borders.

To precisely control the overall window size or position, it’s important to account for the size of these decorations.

The SDL_GetWindowBordersSize() function can help us here. We pass the SDL_Window pointer, and 4 integer pointers. The integers will be updated with the size of the decorations on the top, left, bottom, and right of our window respectively:

1SDL_Window* Window{SDL_CreateWindow(
2  "Window", 100, 200, 300, 200, 0
3)};
4
5int Top, Left, Bottom, Right;
6SDL_GetWindowBordersSize(
7  Window, &Top, &Left, &Bottom, &Right);
8
9std::cout << "Top: " << Top
10  << ", Left: " << Left
11  << ", Bottom: " << Bottom
12  << ", Right: " << Right;

1Top: 31, Left: 8, Bottom: 8, Right: 8

We can pass a nullptr for any of these arguments to ignore the decoration size on that side. For example, passing nullptr for the left and right pointers will only return the sizes of the top and bottom decorations.

1// We only care about the top and bottom decoration size
2int Top, Bottom;
3SDL_GetWindowBordersSize(
4  Window, &Top, nullptr, &Bottom, nullptr);

This function returns 0 if successful, or a negative error code otherwise. We can call SDL_GetError() for an explanation of the error:

1int Top;
2int ExitCode{SDL_GetWindowBordersSize(
3  nullptr, &Top, nullptr, nullptr, nullptr)};  
4
5if (ExitCode < 0) {
6  std::cout << "Error getting border size: "
7    << SDL_GetError();
8}

1Error getting border size: Invalid window

Summary

In this lesson, we introduced window decorations, and how to control them through SDL2. This included making windows borderless and measuring their decorations for precise layout control.

Key Takeaways

• SDL provides the SDL_WINDOW_BORDERLESS flag to create borderless windows.
• Use SDL_SetWindowBordered() to dynamically toggle decorations.
• The SDL_GetWindowBordersSize() function helps calculate the size of window decorations.

Next Lesson

Window Titles

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

ContinueView Course