Window Sizing

This lesson explores the tools SDL2 offers for controlling window sizes and responding to changes. We’ll cover:

• Allowing users to resize windows.
• Retrieving and setting window dimensions programmatically.
• Using resize events for dynamic layouts.

Window Size

As we’ve seen, we can define the initial size when creating our window using the 4th and 5th arguments to SDL_CreateWindow():

1SDL_CreateWindow(
2  "My Program", // Title
3  100, // Horizontal Position
4  200, // Vertical Position
5  600, // Width
6  300, // Height
7  0 // Configuration
8);

Resizable Windows

In most desktop environments, users can resize windows by clicking and dragging their borders. We can allow our window to be resized by passing the SDL_WINDOW_RESIZABLE window flag:

1SDL_CreateWindow(
2  "My Program",
3  100, 200, 600, 300,
4  SDL_WINDOW_RESIZABLE
5);

We cover window flags in detail earlier in this chapter:

Window Configuration

Explore window creation, configuration, and event handling using SDL's windowing system

SDL_SetWindowResizable()

We can specify whether an existing window can be resized by players using the SDL_SetWindowResizable() function. We pass the SDL_Window pointer as the first argument. The second argument will be SDL_TRUE if we want the window to be resizable, or SDL_FALSE otherwise:

1SDL_Window* Window{SDL_CreateWindow(
2  "My Program",
3  100, 200, 600, 300,
4  // Not setting the resizable flag
5  0 
6)};
7
8// Update the window to be resizable
9SDL_SetWindowResizable(Window, SDL_TRUE);
10
11// Disable resizing
12SDL_SetWindowResizable(Window, SDL_FALSE);

Checking if a Window is Resizable

If we need to check if an SDL_Window is currently resizable by players, we can retrieve its window flags and use the & operator to isolate the SDL_WINDOW_RESIZABLE bit:

1bool isResizable(SDL_Window* Window) {
2  Uint32 Flags{SDL_GetWindowFlags(Window)};
3  return Flags & SDL_WINDOW_RESIZABLE;
4}

The window flags associated with a window are kept up to date as we use other functions, like SDL_SetWindowResizable(), to update the configuration of our window:

1SDL_Window* Window{SDL_CreateWindow(
2  "My Program",
3  100, 200, 600, 300,
4  SDL_WINDOW_RESIZABLE
5)};
6
7if (isResizable(Window)) {
8  std::cout << "Window is resizable\n";
9}
10
11SDL_SetWindowResizable(Window, SDL_FALSE);
12
13if (!isResizable(Window)) {
14  std::cout << "Not any more!";
15}

1Window is resizable
2Not any more!

Minimum Size

If we want to let players resize our window, we will often want to set some constraints on how large or how small they can make it.

To set the minimum size, we use the SDL_SetWindowMinimumSize() function, passing three arguments:

1. The pointer to the SDL_Window we want to constrain
2. The minimum horizontal size
3. The minimum vertical size

1SDL_Window* Window{SDL_CreateWindow(
2  "My Program",
3  100, 200, 600, 300,
4  SDL_WINDOW_RESIZABLE
5)};
6
7SDL_SetWindowMinimumSize(Window, 200, 200);

We can retrieve the currently configured minimum size using SDL_GetWindowMinimumSize(). We pass the SDL_Window pointer and two integer pointers. The integers are updated with the current minimum width and height, respectively:

1SDL_Window* Window{SDL_CreateWindow(
2  "My Program",
3  100, 200, 600, 300,
4  SDL_WINDOW_RESIZABLE
5)};
6
7SDL_SetWindowMinimumSize(Window, 200, 200);
8
9int minW, minH;
10SDL_GetWindowMinimumSize(Window, &minW, &minH);
11
12std::cout << "Minimum Width: " << minW
13  << "\nMinimum Height: " << minH;

1Minimum Width: 200
2Minimum Height: 200

Either of the integer pointers can be a nullptr if we don’t care about the minimum size in that dimension:

1int minW, minH;
2
3// We only care about the minimum width
4SDL_GetWindowMinimumSize(Window, &minW, nullptr);
5
6// We only care about the minimum height
7SDL_GetWindowMinimumSize(Window, nullptr, &minH);

Maximum Size

For the maximum window size, we have the SDL_SetWindowMaximumSize() and SDL_GetWindowMaximumSize() functions. These work in the same way as their minimum-size counterparts:

1SDL_Window* Window{SDL_CreateWindow(
2  "My Program",
3  100, 200, 600, 300,
4  SDL_WINDOW_RESIZABLE
5)};
6
7SDL_SetWindowMaximumSize(Window, 1200, 1200);
8
9int maxW, maxH;
10SDL_GetWindowMaximumSize(Window, &maxW, &maxH);
11
12std::cout << "Maximum Width: " << maxW
13  << "\nMaximum Height: " << maxH;

1Maximum Width: 1200
2Maximum Height: 1200

Getting the Current Window Size

We can request the current window size at any time using the SDL_GetWindowSize() function. We pass the window size and two pointers to integers. The integers will be updated with the width and height of the window respectively:

1SDL_Window* Window{SDL_CreateWindow(
2  "My Program",
3  100, 200, 600, 300,
4  SDL_WINDOW_RESIZABLE
5)};
6
7int x, y;
8SDL_GetWindowSize(Window, &x, &y);
9std::cout << "Size: " << x << "x" << y;

1Size: 600x300

If we only care about the size in a single dimension, we can pass a nullptr as the other argument:

1SDL_Window* Window{SDL_CreateWindow(
2  "My Program",
3  100, 200, 600, 300,
4  SDL_WINDOW_RESIZABLE
5)};
6
7int x;
8SDL_GetWindowSize(Window, &x, nullptr);
9std::cout << "Width: " << x;
10
11int y;
12SDL_GetWindowSize(Window, nullptr, &y);
13std::cout << "\nHeight: " << x;

1Width: 600
2Height: 300

Programmatic Resizing

In addition to letting users resize our window, we can programmatically resize our window at any time. We do this using the SDL_SetWindowSize() function, passing our SDL_Window pointer, and two integers representing the desired width and height respectively:

1SDL_Window* Window{SDL_CreateWindow(
2  "My Program",
3  100, 200, 600, 300,
4  SDL_WINDOW_RESIZABLE
5)};
6
7int x, y;
8SDL_GetWindowSize(Window, &x, &y);
9std::cout << "\nSize: " << x << "x" << y;
10
11SDL_SetWindowSize(Window, 500, 700);
12
13SDL_GetWindowSize(Window, &x, &y);
14std::cout << "\nSize: " << x << "x" << y;

1Size: 600x300
2Size: 500x700

Maximising and Restoring Windows

Desktop platforms typically support the idea of having a window maximized within a screen. Maximized windows are sized and positioned to fill almost the entire visible area of the screen, only leaving space for some platform-specific elements like the taskbar on Windows.

If our SDL_Window is resizable, users will typically also be able to maximize by, for example, double-clicking the title bar in Windows or macOS:

1SDL_Window* Window{SDL_CreateWindow(
2  "My Program",
3  100, 200, 600, 300,
4  // If a window is resizable, it will also
5  // also be maximizable in supported platforms
6  SDL_WINDOW_RESIZABLE
7)};

We can also create our window in the maximized state using the SDL_WINDOW_MAXIMIZED flag. This does not require the window to be resizable but, in most circumstances, we’ll want a maximized window to also be resizable:

1SDL_Window* Window{SDL_CreateWindow(
2  "My Program",
3  100, 200, 600, 300,
4  SDL_WINDOW_RESIZABLE | SDL_WINDOW_MAXIMIZED
5)};

SDL_MaximizeWindow()

We can maximize an existing window by passing its SDL_Window pointer to SDL_MaximizeWindow():

1SDL_Window* Window{SDL_CreateWindow(
2  "My Program",
3  100, 200, 600, 300,
4  SDL_WINDOW_RESIZABLE
5)};
6
7SDL_MaximizeWindow(Window);

SDL_RestoreWindow()

When a window is maximized, the platform remembers its previous position and size. We can restore a window to this state by passing its SDL_Window pointer to SDL_RestoreWindow():

1SDL_Window* Window{SDL_CreateWindow(
2  "My Program",
3  100, 200, 600, 300,
4  SDL_WINDOW_RESIZABLE
5)};
6
7SDL_MaximizeWindow(Window);

Checking if a Window is Maximized

We can check if a window is currently maximized by retrieving its SDL_WindowFlags and isolating the SDL_WINDOW_MAXIMIZED bit:

1SDL_Window* Window{SDL_CreateWindow(
2  "My Program",
3  100, 200, 600, 300,
4  SDL_WINDOW_RESIZABLE | SDL_WINDOW_MAXIMIZED
5)};
6
7if (SDL_GetWindowFlags(Window) &
8    SDL_WINDOW_MAXIMIZED) {
9  std::cout << "Window is maximized";
10}

1Window is maximized

Window Resize Events

When this happens, an SDL_WindowEvent is created. As usual, we can detect window events within our event loop by checking if the type of each SDL_Event is SDL_WINDOWEVENT.

If it is, the window member of the SDL_Event will contain an SDL_WindowEvent, which we can further examine to determine what our reaction should be:

1// main.cpp
2#include <SDL.h>
3#include "Window.h"
4
5void HandleWindowEvent(SDL_WindowEvent& E) {
6  // Detected Window Event
7}
8
9int main(int argc, char** argv) {
10  SDL_Init(SDL_INIT_VIDEO);
11  Window GameWindow;
12  SDL_Event E;
13
14  while (true) {
15    while (SDL_PollEvent(&E)) {
16      if (E.type == SDL_WINDOWEVENT) {
17        HandleWindowEvent(E.window);
18      } else if (E.type == SDL_QUIT) {
19        SDL_Quit();
20        return 0;
21      }
22    }
23    GameWindow.Update();
24    GameWindow.Render();
25  }
26}

SDL_WINDOWEVENT_SIZE_CHANGED

When the SDL_WindowEvent was created to report the size of our window changing, its event member will be equal to SDL_WINDOWEVENT_SIZE_CHANGED. The new horizontal and vertical dimensions of the window are available in the data1 and data2 variables respectively:

1// main.cpp
2#include <SDL.h>
3#include <iostream>
4#include "Window.h"
5
6void HandleWindowEvent(SDL_WindowEvent& E) {
7  if (E.event == SDL_WINDOWEVENT_SIZE_CHANGED) {
8    std::cout << "Window Resized to: "
9      << E.data1 << "x" << E.data2 << '\n';
10  }
11}
12
Main Function|Show
13int main(int argc, char** argv) {/*...*/}

1Window Size Changed to: 831x497

SDL_WINDOWEVENT_RESIZED

In the previous example, we tracked SDL_WINDOWEVENT_SIZE_CHANGED events. These events are reported when the window size changes for any reason. This includes programmatic resizes using SDL_SetWindowSize(), and resizing triggered by the platform itself.

When the resizing is triggered by the user, an additional SDL_WindowEvent is generated, with its event equal to SDL_WINDOWEVENT_RESIZED. When we only need to react to user-triggered events, we can check explicitly for this event rather than the more generic SDL_WINDOWEVENT_SIZE_CHANGED:

1// main.cpp
2#include <SDL.h>
3#include <iostream>
4#include "Window.h"
5
6void HandleWindowEvent(SDL_WindowEvent& E) {
7  if (E.event == SDL_WINDOWEVENT_RESIZED) {
8    std::cout << "Window Resized by Player to: "
9      << E.data1 << "x" << E.data2 << '\n';
10  }
11}
12
13int main(int argc, char** argv) {
14  SDL_Init(SDL_INIT_VIDEO);
15  Window GameWindow;
16
17  // This will create a
18  // SDL_WINDOWEVENT_SIZE_CHANGED event, but
19  // not a SDL_WINDOWEVENT_RESIZED event
20  SDL_SetWindowSize(
21    GameWindow.SDLWindow, 150, 150
22  );
23  
24  SDL_Event E;
25  
Event Loop|Show
26  while (true) {/*...*/}
39}

1Window Resized by Player to: 1003x509

SDL_WINDOWEVENT_MAXIMIZED and SDL_WINDOWEVENT_RESTORED

Window resize events will also be triggered if the act of maximizing or restoring a window causes the size to change. However, if we need to react to maximizing and restoring actions explicitly, additional events are also reported to help us achieve that.

The type of these events will also be SDL_WINDOWEVENT and, within the SDL_WindowEvent, the event field will be SDL_WINDOWEVENT_MAXIMIZED or SDL_WINDOWEVENT_RESTORED:

1// main.cpp
2#include <SDL.h>
3#include <iostream>
4#include "Window.h"
5
6void HandleWindowEvent(SDL_WindowEvent& E) {
7  if (E.event == SDL_WINDOWEVENT_SIZE_CHANGED) {
8    std::cout << "\nWindow Size Changed to: "
9      << E.data1 << "x" << E.data2;
10  } else if (E.event == SDL_WINDOWEVENT_MAXIMIZED) {
11    std::cout << " (Maximized)";
12  } else if (E.event == SDL_WINDOWEVENT_RESTORED) {
13    std::cout << " (Restored)";
14  }
15}
16
Main Function|Show
17int main(int argc, char** argv) {/*...*/}

1Window Size Changed to: 2560x1369 (Maximized)
2Window Size Changed to: 600x300 (Restored)

Summary

This lesson explored the ways in which we manage our window sizes in SDL2 programs. Key takeaways include:

• Use the SDL_WINDOW_RESIZABLE flag to create a resizable window, or to determine if an existing window is resizable
• The SDL_SetWindowResizable() function lets us configure whether an existing window is resizable.
• Use SDL_SetWindowMinimumSize() and SDL_SetWindowMaximumSize() to limit the extent to which a window is resizable.
• We can programmatically resize a window using SDL_SetWindowSize()
• SDL_GetWindowSize() let’s us determine the current size of a window
• Windows can be maximized and restored using SDL_MaximizeWindow() and SDL_RestoreWindow()
• If we need to react to users resizing, maximizing or restoring our windows, we can monitor the event loop for relevant SDL_WindowEvent traffic.

Next Lesson

Window Visibility

Learn how to control the visibility of SDL2 windows, including showing, hiding, minimizing, and more

ContinueView Course