Window Sizing

Learn how to resize, constrain, and manage SDL2 windows

Ryan McCombe
Updated

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.

Setting the 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():

SDL_CreateWindow(
  "My Program", // Title
  100, // Horizontal Position
  200, // Vertical Position
  600, // Width
  300, // Height
  0 // Configuration
);

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:

SDL_CreateWindow(
  "My Program",
  100, 200, 600, 300,
  SDL_WINDOW_RESIZABLE
);

We cover window flags in detail earlier in this chapter:

Window Configuration

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

Making Windows Resizable Using 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:

SDL_Window* Window{SDL_CreateWindow(
  "My Program",
  100, 200, 600, 300,
  // Not setting the resizable flag
  0 
)};

// Update the window to be resizable
SDL_SetWindowResizable(Window, SDL_TRUE);

// Disable resizing
SDL_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:

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

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:

SDL_Window* Window{SDL_CreateWindow(
  "My Program",
  100, 200, 600, 300,
  SDL_WINDOW_RESIZABLE
)};

if (isResizable(Window)) {
  std::cout << "Window is resizable\n";
}

SDL_SetWindowResizable(Window, SDL_FALSE);

if (!isResizable(Window)) {
  std::cout << "Not any more!";
}
Window is resizable
Not 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
SDL_Window* Window{SDL_CreateWindow(
  "My Program",
  100, 200, 600, 300,
  SDL_WINDOW_RESIZABLE
)};

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

SDL_Window* Window{SDL_CreateWindow(
  "My Program",
  100, 200, 600, 300,
  SDL_WINDOW_RESIZABLE
)};

SDL_SetWindowMinimumSize(Window, 200, 200);

int minW, minH;
SDL_GetWindowMinimumSize(Window, &minW, &minH);

std::cout << "Minimum Width: " << minW
  << "\nMinimum Height: " << minH;
Minimum Width: 200
Minimum Height: 200

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

int minW, minH;

// We only care about the minimum width
SDL_GetWindowMinimumSize(Window, &minW, nullptr);

// We only care about the minimum height
SDL_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:

SDL_Window* Window{SDL_CreateWindow(
  "My Program",
  100, 200, 600, 300,
  SDL_WINDOW_RESIZABLE
)};

SDL_SetWindowMaximumSize(Window, 1200, 1200);

int maxW, maxH;
SDL_GetWindowMaximumSize(Window, &maxW, &maxH);

std::cout << "Maximum Width: " << maxW
  << "\nMaximum Height: " << maxH;
Maximum Width: 1200
Maximum 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:

SDL_Window* Window{SDL_CreateWindow(
  "My Program",
  100, 200, 600, 300,
  SDL_WINDOW_RESIZABLE
)};

int x, y;
SDL_GetWindowSize(Window, &x, &y);
std::cout << "Size: " << x << "x" << y;
Size: 600x300

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

SDL_Window* Window{SDL_CreateWindow(
  "My Program",
  100, 200, 600, 300,
  SDL_WINDOW_RESIZABLE
)};

int x;
SDL_GetWindowSize(Window, &x, nullptr);
std::cout << "Width: " << x;

int y;
SDL_GetWindowSize(Window, nullptr, &y);
std::cout << "\nHeight: " << x;
Width: 600
Height: 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:

SDL_Window* Window{SDL_CreateWindow(
  "My Program",
  100, 200, 600, 300,
  SDL_WINDOW_RESIZABLE
)};

int x, y;
SDL_GetWindowSize(Window, &x, &y);
std::cout << "\nSize: " << x << "x" << y;

SDL_SetWindowSize(Window, 500, 700);

SDL_GetWindowSize(Window, &x, &y);
std::cout << "\nSize: " << x << "x" << y;
Size: 600x300
Size: 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:

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

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:

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

Maximising Windows Using SDL_MaximizeWindow()

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

SDL_Window* Window{SDL_CreateWindow(
  "My Program",
  100, 200, 600, 300,
  SDL_WINDOW_RESIZABLE
)};

SDL_MaximizeWindow(Window);

Restoring Windows Using 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():

SDL_Window* Window{SDL_CreateWindow(
  "My Program",
  100, 200, 600, 300,
  SDL_WINDOW_RESIZABLE
)};

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

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

if (SDL_GetWindowFlags(Window) &
    SDL_WINDOW_MAXIMIZED) {
  std::cout << "Window is maximized";
}
Window 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:

// main.cpp
#include <SDL.h>
#include "Window.h"

void HandleWindowEvent(SDL_WindowEvent& E) {
  // Detected Window Event
}

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(E.window);
      } else if (E.type == SDL_QUIT) {
        SDL_Quit();
        return 0;
      }
    }
    GameWindow.Render();
    GameWindow.Update();
  }
}

Tracking Window Resizes Using 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:

// main.cpp
#include <SDL.h>
#include <iostream>
#include "Window.h"

void HandleWindowEvent(SDL_WindowEvent& E) {
  if (E.event == SDL_WINDOWEVENT_SIZE_CHANGED) {
    std::cout << "Window Resized to: "
      << E.data1 << "x" << E.data2 << '\n';
  }
}

int main(int argc, char** argv) {/*...*/}
Window Size Changed to: 831x497

Tracking Manual Resizes Using 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:

// main.cpp
#include <SDL.h>
#include <iostream>
#include "Window.h"

void HandleWindowEvent(SDL_WindowEvent& E) {
  if (E.event == SDL_WINDOWEVENT_RESIZED) {
    std::cout << "Window Resized by Player to: "
      << E.data1 << "x" << E.data2 << '\n';
  }
}

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

  // This will create a
  // SDL_WINDOWEVENT_SIZE_CHANGED event, but
  // not a SDL_WINDOWEVENT_RESIZED event
  SDL_SetWindowSize(
    GameWindow.SDLWindow, 150, 150
  );
  
  SDL_Event E;
  
while (true) {/*...*/} }
Window Resized by Player to: 1003x509

The SDL_WINDOWEVENT_MAXIMIZED and SDL_WINDOWEVENT_RESTORED Event Types

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:

// main.cpp
#include <SDL.h>
#include <iostream>
#include "Window.h"

void HandleWindowEvent(SDL_WindowEvent& E) {
  if (E.event == SDL_WINDOWEVENT_SIZE_CHANGED) {
    std::cout << "\nWindow Size Changed to: "
      << E.data1 << "x" << E.data2;
  } else if (E.event == SDL_WINDOWEVENT_MAXIMIZED) {
    std::cout << " (Maximized)";
  } else if (E.event == SDL_WINDOWEVENT_RESTORED) {
    std::cout << " (Restored)";
  }
}

int main(int argc, char** argv) {/*...*/}
Window Size Changed to: 2560x1369 (Maximized)
Window 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
Lesson 53 of 129

Window Decorations and Borders

An introduction to managing SDL2 window decorations, borders, and client areas.

Questions & Answers

Answers are generated by AI models and may not have been reviewed. Be mindful when running any code on your device.

Handling Exceeded Minimum Window Size
What happens if the minimum window size exceeds the current window size?
Resizing and Graphical Content
How does resizing affect graphical content displayed inside the window?
Constraints in SDL_SetWindowSize()
Is SDL_SetWindowSize() affected by the maximum and minimum size constraints?
Size Changed vs Resized Events
What is the difference between SDL_WINDOWEVENT_SIZE_CHANGED and SDL_WINDOWEVENT_RESIZED?
Best Practices for Resize Events
What are the best practices for handling resize events in games?
Integer Pointers in SDL
Why does SDL require integer pointers in functions like SDL_GetWindowSize()?
Or Ask your Own Question
Purchase the course to ask your own questions