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:

Screenshot showing windows with and without focus

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

View Related 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
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
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
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
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
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.

Using `SDL_SetWindowInputFocus()`

SDL includes the SDL_SetWindowInputFocus() function, which can be a bit confusing. In principle, we can use it the same way as SDL_RaiseWindow():

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
21int main(int argc, char** argv) {/*...*/}

However, in practice, this is rarely appropriate for two reasons:

It is not as widely supported across different platforms and will often have no effect
On platforms where it is supported, it does not bring the window into view if it is obscured by other applications. This can mean our user's keyboard input is being sent to a window they cannot see, which can be confusing.

The SDL_RaiseWindow() function alleviates both of these problems so, if we need to grab focus, we should prefer it over SDL_SetWindowInputFocus().

Keyboard Events and Input Focus

SDL only creates keyboard events if they happen when our application has focus. As such, when we're reacting to input using the event loop, we do not need to check if our window has input focus.

If we received the event, we can assume our application had focus when it happened, so the input was intended for our application.

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.

Managing Window Input Focus

Creating a Window with Input Focus

Bitwise Operators and Bit Flags

Detecting if a Window has Input Focus

Using `SDL_GetKeyboardFocus()`

Using the Event Loop

Grabbing Input Focus

Summary

Understanding Keyboard State

Game Development with SDL2

Questions & Answers

Managing Window Input Focus

Creating a Window with Input Focus

Bitwise Operators and Bit Flags

Detecting if a Window has Input Focus

Using SDL_GetKeyboardFocus()

Using the Event Loop

Grabbing Input Focus

Summary

Understanding Keyboard State

Questions & Answers

Using `SDL_GetKeyboardFocus()`