Managing Window Input Focus

On most platforms, multiple applications can be open at once. However, when the user is providing input on their keyboard, they typically only intend to provide that input to one of the open applications.

Users can select which application is active by, for example, clicking within its window.

Operating systems typically apply more vibrant styling to the active window. In the following example, the left window is inactive, while the right is active.

Accordingly, the user will not expect the left window to react to keyboard events, as their input is likely intended for the right window instead:

Creating a Window with Input Focus

The SDL_WindowFlags mask includes a bit dedicated to whether or not the window has input focus. The SDL_WINDOW_INPUT_FOCUS variable is available to represent this bit.

Accordingly, we can specify that our window should have input focus as soon as it is created by using this variable with SDL_CreateWindow():

1// Window.h
2#pragma once
3#include <SDL.h>
4
5class Window {
6public:
7  Window(){
8    SDLWindow = SDL_CreateWindow(
9      "Hello Window",
10      100, 100, 700, 300,
11      SDL_WINDOW_INPUT_FOCUS  
12    );
13  }
14  // ...
15private:
16  SDL_Window* SDLWindow{nullptr};
17  // ...
18};

We can combine SDL_WINDOW_INPUT_FOCUS with other window flags using the | operator. For example, to create a window that is both resizable and grabs focus when created, we could use this:

1SDL_CreateWindow(
2  "Hello Window", 100, 100, 700, 300,
3  SDL_WINDOW_INPUT_FOCUS | SDL_WINDOW_RESIZABLE  
4);

Bitwise Operators and Bit Flags

Unravel the fundamentals of bitwise operators and bit flags in this practical lesson

Detecting if a Window has Input Focus

SDL keeps the window flags bitset up to date through the lifecycle of our program. We can get the current window flags at any time using the SDL_GetWindowFlags() function. We pass the pointer to our window - that is, the SDL_Window* value returned from SDL_CreateWindow():

SDL_GetWindowFlags() returns a bit mask in the form of a Uint32 (a 32-bit unsigned integer):

1#include <iostream>
2#include <SDL.h>
3#include "Window.h"
4
5int main(int argc, char** argv) {
6  SDL_Init(SDL_INIT_VIDEO);
7  Window GameWindow;
8  SDL_Event Event;
9  
10  std::cout << "Window Flags: "
11    << SDL_GetWindowFlags(GameWindow.SDLWindow);
12
Event Loop|Show
13  while (true) {/*...*/}
19
20  SDL_Quit();
21  return 0;
22}

1Window Flags: 516

We can use the value returned by this function with the & operator to determine if any flag is currently set, Below, we use this technique to determine if the window currently has input focus:

1#include <iostream>
2#include <SDL.h>
3#include "Window.h"
4
5int main(int argc, char** argv) {
6  SDL_Init(SDL_INIT_VIDEO);
7  Window GameWindow;
8  SDL_Event Event;
9
10  Uint32 Flags{
11    SDL_GetWindowFlags(GameWindow.SDLWindow)};
12
13  if (Flags & SDL_WINDOW_INPUT_FOCUS) {
14    std::cout << "Window has input focus";
15  }
16
Event Loop|Show
17  while (true) {/*...*/}
23
24  SDL_Quit();
25  return 0;
26}

1Window has input focus

Using SDL_GetKeyboardFocus()

Alternatively, we can determine which window currently has focus using the GetKeyboardFocus() function:

1#include <iostream>
2#include <SDL.h>
3#include "Window.h"
4
5int main(int argc, char** argv) {
6  SDL_Init(SDL_INIT_VIDEO);
7  Window GameWindow;
8  SDL_Event Event;
9
10  std::cout << "Window with focus: "
11    << SDL_GetKeyboardFocus();
12
Event Loop|Show
13  while (true) {/*...*/}
19
20  SDL_Quit();
21  return 0;
22}

1Window with focus: 0000022391741BF8

This returns a SDL_Window*, which we can compare to any other SDL_Window* to understand whether or not it has focus:

1#include <iostream>
2#include <SDL.h>
3#include "Window.h"
4
5int main(int argc, char** argv) {
6  SDL_Init(SDL_INIT_VIDEO);
7  Window GameWindow;
8  SDL_Event Event;
9
10  SDL_Window* Focused{SDL_GetKeyboardFocus()};
11
12  if (Focused == GameWindow.SDLWindow) {  
13    std::cout << "GameWindow has input focus";
14  }
15
Event Loop|Show
16  while (true) {/*...*/}
22
23  SDL_Quit();
24  return 0;
25}

1GameWindow has input focus

Using the Event Loop

We can also keep track of whether or not our window has focus using the event loop. When our window gains or loses focus, SDL broadcasts an SDL_WINDOWEVENT.

To determine whether the event was caused by a window gaining or losing input focus, we can compare the Event.window.event property to SDL_WINDOWEVENT_FOCUS_GAINED and SDL_WINDOWEVENT_FOCUS_LOST constants respectively:

1#include <iostream>
2#include <SDL.h>
3#include "Window.h"
4
5void HandleWindowEvent(SDL_WindowEvent& E) {
6  if (E.event == SDL_WINDOWEVENT_FOCUS_GAINED) {
7    std::cout << "Window gained input focus\n";
8  }
9  if (E.event == SDL_WINDOWEVENT_FOCUS_LOST) {
10    std::cout << "Window lost input focus\n";
11  }
12}
13
14int main(int argc, char** argv) {
15  SDL_Init(SDL_INIT_VIDEO);
16  Window GameWindow;
17  SDL_Event Event;
18
19  while (true) {
20    while (SDL_PollEvent(&Event)) {
21      if (Event.type == SDL_WINDOWEVENT)
22        HandleWindowEvent(Event.window);
23    }
24  }
25
26  SDL_Quit();
27  return 0;
28}

1Window gained input focus
2Window lost input focus
3Window gained input focus

Grabbing Input Focus

When we want input focus to shift to our application, we can use the SDL_RaiseWindow() function, passing a pointer to our SDL_Window:

1SDL_Window* MyWindow{GameWindow.SDLWindow};
2SDL_RaiseWindow(MyWindow);

In addition to grabbing focus, SDL_RaiseWindow() will also move the window to be in front of any other windows that might be obscuring it. This ensures the user is aware that it has taken focus, and will now be handling their input.

In the following example, our window automatically grabs input focus 5 seconds after it loses it. Window events have a windowID property, representing which window caused the event. We can pass this ID to the SDL_GetWindowFromID() function to retrieve the SDL_Window* associated with that ID:

1#include <iostream>
2#include <SDL.h>
3#include <chrono>
4#include <thread>
5#include "Window.h"
6
7void HandleWindowEvent(SDL_WindowEvent& E) {
8  if (E.event == SDL_WINDOWEVENT_FOCUS_GAINED) {
9    std::cout << "Window gained input focus\n";
10  }
11  if (E.event == SDL_WINDOWEVENT_FOCUS_LOST) {
12    std::cout << "Window lost input focus\n";
13
14    using namespace std::chrono_literals;
15    std::this_thread::sleep_for(5s);
16    SDL_RaiseWindow(SDL_GetWindowFromID(E.windowID));
17  }
18}
19
Main Function|Show
20int main(int argc, char** argv) {/*...*/}

1Window gained input focus
2Window lost input focus
3Window gained input focus

Flashing Windows

Naturally, we should be cautious with grabbing input focus. Having our application jump to the top and grab focus is disruptive for users and is rarely warranted.

Most platforms provide a mechanism for windows to request the user’s attention in less disruptive ways. This is called "flashing" the window, but the specific visual effect that "flashing" has varies from platform to platform.

On Windows, for example, flashing a window means it will be highlighted with a colored blinking animation in the user’s task bar:

The SDL_FlashWindow() function let’s us access these attention-grabbing mechanisms:

1SDL_FlashWindow(Window, SDL_FLASH_BRIEFLY);

Our first argument is the SDL_Window* we want to attract attention, and the second argument is one of three possible values:

• SDL_FLASH_BRIEFLY - Briefly flash the window to attract attention
• SDL_FLASH_UNTIL_FOCUSED - Attract attention continuously until the user focuses our window, or until we cancel the flashing
• SDL_FLASH_CANCEL - Stop flashing

We cover window management in more detail in a dedicated chapter later in the course.

1#include <iostream>
2#include <SDL.h>
3#include <chrono>
4#include <thread>
5#include "Window.h"
6
7void HandleWindowEvent(SDL_WindowEvent& E) {
8  if (E.event == SDL_WINDOWEVENT_FOCUS_GAINED) {
9    std::cout << "Window gained input focus\n";
10  }
11  if (E.event == SDL_WINDOWEVENT_FOCUS_LOST) {
12    std::cout << "Window lost input focus\n";
13
14    using namespace std::chrono_literals;
15    std::this_thread::sleep_for(5s);
16    SDL_SetWindowInputFocus(
17      SDL_GetWindowFromID(E.windowID));
18  }
19}
20
Main Function|Show
21int main(int argc, char** argv) {/*...*/}

1#include <iostream>
2#include <SDL.h>
3#include <chrono>
4#include <thread>
5#include "Window.h"
6
7void HandleKeyboardEvent(SDL_KeyboardEvent& E) {
8  std::cout << "Keyboard input detected\n";
9}
10
11void HandleWindowEvent(SDL_WindowEvent& E) {
12  if (E.event == SDL_WINDOWEVENT_FOCUS_GAINED) {
13    std::cout << "Window gained input focus\n";
14  }
15  if (E.event == SDL_WINDOWEVENT_FOCUS_LOST) {
16    std::cout << "Window lost input focus\n";
17  }
18}
19
20int main(int argc, char** argv) {
21  SDL_Init(SDL_INIT_VIDEO);
22  Window GameWindow;
23  SDL_Event Event;
24
25  while (true) {
26    while (SDL_PollEvent(&Event)) {
27      if (Event.type == SDL_WINDOWEVENT)
28        HandleWindowEvent(Event.window);
29      if (Event.type == SDL_KEYDOWN)
30        HandleKeyboardEvent(Event.key);
31    }
32  }
33
34  SDL_Quit();
35  return 0;
36}

1Window gained input focus
2Keyboard input detected
3Keyboard input detected
4Keyboard input detected
5Window lost input focus
6Window gained input focus
7Keyboard input detected

Summary

In this lesson, we explored how to manage window input focus using SDL. The key takeaways include:

• Creating windows with input focus using SDL_CreateWindow().
• Detecting if a window has input focus using SDL_GetWindowFlags() and SDL_GetKeyboardFocus().
• Handling window focus events in the event loop.
• Using SDL_RaiseWindow() to grab input focus and bring the window to the front.
• Understanding the limitations of SDL_SetWindowInputFocus().
• Reacting to keyboard events when the window has input focus.

Next Lesson

Understanding Keyboard State

Learn how to detect and handle keyboard input in SDL2 using both event-driven and polling methods. This lesson covers obtaining and interpreting the keyboard state array.

ContinueView Course