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:

Screenshot showing windows with and without focus

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.

In this lesson, we'll learn how to interact with this mechanism using SDL.

Starting Point

This lesson builds on our earlier work. We'll start with a minimal project containing a Window class and a main function with a basic application loop if you want to follow along.

Note that we've added a GetRaw() function to our Window class, which returns the underlying SDL_Window pointer that it manages:

Files

src

Select a file to view its content

Creating a Window with Input Focus

On most platforms, a newly opened window will have input focus by default, but we can explicitly specify this as a requirement if we wish.

The SDL_WindowFlags mask includes a bit dedicated to whether or not the window has input focus. In SDL3, this flag is named SDL_WINDOW_INPUT_FOCUS.

We can specify that our window should have input focus as soon as it is created by providing this flag to SDL_CreateWindow():

src/Window.h

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

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", 700, 300,
3  SDL_WINDOW_INPUT_FOCUS | SDL_WINDOW_RESIZABLE  
4);

You can learn more about this technique in our .

Detecting if a Window has Input Focus

SDL keeps the window flags updated throughout 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.

SDL_GetWindowFlags() returns a bitmask as an SDL_WindowFlags type, which is a 64-bit unsigned integer in SDL3:

src/main.cpp

1#include <iostream>
2#include <SDL3/SDL.h>
3#include <SDL3/SDL_main.h>
4#include "Window.h"
5
6int main(int, char**) {
7  SDL_Init(SDL_INIT_VIDEO);
8  Window GameWindow;
9  SDL_Event Event;
10
11  std::cout << "Window Flags: "
12    << SDL_GetWindowFlags(GameWindow.GetRaw());
13
14  bool IsRunning = true;
15  while (IsRunning) {
16    while (SDL_PollEvent(&Event)) {
17      if (Event.type == SDL_EVENT_QUIT) {
18        IsRunning = false;
19      }
20    }
21    GameWindow.Render();
22    GameWindow.Update();
23  }
24
25  SDL_Quit();
26  return 0;
27}

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:

src/main.cpp

1#include <iostream>
2#include <SDL3/SDL.h>
3#include <SDL3/SDL_main.h>
4#include "Window.h"
5
6int main(int, char**) {
7  SDL_Init(SDL_INIT_VIDEO);
8  Window GameWindow;
9  SDL_Event Event;
10
11  SDL_WindowFlags Flags{
12    SDL_GetWindowFlags(GameWindow.GetRaw())};
13
14  if (Flags & SDL_WINDOW_INPUT_FOCUS) {
15    std::cout << "Window has input focus";
16  }
17
18  bool IsRunning = true;
19  while (IsRunning) {
20    while (SDL_PollEvent(&Event)) {
21      if (Event.type == SDL_EVENT_QUIT) {
22        IsRunning = false;
23      }
24    }
25    GameWindow.Render();
26    GameWindow.Update();
27  }
28
29  SDL_Quit();
30  return 0;
31}

1Window has input focus

Using `SDL_GetKeyboardFocus()`

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

src/main.cpp

1#include <iostream>
2#include <SDL3/SDL.h>
3#include <SDL3/SDL_main.h>
4#include "Window.h"
5
6int main(int, char**) {
7  SDL_Init(SDL_INIT_VIDEO);
8  Window GameWindow;
9  SDL_Event Event;
10
11  std::cout << "Window with focus: "
12    << SDL_GetKeyboardFocus();
13
14  bool IsRunning = true;
15  while (IsRunning) {
16    while (SDL_PollEvent(&Event)) {
17      if (Event.type == SDL_EVENT_QUIT) {
18        IsRunning = false;
19      }
20    }
21    GameWindow.Render();
22    GameWindow.Update();
23  }
24
25  SDL_Quit();
26  return 0;
27}

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:

src/main.cpp

1#include <iostream>
2#include <SDL3/SDL.h>
3#include <SDL3/SDL_main.h>
4#include "Window.h"
5
6int main(int, char**) {
7  SDL_Init(SDL_INIT_VIDEO);
8  Window GameWindow;
9  SDL_Event Event;
10
11  SDL_Window* Focused{SDL_GetKeyboardFocus()};
12
13  if (Focused == GameWindow.GetRaw()) {  
14    std::cout << "GameWindow has input focus";
15  }
16
17  bool IsRunning = true;
18  while (IsRunning) {
19    while (SDL_PollEvent(&Event)) {
20      if (Event.type == SDL_EVENT_QUIT) {
21        IsRunning = false;
22      }
23    }
24    GameWindow.Render();
25    GameWindow.Update();
26  }
27
28  SDL_Quit();
29  return 0;
30}

1GameWindow has input focus

Using the Event Loop

We can also keep track of whether our window has focus using the event loop. In SDL3, window events are top-level events. When our window gains or loses focus, SDL broadcasts SDL_EVENT_WINDOW_FOCUS_GAINED and SDL_EVENT_WINDOW_FOCUS_LOST events.

We can be on the lookout for these event types in our event loop:

src/main.cpp

1#include <iostream>
2#include <SDL3/SDL.h>
3#include <SDL3/SDL_main.h>
4#include "Window.h"
5
6void HandleWindowEvent(const SDL_WindowEvent& E) {
7  if (E.type == SDL_EVENT_WINDOW_FOCUS_GAINED) {
8    std::cout << "Window gained input focus\n";
9  }
10  if (E.type == SDL_EVENT_WINDOW_FOCUS_LOST) {
11    std::cout << "Window lost input focus\n";
12  }
13}
14
15int main(int, char**) {
16  SDL_Init(SDL_INIT_VIDEO);
17  Window GameWindow;
18  SDL_Event Event;
19
20  bool IsRunning = true;
21  while (IsRunning) {
22    while (SDL_PollEvent(&Event)) {
23      if (Event.type == SDL_EVENT_WINDOW_FOCUS_GAINED ||
24          Event.type == SDL_EVENT_WINDOW_FOCUS_LOST
25      ) {
26        HandleWindowEvent(Event.window);
27      } else if (Event.type == SDL_EVENT_QUIT) {
28        IsRunning = false;
29      }
30    }
31    GameWindow.Render();
32    GameWindow.Update();
33  }
34
35  SDL_Quit();
36  return 0;
37}

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.GetRaw()};
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 stops responding for 5 seconds after losing input focus, and then automatically automatically grabs it back using SDL_RaiseWindow().

The SDL_WindowEvent struct contains a windowID, which we can use with SDL_GetWindowFromID() to retrieve the SDL_Window* associated with that event:

src/main.cpp

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

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

Flashing Windows

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 lets 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.

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.

src/main.cpp

1#include <iostream>
2#include <SDL3/SDL.h>
3#include <SDL3/SDL_main.h>
4#include <chrono>
5#include <thread>
6#include "Window.h"
7
8void HandleKeyboardEvent(const SDL_KeyboardEvent& E) {
9  std::cout << "Keyboard input detected\n";
10}
11
12void HandleWindowEvent(const SDL_WindowEvent& E) {
13  if (E.type == SDL_EVENT_WINDOW_FOCUS_GAINED) {
14    std::cout << "Window gained input focus\n";
15  }
16  if (E.type == SDL_EVENT_WINDOW_FOCUS_LOST) {
17    std::cout << "Window lost input focus\n";
18  }
19}
20
21int main(int, char**) {
22  SDL_Init(SDL_INIT_VIDEO);
23  Window GameWindow;
24  SDL_Event Event;
25
26  bool IsRunning = true;
27  while (IsRunning) {
28    while (SDL_PollEvent(&Event)) {
29      if (Event.type == SDL_EVENT_WINDOW_FOCUS_GAINED ||
30          Event.type == SDL_EVENT_WINDOW_FOCUS_LOST) {
31        HandleWindowEvent(Event.window);
32      } else if (Event.type == SDL_EVENT_KEY_DOWN) {
33        HandleKeyboardEvent(Event.key);
34      } else if (Event.type == SDL_EVENT_QUIT) {
35        IsRunning = false;
36      }
37    }
38    GameWindow.Render();
39    GameWindow.Update();
40  }
41
42  SDL_Quit();
43  return 0;
44}

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. The key takeaways include:

Creating windows with initial input focus using the SDL_WINDOW_KEYBOARD_FOCUS window flag.
Detecting if a window has input focus using SDL_GetWindowFlags() and SDL_GetKeyboardFocus().
Handling window focus events in the event loop by checking for SDL_EVENT_WINDOW_FOCUS_GAINED and SDL_EVENT_WINDOW_FOCUS_LOST.
Using SDL_RaiseWindow() to grab input focus and bring the window to the front.
Reacting to keyboard events when the window has input focus.

Managing Window Input Focus

Starting Point

Files

Creating a Window with Input Focus

src/Window.h

Detecting if a Window has Input Focus

src/main.cpp

src/main.cpp

Using `SDL_GetKeyboardFocus()`

src/main.cpp

src/main.cpp

Using the Event Loop

src/main.cpp

Grabbing Input Focus

src/main.cpp

Flashing Windows

Keyboard Events and Input Focus

src/main.cpp

Summary

Understanding Keyboard State

Game Development with SDL3

Managing Window Input Focus

Starting Point

Files

Creating a Window with Input Focus

src/Window.h

Detecting if a Window has Input Focus

src/main.cpp

src/main.cpp

Using SDL_GetKeyboardFocus()

src/main.cpp

src/main.cpp

Using the Event Loop

src/main.cpp

Grabbing Input Focus

src/main.cpp

Flashing Windows

Keyboard Events and Input Focus

src/main.cpp

Summary

Understanding Keyboard State

Using `SDL_GetKeyboardFocus()`