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:

Screenshot showing windows with and without focus

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

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.

Starting Point

This lesson builds upon our previous work. To keep the focus on mouse focus, the starting point below uses a minimal main.cpp and Window.h. We've removed the scroll-specific event handling from the previous lesson.

Files

src

Select a file to view its content

Tracking Mouse Focus Using the Event Loop

Let's begin with a basic application loop. When a window gains or loses mouse focus, SDL dispatches top-level events that we can detect in our event loop.

We can check if an event is related to a window gaining or losing focus by comparing the type of the SDL_Event to SDL_EVENT_WINDOW_MOUSE_ENTER or SDL_EVENT_WINDOW_MOUSE_LEAVE respectively:

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  SDL_Event E;
10
11  bool IsRunning = true;
12  while (IsRunning) {
13    while (SDL_PollEvent(&E)) {
14      if (E.type == SDL_EVENT_WINDOW_MOUSE_ENTER) {
15        std::cout << "Mouse Entered Window\n";
16      } else if (E.type == SDL_EVENT_WINDOW_MOUSE_LEAVE) {
17        std::cout << "Mouse Left Window\n";
18      } else if (E.type == SDL_EVENT_QUIT) {
19        IsRunning = false;
20      }
21    }
22    GameWindow.Render();
23    GameWindow.Update();
24  }
25
26  SDL_Quit();
27  return 0;
28}

1Mouse Entered Window
2Mouse Left Window

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

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

The SDL_WindowFlags type is a bit mask. 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) != 0
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:

src/main.cpp

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

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:

src/main.cpp

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include <iostream>
4#include "Window.h"
5
6Uint32 MonitorWindow(
7  void* Win, SDL_TimerID timerID, Uint32 interval
8) {
9  auto* Window{static_cast<SDL_Window*>(Win)};
10
11  if ((SDL_GetWindowFlags(Window) &
12    SDL_WINDOW_MOUSE_FOCUS) != 0) {
13    std::cout << "Focus\n";
14  } else {
15    std::cout << "No Focus\n";
16  }
17
18  return interval;
19}
20
21int main(int, char**) {
22  SDL_Init(SDL_INIT_VIDEO);
23  Window GameWindow;
24
25  SDL_AddTimer(1000, MonitorWindow,
26               GameWindow.GetRaw());
27
28  SDL_Event E;
29  bool IsRunning = true;
30  while (IsRunning) {
31    while (SDL_PollEvent(&E)) {
32      if (E.type == SDL_EVENT_QUIT) {
33        IsRunning = false;
34      }
35    }
36    GameWindow.Render();
37    GameWindow.Update();
38  }
39
40  SDL_Quit();
41  return 0;
42}

1No Focus
2Focus
3Focus

Using `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().

src/main.cpp

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include <iostream>
4#include "Window.h"
5
6Uint32 MonitorWindow(
7  void* Win, SDL_TimerID timerID, Uint32 interval
8) {
9  auto* Window{static_cast<SDL_Window*>(Win)};
10
11  if (Window == SDL_GetMouseFocus()) {
12    std::cout << "Focus\n";
13  } else {
14    std::cout << "No Focus\n";
15  }
16  return interval;
17}
18
19int main(int, char**) {
20  SDL_Init(SDL_INIT_VIDEO);
21  Window GameWindow;
22  SDL_AddTimer(1000, MonitorWindow,
23               GameWindow.GetRaw());
24
25  SDL_Event E;
26  bool IsRunning = true;
27  while (IsRunning) {
28    while (SDL_PollEvent(&E)) {
29      if (E.type == SDL_EVENT_QUIT) {
30        IsRunning = false;
31      }
32    }
33    GameWindow.Render();
34    GameWindow.Update();
35  }
36
37  SDL_Quit();
38  return 0;
39}

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:

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 Window1;
9  Window Window2;
10
11  SDL_Event E;
12  bool IsRunning = true;
13  while (IsRunning) {
14    while (SDL_PollEvent(&E)) {
15      if (E.type == SDL_EVENT_QUIT) {
16        IsRunning = false;
17      }
18    }
19
20    SDL_Window* Focused{SDL_GetMouseFocus()};
21
22    if (Focused == Window1.GetRaw()) {
23      std::cout << "Window 1 has focus\n";
24    } else if (Focused == Window2.GetRaw()) {
25      std::cout << "Window 2 has focus\n";
26    } else {
27      std::cout << "Neither has focus\n";
28    }
29    
30    Window1.Render();
31    Window2.Render();
32
33    Window1.Update();
34    Window2.Update();
35  }
36
37  SDL_Quit();
38  return 0;
39}

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

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_SetHint(
8    SDL_HINT_MOUSE_FOCUS_CLICKTHROUGH,
9    "1"
10  );
11  SDL_Init(SDL_INIT_VIDEO);
12  Window GameWindow;
13
14  SDL_Event E;
15  bool IsRunning = true;
16  while (IsRunning) {
17    while (SDL_PollEvent(&E)) {
18      if (E.type == SDL_EVENT_WINDOW_FOCUS_GAINED) {
19        std::cout << "Got an Input Focus Event\n";
20      } else if (E.type == SDL_EVENT_MOUSE_BUTTON_DOWN) {
21        if (E.button.button == SDL_BUTTON_LEFT) {
22          std::cout << "Also got a Click Event\n";
23        }
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}

1Got an Input Focus Event
2Also got 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 important for handling mouse interaction, particularly multi-window applications. Here are the key topics covered:

Use SDL_EVENT_WINDOW_MOUSE_ENTER and SDL_EVENT_WINDOW_MOUSE_LEAVE to detect when the mouse enters or leaves a window.
Check window focus state using SDL_GetWindowFlags() and the SDL_WINDOW_MOUSE_FOCUS flag.
Use SDL_GetMouseFocus() to determine which window currently has mouse focus.
Customize click-through behavior during focus changes with SDL_HINT_MOUSE_FOCUS_CLICKTHROUGH.

Managing Mouse Focus

Starting Point

Files

Tracking Mouse Focus Using the Event Loop

src/main.cpp

Using `SDL_GetWindowFlags()`

src/main.cpp

src/main.cpp

Using `SDL_GetMouseFocus()`

src/main.cpp

src/main.cpp

Click Events when Switching Input Focus

src/main.cpp

Summary

Mouse Input Constraints

Game Development with SDL3

Managing Mouse Focus

Starting Point

Files

Tracking Mouse Focus Using the Event Loop

src/main.cpp

Using SDL_GetWindowFlags()

src/main.cpp

src/main.cpp

Using SDL_GetMouseFocus()

src/main.cpp

src/main.cpp

Click Events when Switching Input Focus

src/main.cpp

Summary

Mouse Input Constraints

Using `SDL_GetWindowFlags()`

Using `SDL_GetMouseFocus()`