In this lesson, we'll explore SDL3's window positioning capabilities, from setting initial window locations to handling dynamic repositioning. We'll cover:

How to set window positions explicitly using properties, or use special values that dynamically position our window based on the environment our program is run on.
Retrieving the current location of our window.
Moving windows programmatically, including how to shift a window based on its current position.
Detecting when the user moves our window, so we can respond appropriately.

Starting Point

This lesson builds on our earlier work. To focus on window positioning, we will start with a minimal project containing a Window class and a main function with a basic application loop.

Files

src

Select a file to view its content

Initial Window Position

In SDL3, the simplified SDL_CreateWindow() function no longer accepts position arguments. To specify a window's initial position, we must use the more powerful SDL_CreateWindowWithProperties() function. This approach uses SDL's properties system to configure the window.

First, we create a properties set with SDL_CreateProperties(). Then, we set the desired x and y coordinates using SDL_SetNumberProperty() with the appropriate property names: SDL_PROP_WINDOW_CREATE_X_NUMBER and SDL_PROP_WINDOW_CREATE_Y_NUMBER.

Below, we create a window 100 points from the left edge of the screen and 200 points from the top edge:

1SDL_PropertiesID props{SDL_CreateProperties()};
2
3SDL_SetStringProperty(props,
4  SDL_PROP_WINDOW_CREATE_TITLE_STRING, "Hello Window"
5);
6
7SDL_SetNumberProperty(props,
8  SDL_PROP_WINDOW_CREATE_WIDTH_NUMBER, 700
9);
10
11SDL_SetNumberProperty(props,
12  SDL_PROP_WINDOW_CREATE_HEIGHT_NUMBER, 300
13);
14
15SDL_SetNumberProperty(props,
16  SDL_PROP_WINDOW_CREATE_X_NUMBER, 100
17);
18
19SDL_SetNumberProperty(props,
20  SDL_PROP_WINDOW_CREATE_Y_NUMBER, 200
21);
22
23SDL_Window* Window{
24  SDL_CreateWindowWithProperties(props)
25};
26
27SDL_DestroyProperties(props);

Using `SDL_WINDOWPOS_UNDEFINED`

In most cases, we don't need to be this specific. We can let the platform decide the best place to open the window by using the special value SDL_WINDOWPOS_UNDEFINED.

This is a sensible default, as platforms often have smart placement strategies, like opening the window near the cursor or remembering its last position.

1SDL_SetNumberProperty(props,
2  SDL_PROP_WINDOW_CREATE_X_NUMBER,
3  SDL_WINDOWPOS_UNDEFINED);
4  
5SDL_SetNumberProperty(props,
6  SDL_PROP_WINDOW_CREATE_Y_NUMBER,
7  SDL_WINDOWPOS_UNDEFINED);

Using `SDL_WINDOWPOS_CENTERED`

Alternatively, we can use SDL_WINDOWPOS_CENTERED to have SDL automatically center the window on the primary display. SDL calculates the correct coordinates based on the monitor and window dimensions.

Below, we create a window that is centered both horizontally and vertically:

1SDL_SetNumberProperty(props,
2  SDL_PROP_WINDOW_CREATE_X_NUMBER,
3  SDL_WINDOWPOS_CENTERED);
4  
5SDL_SetNumberProperty(props,
6  SDL_PROP_WINDOW_CREATE_Y_NUMBER,
7  SDL_WINDOWPOS_CENTERED);

Getting the Window Position

While we can specify an initial position, users can move the window by dragging its title bar. To get the current position of a window, we pass its SDL_Window pointer to SDL_GetWindowPosition(). We also provide pointers to two integers that SDL will update with the window's x and y coordinates:

1int x, y;
2SDL_GetWindowPosition(Window, &x, &y);

Here's a complete example:

src/main.cpp

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include <iostream>
4#include "Window.h"
5
6int main(int, char**) {
7  SDL_Init(SDL_INIT_VIDEO);
8  Window GameWindow;
9
10  int x, y;
11  SDL_GetWindowPosition(
12    GameWindow.GetRaw(), &x, &y
13  );
14  
15  std::cout << "Position: "
16    << x << ", " << y << '\n';
17
18  while (IsRunning) {/*...*/}
30
31  SDL_Quit();
32  return 0;
33}

1Position: 930, 570

If we only care about one dimension, we can pass a nullptr for the other:

1// We only care about horizontal position
2int x;
3SDL_GetWindowPosition(Window, &x, nullptr);
4
5// We only care about vertical position
6int y;
7SDL_GetWindowPosition(Window, nullptr, &y);

Window Movement Events and `SDL_EVENT_WINDOW_MOVED`

While SDL_GetWindowPosition() allows us to retrieve the position at any time, reacting to movement is often better handled through the event loop.

When a window is moved, SDL dispatches a top-level event with the type SDL_EVENT_WINDOW_MOVED. We can detect this directly in our event loop:

src/main.cpp

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include <iostream>
4#include "Window.h"
5
6void HandleWindowEvent(const SDL_WindowEvent& E) {
7  if (E.type == SDL_EVENT_WINDOW_MOVED) {
8    std::cout << "Window Moved\n";
9  }
10}
11
12int main(int, char**) {
13  SDL_Init(SDL_INIT_VIDEO);
14  Window GameWindow;
15  SDL_Event E;
16
17  bool IsRunning = true;
18  while (IsRunning) {
19    while (SDL_PollEvent(&E)) {
20      if (E.type >= SDL_EVENT_WINDOW_FIRST &&
21          E.type <= SDL_EVENT_WINDOW_LAST
22      ) {
23        HandleWindowEvent(E.window);
24      } else if (E.type == SDL_EVENT_QUIT) {
25        IsRunning = false;
26      }
27    }
28    GameWindow.Render();
29    GameWindow.Update();
30  }
31
32  SDL_Quit();
33  return 0;
34}

1Window Moved

The data1 and data2 members of the SDL_WindowEvent struct (E.window) contain the new horizontal and vertical positions of the window, respectively:

src/main.cpp

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include <iostream>
4#include "Window.h"
5
6void HandleWindowEvent(const SDL_WindowEvent& E) {
7  if (E.type == SDL_EVENT_WINDOW_MOVED) {
8    std::cout << "Window Moved: "
9      << E.data1 << ", " << E.data2 << '\n';
10  }
11}
12
13int main(int, char**) {/*...*/}

1Window Moved: 506, 281

Programmatically Moving a Window

We can update the position of an SDL_Window at any time using SDL_SetWindowPosition(). This function takes the SDL_Window* as its first argument, followed by the new x and y coordinates.

Let's add this capability to our custom Window class by introducing a Move() method:

src/Window.h

1#pragma once
2#include <SDL3/SDL.h>
3
4class Window {
5public:
6  //...
7  
8  void Move(int x, int y) {
9    SDL_SetWindowPosition(SDLWindow, x, y);
10  }
11
12  //...
13};

Just like when we create a window, we can use SDL_WINDOWPOS_UNDEFINED to let the platform decide the best position, or SDL_WINDOWPOS_CENTERED to center it. Below, we move the window to the center of the screen when the user presses the spacebar:

src/main.cpp

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include <iostream>
4#include "Window.h"
5
6void HandleKeydownEvent(
7  const SDL_KeyboardEvent& E, Window& Window
8) {
9  if (E.key == SDLK_SPACE) {
10    Window.Move(
11      SDL_WINDOWPOS_CENTERED,
12      SDL_WINDOWPOS_CENTERED
13    );
14  }
15}
16
17int main(int, char**) {
18  SDL_Init(SDL_INIT_VIDEO);
19  Window GameWindow;
20  SDL_Event E;
21
22  bool IsRunning = true;
23  while (IsRunning) {
24    while (SDL_PollEvent(&E)) {
25      if (E.type == SDL_EVENT_KEY_DOWN) {
26        HandleKeydownEvent(E.key, GameWindow);
27      } else if (E.type == SDL_EVENT_QUIT) {
28        IsRunning = false;
29      }
30    }
31    GameWindow.Render();
32    GameWindow.Update();
33  }
34
35  SDL_Quit();
36  return 0;
37}

Using `SDL_GetWindowFromID()`

The event handler in the previous example requires a pointer to the SDL_Window it needs to move. We accomplished this by passing a reference to our GameWindow object.

This is a valid approach for a simple, single-window application. However, if our program contains multiple windows, we won't necessarily know which one caused the event.

An alternative approach involves retrieving the SDL_Window* from the event itself. Most event types, including SDL_KeyboardEvent, include a windowID that identifies the window associated with the event. By passing this value to SDL_GetWindowFromID(), we can retrieve the corresponding SDL_Window pointer:

1void HandleKeydownEvent(const SDL_KeyboardEvent& E) {
2  if (E.key == SDLK_SPACE) {
3    SDL_SetWindowPosition(
4      SDL_GetWindowFromID(E.windowID),
5      SDL_WINDOWPOS_CENTERED,
6      SDL_WINDOWPOS_CENTERED
7    );
8  }
9}

Relative Moving

Often, we'll want to move a window relative to its current position rather than to an absolute screen coordinate. To do this, we can combine SDL_GetWindowPosition() and SDL_SetWindowPosition().

Updating our Window class to support relative moving might look something like this:

src/Window.h

1#pragma once
2#include <SDL3/SDL.h>
3
4class Window {
5public:
6  //...
7  void MoveRelative(int DeltaX, int DeltaY) {
8    int CurrentX, CurrentY;
9    SDL_GetWindowPosition(
10      SDLWindow, &CurrentX, &CurrentY
11    );
12
13    SDL_SetWindowPosition(
14      SDLWindow,
15      CurrentX + DeltaX,
16      CurrentY + DeltaY
17    );
18  }
19  //...
20};

In the following example, we use this new method to let the user move the window with their arrow keys:

src/main.cpp

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include <iostream>
4#include "Window.h"
5
6void HandleKeydownEvent(
7  const SDL_KeyboardEvent& E, Window& GameWindow
8) {
9  if (E.key == SDLK_LEFT) {
10    GameWindow.MoveRelative(-10, 0);
11  } else if (E.key == SDLK_RIGHT) {
12    GameWindow.MoveRelative(10, 0);
13  } else if (E.key == SDLK_UP) {
14    GameWindow.MoveRelative(0, -10);
15  } else if (E.key == SDLK_DOWN) {
16    GameWindow.MoveRelative(0, 10);
17  }
18}
19
20int main(int, char**) {
21  SDL_Init(SDL_INIT_VIDEO);
22  Window GameWindow;
23  SDL_Event E;
24
25  bool IsRunning = true;
26  while (IsRunning) {
27    while (SDL_PollEvent(&E)) {
28      if (E.type == SDL_EVENT_KEY_DOWN) {
29        HandleKeydownEvent(E.key, GameWindow);
30      } else if (E.type == SDL_EVENT_QUIT) {
31        IsRunning = false;
32      }
33    }
34    GameWindow.Render();
35    GameWindow.Update();
36  }
37
38  SDL_Quit();
39  return 0;
40}

Summary

In this lesson, we've covered the fundamentals of window positioning. We've learned how to control window placement both at creation and during runtime, respond to window movement events, and implement relative movement. Key takeaways:

Initial window position in SDL3 is set using SDL_CreateWindowWithProperties().
Special values like SDL_WINDOWPOS_UNDEFINED and SDL_WINDOWPOS_CENTERED provide automated placement options.
SDL_GetWindowPosition() lets us query a window's current location.
SDL_SetWindowPosition() allows for programmatic window movement.
Window movement events (SDL_EVENT_WINDOW_MOVED) help us track user-initiated window changes.
Relative movement can be implemented by combining position getting and setting.

Managing Window Position

Starting Point

Files

Initial Window Position

Using `SDL_WINDOWPOS_UNDEFINED`

Using `SDL_WINDOWPOS_CENTERED`

Getting the Window Position

src/main.cpp

Window Movement Events and `SDL_EVENT_WINDOW_MOVED`

src/main.cpp

src/main.cpp

Programmatically Moving a Window

src/Window.h

src/main.cpp

Relative Moving

src/Window.h

src/main.cpp

Summary

Window Sizing

Game Development with SDL3

Managing Window Position

Starting Point

Files

Initial Window Position

Using SDL_WINDOWPOS_UNDEFINED

Using SDL_WINDOWPOS_CENTERED

Getting the Window Position

src/main.cpp

Window Movement Events and SDL_EVENT_WINDOW_MOVED

src/main.cpp

src/main.cpp

Programmatically Moving a Window

src/Window.h

src/main.cpp

Relative Moving

src/Window.h

src/main.cpp

Summary

Window Sizing

Using `SDL_WINDOWPOS_UNDEFINED`

Using `SDL_WINDOWPOS_CENTERED`

Window Movement Events and `SDL_EVENT_WINDOW_MOVED`