Handling Keyboard Input

When our SDL_Event object has a type of SDL_EVENT_KEY_DOWN or SDL_EVENT_KEY_UP, 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_EVENT_KEY_DOWN ||
3      Event.type == SDL_EVENT_KEY_UP
4  ) {
5    SDL_KeyboardEvent KeyEvent = Event.key;
6  }
7}

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 keyboard events 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_EVENT_KEY_DOWN ||
4      Event.type == SDL_EVENT_KEY_UP
5  ) {
6    HandleKeyboard(Event.key);
7  }
8}

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

To understand whether the key was pressed or released, we can access the down boolean of the SDL_KeyboardEvent. This is true for a key press and false for a release:

1void HandleKeyboard(const SDL_KeyboardEvent& E) {
2  if (E.down) {
3    // Key Pressed
4  } else {
5    // Key Released
6  }
7}

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(const SDL_KeyboardEvent& E) {
2  std::cout
3    << "Key Pressed! Key Code: "
4    << E.key
5    << ", Key Name: "
6    << SDL_GetKeyName(E.key)
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

A small subset of keys on our keyboard are considered modifier keys as, by convention, applications use 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(const SDL_KeyboardEvent& E) {
2  if (E.down) {
3    std::cout << SDL_GetKeyName(E.key)
4      << " pressed\n";
5  } else {
6    std::cout << SDL_GetKeyName(E.key)
7      << " released\n";
8  }
9}

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

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

This variable is an integer that acts as a bit set, so we use the bitwise operators to understand which modifiers were active. You can learn more about this technique in our introductory lesson on bitwise operators .

SDL provides constants to use with this bit set. For example, we can use SDL_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(const SDL_KeyboardEvent& E) {
2  if (E.down && E.key == SDLK_SPACE) {
3    std::cout << "Space bar was pressed\n";
4    if (E.mod & SDL_KMOD_LSHIFT) {
5      std::cout << "  with left shift active\n";
6    }
7  }
8}

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(const SDL_KeyboardEvent& E) {
2  if (E.down && E.key == SDLK_SPACE) {
3    std::cout << "Space bar was pressed\n";
4    if ((E.mod & SDL_KMOD_LSHIFT)
5      && (E.mod & SDL_KMOD_LCTRL)) {
6      std::cout << "  with left shift AND "
7        "left ctrl active\n";
8    } else if (E.mod &
9      (SDL_KMOD_LSHIFT | SDL_KMOD_LCTRL)) {
10      std::cout << "  with left shift OR "
11        "left ctrl active\n";
12    }
13  }
14}

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 full list of SDL_KMOD_ constants provided by SDL are listed in the official documentation.

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.

The following program logs both presses and releases of the spacebar but, if we hold the spacebar down, we'll get a stream of continuous key press events:

1void HandleKeyboard(const SDL_KeyboardEvent& E) {
2  if (E.down && E.key == SDLK_SPACE) {
3    std::cout << "Space bar was pressed\n";
4  } else if (!E.down && E.key == SDLK_SPACE) {
5    std::cout << "Space bar was released\n";
6  }
7}

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 false for the initial keydown, and true if it was caused by the user continuing to hold the key down:

1void HandleKeyboard(const SDL_KeyboardEvent& E) {
2  if (E.down && E.key == SDLK_SPACE) {
3    std::cout << "\nSpace bar was pressed - "
4      << (E.repeat ? "Repeat" : "Initial");
5  } else if (!E.down && E.key == SDLK_SPACE) {
6    std::cout << "Space bar was released\n";
7  }
8}

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

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.

We've been using key codes in this lesson, sometimes also referred to as virtual key codes. These 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 which physical button was pressed. In SDL3, the scan code is reported based on a standard hardware layout.

For example, if the user presses the button that would be labeled "Q" on a standard US-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 for "Q", as that physical key is in the "Q" position on a standard US-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. On such a keyboard, Z will be reported as the W scan code. So, if our movement manager interprets input using the button' scan codes, players can use the same physical controls to move their character, regardless of how those buttons are labelled on their specific keyboard.

We'd take the opposite approach if the user is currently typing something into our program, such as interacting with a chat box. In that scenario, if they press the button labeled "Z" on their AZERTY keyboard, we assume they do indeed want to type the letter Z. So, our chat box component should interpret inputs using the key code (which would be Z) rather than the scan code (which would be W).

Within an SDL_KeyboardEvent, the key code is available as the key member, while the scan code is available as scancode.

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

The specific scancodes used are defined in the Human Interface Devices (HID) component of the USB standard, if you want a lower level understanding of keyboard interfaces.

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

• Detecting and handling keyboard events with SDL.
• Using SDL_EVENT_KEY_DOWN and SDL_EVENT_KEY_UP 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.