Mouse Input Constraints

SDL2 provides tools for controlling mouse movement in our applications. In this lesson, we'll explore how to constrain the mouse cursor to specific windows and regions, giving you precise control over user input. Key topics covered:

• Window-level mouse grabbing using SDL_WINDOW_MOUSE_GRABBED
• Dynamic mouse grab toggling with SDL_SetWindowMouseGrab
• Rectangular constraints using SDL_SetWindowMouseRect
• Combining grab and rectangle constraints
• Error handling and state verification

Mouse Grabbing

In many applications, particularly games, we want to prevent the user’s mouse cursor from leaving a window. There is a flag within the SDL_WindowFlags bit set dedicated to this purpose. The SDL_WINDOW_MOUSE_GRABBED bit mask can be used to help us select this bit:

1SDL_CreateWindow(
2  "Hello Window",
3  100, 200, 300, 400,
4  SDL_WINDOW_MOUSE_GRABBED 
5);

The window flags are kept up to date throughout the lifecycle of the window. As such, we can check if a window is currently grabbing the mask by retrieving its flags, and selecting the SDL_WINDOW_MOUSE_GRABBED bit:

1bool isGrabbed(SDL_Window* Window) {
2  return SDL_GetWindowFlags(Window)
3    & SDL_WINDOW_MOUSE_GRABBED;
4}

We cover window flags, including the use of the bitwise AND operator & in more detail here:

Window Configuration

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

SDL_GetWindowMouseGrab()

We can alternatively determine if a window is grabbing the mouse by passing its pointer to SDL_GetWindowMouseGrab():

1bool isGrabbed(SDL_Window* Window) {
2  return SDL_GetWindowMouseGrab(Window);
3}

SDL_GetGrabbedWindow()

We can retrieve the window that has currently grabbed the mouse using the SDL_GetGrabbedWindow(). This returns the SDL_Window pointer to the window that has grabbed the mouse, or a nullptr if the mouse is not grabbed:

1SDL_Window* Grabbed{SDL_GetGrabbedWindow()};
2
3if (Grabbed) {
4  std::cout << "Mouse grabbed by: "
5    << SDL_GetWindowTitle(Grabbed);
6} else {
7  std::cout << "Mouse is not grabbed";
8}

This function is primarily useful in programs that have multiple windows, which we’ll cover in more detail later in this chapter.

Toggling Mouse Grab

That can be done with the SDL_SetWindowMouseGrab() function. We need to pass it a pointer to the SDL_Window, as well as a second argument indicating whether we want the mouse to grab.

The second argument should be SDL_TRUE to grab the cursor, or SDL_FALSE to release it:

1// Grab the mouse
2SDL_SetWindowMouseGrab(SDLWindow, SDL_TRUE);
3
4// Release the mouse
5SDL_SetWindowMouseGrab(SDLWindow, SDL_FALSE);

Error Checking

Mouse grabbing may not always succeed due to system limitations or configurations. While SDL doesn't return error codes for these operations directly, we can verify if the grab was successful by checking the window's state afterward.

Below, we check this immediately after attempting to create a window with mouse grab enabled:

1SDL_Window* Window{
2  SDL_CreateWindow(
3    "Hello Window",
4    100, 200, 300, 400,
5    SDL_WINDOW_MOUSE_GRABBED
6  )
7};
8
9if (!SDL_GetWindowMouseGrab(Window)) {
10  std::cout << "Mouse grab failed - system "
11    "may not support this feature\n";
12  // Handle the failure appropriately
13}

The same verification applies when toggling the mouse grab for an existing window:

1SDL_SetWindowMouseGrab(Window, SDL_TRUE);
2if (!SDL_GetWindowMouseGrab(Window)) {
3  std::cout << "Mouse grab failed - system "
4    "may not support this feature\n";
5  // Handle the failure appropriately
6}

Example

In the following example, we grab the cursor and constrain it to our window as long as the player is holding their left mouse button. When they release the button, we release their mouse:

1#include <SDL.h>
2#include "Window.h"
3
4void HandleMouseEvent(
5  SDL_MouseButtonEvent& E, SDL_Window* Window
6) {
7  if (E.button != SDL_BUTTON_LEFT) return;
8
9  if (E.type == SDL_MOUSEBUTTONDOWN) {
10    SDL_SetWindowMouseGrab(Window, SDL_TRUE);
11  } else if (E.type == SDL_MOUSEBUTTONUP) {
12    SDL_SetWindowMouseGrab(Window, SDL_FALSE);
13  }
14}
15
16int main(int argc, char** argv) {
17  SDL_Init(SDL_INIT_VIDEO);
18  Window GameWindow;
19  SDL_Event E;
20
21  while (true) {
22    while (SDL_PollEvent(&E)) {
23      if (E.type == SDL_MOUSEBUTTONDOWN ||
24          E.type == SDL_MOUSEBUTTONUP) {
25        HandleMouseEvent(
26          E.button, GameWindow.SDLWindow
27        );
28      } else if (E.type == SDL_QUIT) {
29        SDL_Quit();
30        return 0;
31      }
32    }
33  }
34}

Constraining the Cursor within a Window

We can be more specific with our cursor constraint by restricting it to only a specific area of our window. To do this, we use the SDL_SetWindowMouseRect() function, passing a pointer to the SDL_Window and a pointer to the SDL_Rect.

An SDL_Rect is a simple structure that defines a rectangle using 4 integers:

1. The horizontal position of the top left corner of the rectangle
2. The vertical position of the top left corner of the rectangle
3. The width of the rectangle
4. The height of the rectangle

Below, we constrain the cursor to a 100x100 pixel square at the top left corner of our window:

1SDL_Window* Window{
2  SDL_CreateWindow(
3    "Hello Window",
4    100, 200, 300, 400, 0
5  )
6};
7
8SDL_Rect Rect{0, 0, 100, 100};
9SDL_SetWindowMouseRect(Window, &Rect);

SDL_SetWindowMouseRect() copies the SDL_Rect immediately, so we don’t need to ensure that our copy survives. It can safely be deleted after the SDL_SetWindowMouseRect() invocation and our cursor will remain constrained until we invoke the function again with a different pointer.

Releasing the Cursor

We can delete a window mouse rectangle we previously set by passing a nullptr to the second argument of SDL_SetWindowMouseRect():

1SDL_SetWindowMouseRect(Window, nullptr);

This will free the player’s mouse to navigate anywhere within our window (or anywhere at all, if our window hasn’t grabbed their mouse)

Error Checking

SDL_SetWindowMouseRect() is not always supported. It returns 0 if setting the window rectangle was successful, or a negative number if it failed. We can call SDL_GetError() for an explanation of why it failed:

1if(SDL_SetWindowMouseRect(Window, nullptr) < 0) {
2  std::cout << "Setting Window Rect Failed: "
3    << SDL_GetError();
4}

Getting the Mouse Rectangle

We can retrieve the mouse rectangle associated with a window by passing the SDL_Window* to SDL_GetWindowMouseRect().

This returns a pointer to the constant SDL_Rect, or a nullptr if there is no rectangle confining the cursor within the window:

1SDL_Window* Window{
2  SDL_CreateWindow(
3    "Hello Window",
4    100, 200, 300, 400, 0
5  )
6};
7
8SDL_Rect Rect{0, 0, 100, 100};
9SDL_SetWindowMouseRect(Window, &Rect);
10
11const SDL_Rect* WindowRect{
12  SDL_GetWindowMouseRect(Window)};
13  
14if (WindowRect) {
15  auto[x, y, w, h]{*WindowRect};
16  std::cout << "Cursor is confined: "
17    << x << ", " << y << ", " << w << ", " << h;
18} else {
19  std::cout << "Cursor is not confined";
20}

1Cursor is confined: 0, 0, 100, 100

Combining Mouse Grab with Mouse Rectangles

By default, setting the window mouse rectangle does not constrain the cursor to our window. Instead, it means that when the cursor is in our window (that is when our window has mouse focus), its position will be constrained to the rectangle provided.

If want to both constrain the cursor to our window, and specifically to a rectangle within that window, we can combine both SDL_SetWindowMouseRect() with mouse grabbing:

1#include <SDL.h>
2#include "Window.h"
3
4void HandleMouseEvent(
5  SDL_MouseButtonEvent& E, SDL_Window* Window
6) {
7  if (E.button != SDL_BUTTON_LEFT) return;
8
9  if (E.type == SDL_MOUSEBUTTONDOWN) {
10    SDL_Rect Rect{0, 0, 100, 100};
11    SDL_SetWindowMouseGrab(Window, SDL_TRUE);
12    SDL_SetWindowMouseRect(Window, &Rect);
13  } else if (E.type == SDL_MOUSEBUTTONUP) {
14    SDL_SetWindowMouseGrab(Window, SDL_FALSE);
15    SDL_SetWindowMouseRect(Window, nullptr);
16  }
17}
18
main Function|Show
19int main(int argc, char** argv) {/*...*/}

Summary

SDL2 offers tools for controlling mouse movement, allowing us to create more advanced input-handling systems for our applications.

Through window grabbing and rectangular constraints, we can precisely control where users can move their cursor. Key takeaways:

• Mouse grabbing can be enabled through window flags or SDL_SetWindowMouseGrab
• Rectangular constraints allow fine-grained control over cursor movement
• Both features can be combined for maximum control
• Mouse constraints can be dynamically toggled based on game state
• Attempts to constrain the mouse can fail, so we should consider adding error checking to react to these failures

Next Lesson

Mouse State

Learn how to monitor mouse position and button states in real-time using SDL's state query functions

ContinueView Course