Handling Keyboard Input

In this lesson, we will cover in detail how we can detect and react to the user providing input to our application using their keyboard. Similar to other forms of input, when SDL detects keyboard interaction, it pushes events into the event queue. We can capture these events through our event loop, and handle them as needed.

This lesson builds on our earlier work, where we have a Window class that initializes SDL and creates a window:

1// Window.h
2#pragma once
3#include <SDL.h>
4
5class Window {
6public:
7  Window() {
8    SDLWindow = SDL_CreateWindow(
9      "My Program", SDL_WINDOWPOS_UNDEFINED,
10      SDL_WINDOWPOS_UNDEFINED, 600, 300, 0);
11  }
12
13  void Update() {
14    SDL_UpdateWindowSurface(SDLWindow);
15  }
16
17  SDL_Surface* GetSurface() {
18    return SDL_GetWindowSurface(SDLWindow);
19  }
20
21  ~Window() { SDL_DestroyWindow(SDLWindow); }
22  
23  Window(const Window&) = delete;
24  Window& operator=(const Window&) = delete;
25
26private:
27  SDL_Window* SDLWindow;
28};

We also have a main function implementing a basic application loop:

1// main.cpp
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  while(true) {
11    while(SDL_PollEvent(&Event)) {
12      // Detect and handle input events
13      // ...
14    }
15    GameWindow.Update();
16  }
17
18  SDL_Quit();
19  return 0;
20}

Our SDL_PollEvent(&Event) statement will update our Event object with any keyboard action that the user performs. We’ll then detect and react to those actions within the body of the loop.

Keyboard Button Events

The two most common event types for handling the keyboard are SDL_KEYDOWN, which is created when a button is pressed, and SDL_KEYUP, for when a button is released.

1while (SDL_PollEvent(&Event)) {
2  if (Event.type == SDL_KEYDOWN) {
3    // ...
4  } else if (Event.type == SDL_KEYUP) {
5    // ...
6  }
7}

To find out which button was pressed or released, we need to check the key code. If we have an object called Event whose type is SDL_Event, and the Event.type member variable is SDL_KEYUP or SDL_KEYDOWN, we can access the key code using Event.key.keysym.sym:

1while (SDL_PollEvent(&Event)) {
2  if (Event.type == SDL_KEYDOWN) {
3    std::cout << "Key: " << Event.key.keysym.sym;
4  }
5}

1Key: 32

Key codes are basic integers, but SDL provides variables to help us understand which keys these integers represent. These variables are identified by the SDLK_ prefix. For example, the integer that represents the spacebar is available as SDLK_SPACE

1while (SDL_PollEvent(&Event)) {
2  if (Event.type == SDL_KEYDOWN) {
3    if (Event.key.keysym.sym == SDLK_SPACE) {
4      std::cout << "Spacebar Pressed";
5    }
6  }
7}

1Spacebar Pressed

In this example, we react to the arrow keys being pressed:

1while (SDL_PollEvent(&Event)) {
2  if (Event.type == SDL_KEYDOWN) {
3    if (Event.key.keysym.sym == SDLK_UP) {
4      // Up Arrow
5    } else if (Event.key.keysym.sym == SDLK_DOWN) {
6      // Down Arrow
7    } else if (Event.key.keysym.sym == SDLK_LEFT) {
8      // Left Arrow
9    } else if (Event.key.keysym.sym == SDLK_RIGHT) {
10      // Right Arrow
11    }
12  }
13}

A list of all the key codes is available in the SDL_keycode header file.

SDL_KeyboardEvent

When our SDL_Event object has a type of SDL_KEYDOWN or SDL_KEYUP, most of the information we care about is within the key struct of that event. This struct has a type of SDL_KeyboardEvent:

1while (SDL_PollEvent(&Event)) {
2  if (Event.type == SDL_KEYDOWN
3    || Event.type == SDL_KEYUP) {
4    SDL_KeyboardEvent KeyEvent = Event.key;
5  }
6}

Our main event loop can get long and complex, so we want to proactively mitigate this growth in our design.

One of the main ways of doing this is restricting our main event loop to just determining the high-level nature of each event (typically by examining the type variable) and then handing it off to a function to implement the required reaction.

A handler for events whose type is SDL_KEYDOWN or SDL_KEYUP will be most interested in the SDL_KeyboardEvent subobject stored in the key variable, so that tends to be what we provide from our main loop:

1// Event Loop
2while (SDL_PollEvent(&Event)) {
3  if (Event.type == SDL_KEYDOWN
4    || Event.type == SDL_KEYUP) {
5    HandleKeyboard(Event.key);
6  }
7}

1// Handler
2void HandleKeyboard(SDL_KeyboardEvent& E) {
3  if (E.keysym.sym == SDLK_UP) {
4    // Up Arrow
5  } else if (E.keysym.sym == SDLK_DOWN) {
6    // Down Arrow
7  } else if (E.keysym.sym == SDLK_LEFT) {
8    // Left Arrow
9  } else if (E.keysym.sym == SDLK_RIGHT) {
10    // Right Arrow
11  }
12}

To understand whether the key was pressed or released, the SDL_KeyboardEvent subobject also has a type field, which mirrors the type of the original SDL_Event. As such, we can compare it to SDL_KEYDOWN or SDL_KEYUP:

1void HandleKeyboard(SDL_KeyboardEvent& E) {
2  if (E.type == SDL_KEYDOWN) {
3    // Key Pressed
4  } else if (E.type == SDL_KEYUP) {
5    // Key Released
6  }
7}

Alternatively, we can access the state variable of the SDL_KeyboardEvent, and compare it to SDL_PRESSED or SDL_RELEASED:

1void HandleKeyboard(SDL_KeyboardEvent& E) {
2  if (E.state == SDL_PRESSED) {
3    // Key Pressed
4  } else if (E.state == SDL_RELEASED) {
5    // Key Released
6  }
7}

Converting Key Codes to Key Names

If we have a keycode, and we want to understand what key was pressed, the SDL_GetKeyName() function can help us. It converts a key code to a more understandable name:

1void HandleKeyboard(SDL_KeyboardEvent& E) {
2  std::cout
3    << "Key Pressed! Key Code: "
4    << E.keysym.sym
5    << ", Key Name: "
6    << SDL_GetKeyName(E.keysym.sym)
7    << '\n';
8}

1Key Pressed! Key Code: 113, Key Name: Q
2Key Pressed! Key Code: 119, Key Name: W
3Key Pressed! Key Code: 101, Key Name: E
4Key Pressed! Key Code: 114, Key Name: R
5Key Pressed! Key Code: 116, Key Name: T
6Key Pressed! Key Code: 121, Key Name: Y

Modifiers - Ctrl, Alt, Shift, etc

A small subset of keys on our keyboard are considered modifier keys as, by convention, applications them to modify the intent of other inputs. For example, in word processing applications, pressing a letter key whilst the shift key is held down is interpreted as requesting the uppercase form of that letter.

We can detect keydown and keyup events for these keys like any other:

1void HandleKeyboard(SDL_KeyboardEvent& E) {
2  if (E.state == SDL_PRESSED) {
3    std::cout << SDL_GetKeyName(E.keysym.sym)
4      << " pressed\n";
5  } else if (E.state == SDL_RELEASED) {
6    std::cout << SDL_GetKeyName(E.keysym.sym)
7      << " released\n";
8  }
9}

1Left Ctrl pressed
2Left Ctrl released
3Left Shift pressed
4Left Shift released

However, for convenience, the keysym struct also has a mod member variable, which tells us which (if any) modifier keys were active on any keyboard button event.

This variable is an integer that acts as a bit set, so we use the bitwise operators to understand which modifiers were active

Bitwise Operators and Bit Flags

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

SDL provides variables to use with this bit set. For example, we can use KMOD_LSHIFT as the right operand to the & operator, which will return true if the left shift button was active.

Below, we detect presses of the space bar, with different behaviors depending on whether or not left shift was active:

1void HandleKeyboard(SDL_KeyboardEvent& E) {
2  if (E.state == SDL_PRESSED &&
3    E.keysym.sym == SDLK_SPACE) {
4    std::cout << "Space bar was pressed\n";
5    if (E.keysym.mod & KMOD_LSHIFT) {
6      std::cout << "  with left shift active\n";
7    }
8  }
9}

1Space bar was pressed
2Space bar was pressed
3  with left shift active

We can build more elaborate logic by combining boolean or bitwise operators. Below, we use the boolean && operator to determine if multiple modifiers are simultaneously active, and the bitwise | operator to detect if any of a range of modifiers are active:

1void HandleKeyboard(SDL_KeyboardEvent& E) {
2  if (E.state == SDL_PRESSED &&
3    E.keysym.sym == SDLK_SPACE) {
4    std::cout << "Space bar was pressed\n";
5    if ((E.keysym.mod & KMOD_LSHIFT)
6      && (E.keysym.mod & KMOD_LCTRL)) {
7      std::cout << "  with left shift AND "
8        "left ctrl active\n";
9    } else if (E.keysym.mod &
10      (KMOD_LSHIFT | KMOD_LCTRL)) {
11      std::cout << "  with left shift OR "
12        "left ctrl active\n";
13    }
14  }
15}

1Space bar was pressed
2Space bar was pressed
3  with left shift AND left ctrl active
4Space bar was pressed
5  with left shift OR left ctrl active

The range of KMOD_ variables provided by SDL are defined in the SDL_Keymod enum within the keycode header file.

Key Repeats

On many platforms, holding a key down sends a continuous stream of input events after a brief pause. SDL reports these as repeated keydown events.

1void HandleKeyboard(SDL_KeyboardEvent& E) {
2  if (E.state == SDL_PRESSED &&
3    E.keysym.sym == SDLK_SPACE) {
4    std::cout << "Space bar was pressed\n";
5  } else if (E.state == SDL_RELEASED &&
6    E.keysym.sym == SDLK_SPACE) {
7    std::cout << "Space bar was released\n";
8  }
9}

Holding our spacebar down for a few seconds generates output similar to the following:

1Space bar was pressed
2Space bar was pressed
3Space bar was pressed
4Space bar was pressed
5Space bar was released

We can distinguish between initial and repeat events by inspecting the repeat variable of the SDL_KeyboardEvent (or the key.repeat variable of the SDL_Event)

The repeat value will be 0 for the initial keydown, and a non-zero value if it was caused by the user continuing to hold the key down:

1void HandleKeyboard(SDL_KeyboardEvent& E) {
2  if (E.state == SDL_PRESSED &&
3    E.keysym.sym == SDLK_SPACE) {
4    std::cout << "\nSpace bar was pressed - "
5      << (E.repeat ? "Repeat" : "Initial");
6  } else if (E.state == SDL_RELEASED &&
7    E.keysym.sym == SDLK_SPACE) {
8    std::cout << "Space bar was released\n";
9  }
10}

1Space bar was pressed - Initial
2Space bar was pressed - Repeat
3Space bar was pressed - Repeat
4Space bar was pressed - Repeat
5Space bar was released

Key Codes and Scan Codes

Keyboards can have different layouts. Much of the world uses the QWERTY layout, but others, such as AZERTY, are also common.

This variation means there are two different ways to represent keys.

Key codes, sometimes referred to as virtual key codes, are the simplest to understand. If the user presses the button labeled "Q` on their keyboard, a key code representing Q will be reported. This assumes the user configured their system correctly - that is, the layout they selected in their system settings matches the layout of their physical keyboard.

Scan codes, sometimes referred to as physical key codes, ignore the configured layout and instead represent what physical button was pressed. In SDL2, the scan code is reported based on the QWERTY layout. For example, if the user presses the button that would be labeled "Q" on a QWERTY keyboard, a scan code representing Q will be reported.

This means that if the user is on an AZERTY keyboard for example, and they press the button labeled A, the scan code we receive will be Q, as that would be the Q button on a QWERTY keyboard:

Scan codes are primarily useful when we care about the position of the buttons, rather than their alphabetic representations. For example, the W, A, S, and D keys are commonly used for movement in video games, due to their position and proximity to each other on a QWERTY keyboard.

On an AZERTY layout, those same physical buttons are labeled Z, Q, S, and D. But, if we’re using scan codes, we don’t need to care about that difference. Z will be reported as W, and Q will be reported as A, so players can use the same physical controls regardless of their keyboard layout.

Within SDL’s keysym struct, the key code is available as the sym member variable. whilst the scan code is available as scancode

1void HandleKeyboard(SDL_KeyboardEvent& E) {
2  SDL_Keycode KeyCode{E.keysym.sym};
3  SDL_Scancode ScanCode{E.keysym.scancode};
4}

Summary

This lesson introduced how to handle keyboard input using SDL. The key takeaways include:

• Detecting and handling keyboard events with SDL
• Using SDL_KEYDOWN and SDL_KEYUP events
• Understanding key codes and scan codes
• Utilizing the SDL_GetKeyName() function
• Handling modifier keys such as Ctrl, Alt, and Shift
• Distinguishing between initial and repeated key events

Next Lesson

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.

ContinueView Course