Mouse Capture and Global Mouse State

In our earlier lessons where we covered mouse events and mouse tracking, we were primarily concerned with what the mouse is doing whilst it is hovering over our windows. That is, when one of our windows has mouse focus.

However, in certain scenarios, we may need to understand what’s going on with the mouse even when we don’t have mouse focus. This lesson covers the techniques we can use to accomplish this, and some of the scenarios where we may need to.

Global Mouse State

We previously introduced the SDL_GetMouseState() function, which allows us to determine where the mouse is within our window.

The similar SDL_GetGlobalMouseState() function lets us find the cursor position, regardless of where it is on the user’s desktop. It has a familiar API - it accepts two pointers to integers, and will update those integers with the horizontal and vertical position of the cursor respectively:

1int x, y;
2SDL_GetGlobalMouseState(&x, &y);

Whilst SDL_GetMouseState() reports the position relative to the top-left of our window, SDL_GetGlobalMouseState() reports the position relative to the top-left corner of the primary display.

Note that this means that either of the coordinates can be negative. This can happen in multi-monitor setups, where the user has a display above and/or to the left of their primary display.

Similar to SDL_GetMouseState(), the SDL_GetGlobalMouseState() allows us to pass a nullptr to either argument. We’d use this if we only care about the mouse’s horizontal or vertical position:

1// We only care about the horizontal position
2int x;
3SDL_GetGlobalMouseState(&x, nullptr);

1// We only care about the vertical position
2int y;
3SDL_GetGlobalMouseState(nullptr, &y);

Button State

In addition to reporting the position of the mouse, the SDL_GetGlobalMouseState() function also lets us understand what buttons are currently pressed. It does this by return an unsigned integer, which acts as a bit-mask. We can use the & operator to examine individual bits to determine if specific buttons are pressed.

SDL includes the SDL_BUTTON_LMASK, SDL_BUTTON_MMASK, and SDL_BUTTON_RMASK to help us isolate the bits associated with the left, middle and right mouse buttons respectively:

1void LogMouseGlobalState() {
2  int x, y;
3  Uint32 Buttons{SDL_GetGlobalMouseState(&x, &y)};  
4
5  std::cout << "\nMouse Position: "
6    << x << ", " << y;
7  if (Buttons & SDL_BUTTON_LMASK) {
8    std::cout << " - Left Button is pressed";
9  }
10  if (Buttons & SDL_BUTTON_MMASK) {
11    std::cout << " - Middle Button is pressed";
12  }
13  if (Buttons & SDL_BUTTON_RMASK) {
14    std::cout << " - Right Button is pressed";
15  }
16}

Mouse Capture

Previously, we covered how SDL will only report mouse events like movement and button presses if the event happens when one of our windows has mouse focus. That is, when the user’s cursor is hovering over one of our windows:

1#include <SDL.h>
2#include <iostream>
3#include "Window.h"
4
5void HandleWindowEvent(SDL_WindowEvent& E) {
6  if (E.event == SDL_WINDOWEVENT_ENTER) {
7    std::cout << "Mouse Entered Window - "
8      "Tracking Resumed\n";
9  } else if (E.event == SDL_WINDOWEVENT_LEAVE) {
10    std::cout << "Mouse Left Window - "
11      "Tracking Stopped\n";
12  }
13}
14
15void HandleMouseMotion(SDL_MouseMotionEvent& E) {
16  std::cout << "Mouse moved to "
17    << E.x << ", " << E.y << '\n';
18}
19
20int main(int argc, char** argv) {
21  SDL_Init(SDL_INIT_VIDEO);
22  Window GameWindow;
23  SDL_Event E;
24
25  while (true) {
26    while (SDL_PollEvent(&E)) {
27      if (E.type == SDL_QUIT) {
28        SDL_Quit();
29        return 0;
30      }
31      if (E.type == SDL_WINDOWEVENT) {
32        HandleWindowEvent(E.window);
33      } else if (E.type == SDL_MOUSEMOTION) {
34        HandleMouseMotion(E.motion);
35      }
36    }
37
38    GameWindow.Update();
39  }
40}

1Mouse moved to 2, 120
2Mouse moved to 0, 120
3Mouse Left Window - Tracking Stopped
4Mouse Entered Window - Tracking Resumed
5Mouse moved to 1, 108
6Mouse moved to 2, 107

In some situations, we’d prefer mouse events be reported even when none of our windows have mouse focus. SDL refers to this as mouse capture, and we can enable it using the SDL_CaptureMouse() function.

We pass SDL_TRUE to enable capturing, or SDL_FALSE to disable it:

1// Enable mouse capture
2SDL_CaptureMouse(SDL_TRUE);
3
4// Disable mouse capture
5SDL_CaptureMouse(SDL_FALSE);

Enabling mouse capture for prolonged period of times is not recommended, as it can interfere with other windows the user might be interacting with. Instead, we typically enable mouse capture briefly for certain actions, and then disable it when those actions complete.

The most common use case for mouse capture is to support drag-and-drop interactions. For example, if we want to allow the user to drag something from one of our windows to another, there’s typically going to be a point in that action where neither of our windows have mouse focus.

Even if the user is dragging and dropping within the same window, their mouse may arc outside our window temporarily.

Without mouse capture, we may not be able to track the cursor when our windows do not have mouse focus. So instead, we’d typically enable mouse capture throughout that action to remove that restriction.

Getting Capture State

Enabling mouse capture requires that one of our windows has input focus (ie, keyboard focus). Additionally, if we lose input focus, then mouse capture is automatically disabled.

The SDL_WindowFlags bit set includes an SDL_WINDOW_MOUSE_CAPTURE flag. It’s unusual that we would enable this when creating our window, for the reasons we covered above about not enabling it until necessary.

However, this flag is still helpful, as we can retrieve the flags at any time and examine the SDL_WINDOW_MOUSE_CAPTURE bit to understand if we’re currently capturing the mouse.

1#include <SDL.h>
2#include <iostream>
3
4int main(int argc, char** argv) {
5  SDL_Init(SDL_INIT_VIDEO);
6  SDL_Window* Window{SDL_CreateWindow(
7    "Example Window",
8    SDL_WINDOWPOS_UNDEFINED,
9    SDL_WINDOWPOS_UNDEFINED,
10    400, 400, 0
11  )};
12
13  // Capture mouse
14  SDL_CaptureMouse(SDL_TRUE);
15  if (SDL_GetWindowFlags(Window)
16      & SDL_WINDOW_MOUSE_CAPTURE) {
17    std::cout << "Mouse is captured\n";
18  }
19
20  // Minimized windows lose input focus,
21  // so we will lose mouse capture too
22  SDL_MinimizeWindow(Window);
23  if (!(SDL_GetWindowFlags(Window)
24      & SDL_WINDOW_MOUSE_CAPTURE)) {
25    std::cout << "Mouse is no longer captured";
26  }
27
Game Loop|Show
38}

1Mouse is captured
2Mouse is no longer captured

Error Handling

SDL_CaptureMouse() returns 0 if it was successful, or a negative error code otherwise. We can use this to react to errors in the normal way, and call SDL_GetError() if we need a description of what went wrong.

The most common reasons enabling mouse capture will fail is that we didn’t have input focus when we tried to enable it, or it isn’t supported on the platform at all.

1if (SDL_CaptureMouse(SDL_TRUE) < 0) {
2  std::cout << "Error: " << SDL_GetError(); 
3}

1Error: No window has focus

Mouse Auto Capture

The drag-and-drop use case for enabling mouse capture is so common that, from version 2.0.22 of SDL, mouse capture is automatically enabled when the user holds down one of their mouse buttons.

The following program shows an example of this in action:

1#include <SDL.h>
2#include <iostream>
3
4int main(int argc, char** argv) {
5  SDL_Init(SDL_INIT_VIDEO);
6  SDL_Window* Window{SDL_CreateWindow(
7    "Example Window",
8    SDL_WINDOWPOS_UNDEFINED,
9    SDL_WINDOWPOS_UNDEFINED,
10    400, 400, 0
11  )};
12
13  SDL_Event E;
14  while (true) {
15    while (SDL_PollEvent(&E)) {
16      if (E.type == SDL_QUIT) {
17        SDL_Quit();
18        SDL_DestroyWindow(Window);
19        return 0;
20      }
21
22      if (E.type == SDL_MOUSEBUTTONDOWN) {
23        std::cout << "Mouse button down\n";
24      } else if (E.type == SDL_MOUSEBUTTONUP) {
25        std::cout << "Mouse button up\n";
26      }
27    }
28
29    std::cout << "Capturing Mouse: ";
30    if (SDL_GetWindowFlags(Window) & SDL_WINDOW_MOUSE_CAPTURE) {
31      std::cout << "true\n";
32    } else {
33      std::cout << "false\n";
34    }
35  }
36}

1Capturing Mouse: false
2Capturing Mouse: false
3Mouse button down
4Capturing Mouse: true
5Capturing Mouse: true
6Mouse button up
7Capturing Mouse: false

This behavior is controlled by the SDL_HINT_MOUSE_AUTO_CAPTURE hint. By default, it is set to "1", representing we want auto-capture to be enabled.

We can disable auto-capture by setting it to "0" using SDL_SetHint():

1#include <SDL.h>
2#include <iostream>
3
4int main(int argc, char** argv) {
5  SDL_Init(SDL_INIT_VIDEO);
6  SDL_Window* Window{SDL_CreateWindow(
7    "Some Window",
8    SDL_WINDOWPOS_UNDEFINED,
9    SDL_WINDOWPOS_UNDEFINED,
10    400, 400, 0
11  )};
12
13  SDL_SetHint(SDL_HINT_MOUSE_AUTO_CAPTURE, "0");
14
15  SDL_Event E;
16  while (true) {
Event Loop|Show
30
31    std::cout << "Capturing Mouse: ";
32    if (SDL_GetWindowFlags(Window) & SDL_WINDOW_MOUSE_CAPTURE) {
33      std::cout << "true\n";
34    } else {
35      std::cout << "false\n";
36    }
37  }
38}

1Capturing Mouse: false
2Capturing Mouse: false
3Mouse button down
4Capturing Mouse: false
5Capturing Mouse: false
6Mouse button up
7Capturing Mouse: false

Summary

SDL's mouse capture and global mouse state features let us track mouse movement and button states beyond our window boundaries. This lets us implement advanced mouse interactions like drag-and-drop. Key topics covered:

• Using SDL_GetGlobalMouseState() to track mouse position and button states across the entire desktop
• Understanding the difference between window-relative and global mouse coordinates
• Implementing mouse capture to maintain mouse event tracking outside window boundaries
• Managing automatic mouse capture during drag operations using SDL hints
• Handling common error cases and platform-specific considerations
• Distinguishing between mouse capture and mouse grab functionality

Next Lesson

Relative Mouse Mode

Learn how to restrict cursor movement to a window whilst capturing mouse motion continuously.

ContinueView Course