Window Decorations and Borders

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)};

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!

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