Managing Mouse Focus with SDL2

In desktop environments, users can have multiple windows open at once. On most platforms, only a single window can have input focus at a time, which is typically gained by the user clicking on the window:

This is referred to as input focus, and we covered it in more detail in our earlier lesson on keyboard input:

Managing Window Input Focus

Learn how to manage and control window input focus in SDL applications, including how to create, detect, and manipulate window focus states.

In this lesson, we’ll introduce the related concept of mouse focus. A window has mouse focus if the user’s pointer is currently hovering over it. The window with mouse focus is not necessarily the same as the window with input focus.

Tracking Mouse Focus Using the Event Loop

Let’s begin with a basic application loop. SDL dispatches window events (SDL_WindowEvent) when a window gains and loses mouse focus, so we’ll look out for those in our event loop:

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

We can check if the event specifically relates to a window gaining or losing focus by comparing the event property of the SDL_WindowEvent to SDL_WINDOWEVENT_ENTER or SDL_WINDOWEVENT_LEAVE respectively:

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\n";
8  } else if (E.event == SDL_WINDOWEVENT_LEAVE) {
9    std::cout << "Mouse Left Window\n";
10  }
11}
12
main Function|Show
13int main(int argc, char** argv) {/*...*/}

1Mouse Entered Window
2Mouse Left Window

SDL_GetWindowFlags()

As with most things in SDL, we don't need to monitor events to retrieve the state of its internally-managed objects, like an SDL_Window. Instead, we can directly query the state of those objects at any time.

SDL_Window objects keep track of whether or not they have focus within their window flags. As we covered in the previous chapter, we can access those flags by passing the SDL_Window pointer to SDL_GetWindowFlags():

1SDLWindow* Window{SDL_CreateWindow(
2  "Some Window",
3  200, 200,
4  700, 300, 0
5)};
6
7SDL_WindowFlags Flags{
8  SDL_GetWindowFlags(Window)
9};

The SDL_WindowFlags type is a bit mask in the form of a 32-bit unsigned integer. We can examine the state of any flag using the & operator. SDL provides the SDL_WINDOW_MOUSE_FOCUS helper to give us easy access to the flag that tracks whether the window has mouse focus:

1bool hasFocus{
2  SDL_GetWindowFlags(Window) &
3    SDL_WINDOW_MOUSE_FOCUS
4};

In practice, this state-checking approach is appropriate when we need to check if the window has focus as part of our reaction to some other event. The following example checks if our window has mouse focus when the user presses a keyboard button:

1#include <SDL.h>
2#include <iostream>
3#include "Window.h"
4
5void LogFocus(SDL_Window* Window) {
6  std::cout << "\nMouse focus: ";
7  if (SDL_GetWindowFlags(Window) &
8    SDL_WINDOW_MOUSE_FOCUS) {
9    std::cout << "yes";
10  } else {
11    std::cout << "no";
12  }
13}
14
15int main(int argc, char** argv) {
16  SDL_Init(SDL_INIT_VIDEO);
17  Window GameWindow;
18
19  SDL_Event E;
20  while (true) {
21    while (SDL_PollEvent(&E)) {
22      if (E.type == SDL_KEYDOWN) {
23        LogFocus(GameWindow.SDLWindow);
24      }
25    }
26    GameWindow.Update();
27  }
28
29  SDL_Quit();
30  return 0;
31}

1Mouse focus: no
2Mouse focus: no
3Mouse focus: yes

In the following example, we create a timer that checks every second (1,000 milliseconds) if our window has mouse focus:

1#include <SDL.h>
2#include <iostream>
3#include "Window.h"
4
5Uint32 MonitorWindow(Uint32 Timer, void* Win) {
6  auto* Window{static_cast<SDL_Window*>(Win)};
7
8  if (SDL_GetWindowFlags(Window) &
9    SDL_WINDOW_MOUSE_FOCUS) {
10    std::cout << "Focus\n";
11  } else {
12    std::cout << "No Focus\n";
13  }
14
15  return Timer;
16}
17
main Function|Show
18int main(int argc, char** argv) {/*...*/}

1No Focus
2Focus
3Focus

SDL_GetMouseFocus()

SDL also provides the SDL_GetMouseFocus() function, which returns the SDL_Window* with mouse focus, or a nullptr if no window has focus.

This example is very similar to the previous one, except we’ve updated our implementation to use SDL_GetMouseFocus() instead of SDL_GetWindowFlags().

1#include <SDL.h>
2#include <iostream>
3#include "Window.h"
4
5Uint32 MonitorWindow(Uint32 Timer, void* Win) {
6  auto* Window{static_cast<SDL_Window*>(Win)};
7
8  if (Window == SDL_GetMouseFocus()) {
9    std::cout << "Focus\n";
10  } else {
11    std::cout << "No Focus\n";
12  }
13  return Timer;
14}
15
main Function|Show
16int main(int argc, char** argv) {/*...*/}

1No Focus
2Focus
3Focus

Whilst the SDL_GetWindowFlags() example lets us determine if a specific window has focus, SDL_GetMouseFocus() is primarily useful when we want to know which window has focus. This is typically used in applications where we manage multiple windows, including utility windows.

The following program creates two windows and, on every iteration of our application loop, reports which one of them has mouse focus:

1#include <SDL.h>
2#include <iostream>
3#include "Window.h"
4
5int main(int argc, char** argv) {
6  SDL_Init(SDL_INIT_VIDEO);
7  Window Window1;
8  Window Window2;
9
10  SDL_Event E;
11  while (true) {
12    while (SDL_PollEvent(&E)) {
13      // ...
14    }
15
16    SDL_Window* Focused{SDL_GetMouseFocus()};
17
18    if (Focused == Window1.SDLWindow) {
19      std::cout << "Window 1 has focus\n";
20    } else if (Focused == Window2.SDLWindow) {
21      std::cout << "Window 2 has focus\n";
22    } else {
23      std::cout << "Neither has focus\n";
24    }
25
26    Window1.Update();
27    Window2.Update();
28  }
29
30  SDL_Quit();
31  return 0;
32}

1Window 1 has focus
2Window 1 has focus
3Neither has focus
4Window 2 has focus

Click Events when Switching Input Focus

The most common way a user will switch their input focus is by left-clicking on the window with their mouse. By default, SDL does not report these clicks - you won't get a mouse click event when the user clicks to set input focus to your window.

This is typically a sensible default for games. For example, if we’re working on a first-person shooter, we want players to be able to switch focus to our window by clicking on it, and we won’t want that click to also fire their weapon.

However, we can change this behavior by setting the SDL_HINT_MOUSE_FOCUS_CLICKTHROUGH hint to "1":

1#include <SDL.h>
2#include <iostream>
3#include "Window.h"
4
5int main(int argc, char** argv) {
6  SDL_SetHint(
7    SDL_HINT_MOUSE_FOCUS_CLICKTHROUGH,
8    "1"
9  );
10  SDL_Init(SDL_INIT_VIDEO);
11  Window GameWindow;
12
13  SDL_Event E;
14
15  while (true) {
16    while (SDL_PollEvent(&E)) {
17      switch (E.type) {
18      case SDL_WINDOWEVENT:
19        if (E.window.event ==
20          SDL_WINDOWEVENT_FOCUS_GAINED) {
21          std::cout << "Input Focus Event\n";
22        }
23        break;
24
25      case SDL_MOUSEBUTTONDOWN:
26        if (E.button.button ==
27          SDL_BUTTON_LEFT) {
28          std::cout << "Also a Click Event\n";
29        }
30        break;
31
32      default:
33        break;
34      }
35    }
36    GameWindow.Update();
37  }
38
39  SDL_Quit();
40  return 0;
41}

1Input Focus Event
2Also a Click Event

We can set it to "0" to restore the default behavior:

1SDL_SetHint(
2  SDL_HINT_MOUSE_FOCUS_CLICKTHROUGH,
3  "0"
4);

Summary

Mouse focus management is crucial for creating responsive multi-window applications in SDL2, allowing you to track which window the mouse is hovering over and respond appropriately. Here are the key topics covered:

• Using SDL_WindowEvent to detect when the mouse enters or leaves a window
• Checking window focus state using SDL_GetWindowFlags() and the SDL_WINDOW_MOUSE_FOCUS flag
• Using SDL_GetMouseFocus() to determine which window currently has mouse focus
• Customizing click-through behavior during focus changes with SDL_HINT_MOUSE_FOCUS_CLICKTHROUGH

Next Lesson

Mouse Input Constraints

Implement mouse constraints in SDL2 to control cursor movement using window grabs and rectangular bounds

ContinueView Course