Keyboard and Mouse Input in SDL2

In this lesson, we will cover in detail how we can detect and react to user input.

Input is handled through the SDL event queue, so user input will show up within our event loop.

There, we can inspect the event and, if it’s something we want to react to, we can write the required code to make that happen.

SDL supports a wide range of input, including game pads, joysticks and microphones. Here, we’ll be focused on keyboard and mouse events.

Handling the Keyboard in SDL2

Keyboard input is slightly easier to handle than the mouse, as there are so few events to deal with. A button is either pressed, or it isn’t. However, there are some additional considerations when it comes to determining which button was pressed.

SDL2 Keyboard Button Events (SDL_KEYDOWN, SDL_KEYUP)

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_KEYDOWN) {
5    // ...
6  }
7}
8

To find out which button was pressed or released, we need to check the key code. When we’re dealing with a keyboard event, the key code is available within Event.key.keysym.sym.

This is an integer, but SDL provides named helpers to make our code more readable. For example, here is how we’d detect 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}
14

All the key codes are available in the official documentation.

Converting an SDL2 Key Code to Key Name with SDL_GetKeyName

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:

1while (SDL_PollEvent(&Event)) {
2  if (Event.type == SDL_KEYDOWN) {
3    std::cout
4      << "Key Pressed! Key Code: "
5      << Event.key.keysym.sym
6      << ", Key Name: "
7      << SDL_GetKeyName(Event.key.keysym.sym)
8      << '\n';
9  }
10}
11

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
7

Handling the Mouse in SDL2

There are a lot of mouse-related events we might be interested in. Here, we cover the most common examples

SDL2 Mouse Click Events (SDL_MOUSEBUTTONDOWN, SDL_MOUSEBUTTONUP)

When any mouse button is pressed or released, we get one of these events.

1while (SDL_PollEvent(&Event)) {
2  if (Event.type == *SDL_MOUSEBUTTONDOWN*) {
3    // A button was pressed
4  } else if (Event.type == *SDL_MOUSEBUTTONUP*) {
5    // A button was released
6  }
7}
8

When we have a mouse button event, we can find out which button was pressed or released within the Event.button.button value. As usual, SDL has helpers to compare these to:

1if (Event.type == SDL_MOUSEBUTTONDOWN) {
2   if (Event.button.button == SDL_BUTTON_LEFT) {
3     // Left Button Pressed
4   } else if (Event.button.button == SDL_BUTTON_RIGHT) {
5     // Left Button Released
6   }
7}
8

SDL2 Mouse Motion Events (SDL_MOUSEMOTION)

When the user’s mouse was moved, an event with a type of SDL_MOUSEMOTION is created. Within that event, the mouse’s x and y position are available under Event.motion.x:

1while (SDL_PollEvent(&Event)) {
2  if (Event.type == *SDL_MOUSEMOTION*) {
3    int x { Event.motion.x };
4    int y { Event.motion.y };
5  }
6}
7

By default, these values are relative to the window, starting from the top left.

So, if x is 0 and y is 0, that means the user moved their cursor to the extreme top left of our window.

If x is the same as our window width, and y is the same as our window height, that means the cursor moved to the bottom right of our window.

SDL Mouse Wheel Events - Detecting Mouse Scroll (SDL_MOUSEWHEEL)

We can react to mouse wheel scrolling by listening for events with the type of SDL_MOUSEWHEEL.

Event.wheel.y lets us know how far the wheel was scrolled. Positive values mean the user scrolled down; negative means they scrolled up.

1while (SDL_PollEvent(&Event)) {
2  if (Event.type == *SDL_MOUSEWHEEL*) {
3    int Amount { Event.wheel.y };
4  }
5}
6

Detecting Mouse Enter / Mouse Leave (SDL_WINDOWEVENT_ENTER, SDL_WINDOWEVENT_LEAVE)

Finally, we can detect when the user’s cursor entered or left our window, by listening for the SDL_WINDOWEVENT type.

This is a slightly more complicated event type, as there are multiple different subtypes. The subtypes are available under Event.window.event.

The mouse enter and mouse leave events have a subtype of SDL_WINDOWEVENT_ENTER and SDL_WINDOWEVENT_LEAVE:

1if (Event.type == SDL_WINDOWEVENT) {
2  if (Event.window.event == SDL_WINDOWEVENT_ENTER) {
3    // Cursor entered our window    
4  } else if (Event.window.event == SDL_WINDOWEVENT_LEAVE) {
5    // Cursor left our window
6  }
7}
8

Preventing the Cursor from leaving the Window in SDL2 (C++)

In many applications, particularly games, we want to prevent the user’s mouse cursor from leaving our window.

That can be done with the SDL_SetWindowMouseGrab function. We need to pass it a pointer to our SDL_Window, as well as a second argument instructing whether we want to grab the cursor or not.

The second argument should be SDL_TRUE to grab the cursor, or SDL_FALSE to release it.

Here, we grab the cursor when the user presses their left mouse button, and we release it when they release the button.

This code assumes the pointer to our SDL_Window is stored in a variable called SDLWindow:

1while (SDL_PollEvent(&Event)) {
2  if (
3    Event.type == *SDL_MOUSEBUTTONDOWN &&*
4    Event.button.button == SDL_BUTTON_LEFT
5  ) {
6    SDL_SetWindowMouseGrab(SDLWindow, SDL_TRUE);
7    }
8  else if (
9    Event.type == *SDL_MOUSEBUTTONDOWN &&*
10    Event.button.button == SDL_BUTTON_LEFT
11  ) {
12    SDL_SetWindowMouseGrab(SDLWindow, SDL_FALSE);
13  }
14}
15

Hiding the Cursor in SDL2 (C++)

Similar to trapping the cursor, we also often want to hide it. That can be done with SDL_ShowCursor, passing in SDL_ENABLE to show the cursor, or SDL_DISABLE to hide it:

1if (shouldShowCursor){
2  SDL_ShowCursor(SDL_ENABLE);
3} else {
4  SDL_ShowCursor(SDL_DISABLE);
5}
6

Getting the Current Mouse and Keyboard State in SDL2

We do not need to wait for an event to occur before we can get information about the mouse and keyboard. At any time, we can find out what is going on.

SDL2 Mouse State with SDL_GetMouseState

SDL_GetMouseState accepts two int pointers, which it will update with the mouse’s current x and y coordinates.

1int x, y;
2SDL_GetMouseState(&x, &y);
3std::cout << "Mouse is at " << x << ", " << y;
4

Just like with mouse events, these values are relative to our window. If we don’t care about the mouse position, and only want to know about the buttons, we can pass nullptr to both of these parameters.

To get the state of the buttons, we use the return value of SDL_GetMouseState. The function returns bit flags / a bit mask in the form of a Uint32. We can use the Bitwise OR operator (&) on this value to determine if any buttons are pressed.

Bitwise Operators and Bit Flags

An introduction to the bitwise AND, OR, and XOR operators - and one of their most interesting use cases

SDL provides helpers to use with this bit mask - most notably, SDL_BUTTON_LMASK for the left button, and SDL_BUTTON_RMASK for the right button.

Here’s an example where we get and print the mouse state when the user presses their space bar:

1while (SDL_PollEvent(&Event)) {
2  if (
3    Event.type == SDL_KEYDOWN &&
4    Event.key.keysym.sym == SDLK_SPACE
5  ) {
6    int x, y;
7    Uint32 Buttons { SDL_GetMouseState(&x, &y) };
8
9    std::cout << "Mouse is at " << x << ", " << y;
10    if ((Buttons & SDL_BUTTON_LMASK)) {
11      std::cout << " - Left Button is pressed";
12    }
13    if ((Buttons & SDL_BUTTON_RMASK)) {
14       std::cout << " - Right Button is pressed";
15    }
16    std::cout << "\n";
17  }
18}
19

1Mouse is at 71, 43
2Mouse is at 139, 100 - Left Button is pressed
3Mouse is at 77, 254 - Left Button is pressed - Right Button is pressed
4

SDL2 Keyboard State with SDL_GetKeyboardState

Getting keyboard state works a little differently to mouse state. SDL maintains an array of UInt8 values - one for every keyboard key. The integer at each array position is 1 if the corresponding key is pressed, and 0 if it isn’t.

Once we acquire a pointer to that array, we can access it any time we need. The array is kept updated at all times by SDL - we don’t need to call a function to get the latest state.

We get the pointer using SDL_GetKeyboardState:

1int Length;
2const Uint8* KeyboardState = SDL_GetKeyboardState(&Length);
3

This function accepts a pointer to an integer, which will be populated with the length of the array. If we don’t care about that, we can just pass nullptr.

Once we have access to the array, we then check if a key is pressed by indexing into that array. The index we need to use will be the scan code of the key we’re interested in.

Just like key codes, SDL provides helper identifiers for those scan codes. To check if the space bar is pressed, we would do this:

1if (KeyboardState[SDL_SCANCODE_SPACE]) {
2   std::cout << "Space is pressed\n";
3}
4

All the scan codes are available in the official documentation.

A Full Example

What follows is an example application, showing how we can react to input, and manipulate the SDL window in various ways.

We’ve provided a more fleshed-out Window class, which builds on what we created in the previous lesson.

Creating a Window

Learn how to get started with SDL2 in C++ by creating a window. Includes an explanation of all the SDL2 functions we use, and the options we have to modify the window.

Using additional SDL functions, which we’ve documented in the comments, we’ve added some additional functionality:

• Changing the window’s background color
• Getting and changing the window’s size
• Changing the window’s position
• Changing the window's title
• Grabbing and releasing the mouse

1// Window.h
2#pragma once
3#include <SDL.h>
4#include <string>
5
6class Window {
7public:
8  Window() {
9    SDL_Init(SDL_INIT_VIDEO);
10
11    SDLWindow = SDL_CreateWindow(
12      "Hello World",
13      SDL_WINDOWPOS_UNDEFINED,
14      SDL_WINDOWPOS_UNDEFINED,
15      windowWidth, windowHeight, 0
16    );
17
18    SDLWindowSurface = SDL_GetWindowSurface(SDLWindow);
19  }
20
21  void Update() {
22    SDL_FillRect(
23      SDLWindowSurface,
24      nullptr,
25      SDL_MapRGB(
26        SDLWindowSurface->format,
27        bgRed, bgGreen, bgBlue
28      )
29    );
30  }
31
32  void RenderFrame() {
33    SDL_UpdateWindowSurface(SDLWindow);
34  }
35
36  void SetBackgroundColor(int R, int G, int B) {
37    bgRed = R;
38    bgGreen = G;
39    bgBlue = B;
40  }
41
42  void SetTitle(std::string NewTitle) {
43    // https://wiki.libsdl.org/SDL_SetWindowTitle
44    SDL_SetWindowTitle(
45      SDLWindow, NewTitle.c_str()
46    );
47  }
48
49  void ChangeWindowSize(int Amount) {
50    // https://wiki.libsdl.org/SDL_SetWindowSize
51    SDL_SetWindowSize(
52      SDLWindow,
53      windowWidth += Amount,
54      windowHeight += Amount
55    );
56  }
57
58  [[nodiscard]]
59  int GetWindowWidth() const {
60    return windowWidth;
61  }
62
63  [[nodiscard]]
64  int GetWindowHeight() const {
65    return windowHeight;
66  }
67
68  int MoveRelative(int x, int y) {
69    // https://wiki.libsdl.org/SDL_GetWindowPosition
70    int CurrentX; int CurrentY;
71    SDL_GetWindowPosition(
72      SDLWindow, &CurrentX, &CurrentY
73    );
74
75    // https://wiki.libsdl.org/SDL_SetWindowPosition
76    SDL_SetWindowPosition(
77      SDLWindow, CurrentX + x, CurrentY + y
78    );
79  }
80
81  void GrabMouse() {
82    // https://wiki.libsdl.org/SDL_SetWindowMouseGrab
83    SDL_SetWindowMouseGrab(SDLWindow, SDL_TRUE);
84  }
85
86  void FreeMouse() {
87    // https://wiki.libsdl.org/SDL_SetWindowMouseGrab
88    SDL_SetWindowMouseGrab(SDLWindow, SDL_FALSE);
89  }
90
91private:
92  SDL_Window* SDLWindow { nullptr };
93  SDL_Surface* SDLWindowSurface { nullptr };
94  int windowWidth { 300 };
95  int windowHeight { 300 };
96
97  int bgRed { 40 };
98  int bgGreen { 40 };
99  int bgBlue { 40 };
100};
101

To make use of this in main.cpp, we’ve built our event loop with lots of examples:

• The window title changes when we move our cursor into and out of the window
• The window background color changes based on our mouse position
• The scroll wheel makes the window larger or smaller
• The arrow keys move the window around
• When the left mouse button is held, the cursor is hidden and locked to the window
• When the right mouse button is pressed, we find and log out information about the keyboard state
• When the return key is pressed, we find and log out information about the mouse state
• When any other key is pressed, we log out its name

1#include <SDL.h>
2#include <iostream>
3#include "Window.h"
4
5int main() {
6  Window AppWindow;
7  auto KeyboardState = SDL_GetKeyboardState(nullptr);
8  SDL_Event Event;
9  while(true) {
10    while (SDL_PollEvent(&Event)) {
11      // System
12      if (Event.type == SDL_QUIT) [[unlikely]] {
13        SDL_Quit();
14        return 0;
15      }
16
17      // Mouse Input
18      else if (Event.type == SDL_MOUSEBUTTONDOWN) {
19        if (Event.button.button == SDL_BUTTON_LEFT) {
20          SDL_ShowCursor(SDL_ENABLE);
21          AppWindow.GrabMouse();
22        } else if (Event.button.button == SDL_BUTTON_RIGHT) {
23          if (KeyboardState[SDL_SCANCODE_SPACE]) {
24            std::cout << "Spacebar is pressed\n";
25          } else {
26            std::cout << "Spacebar is not pressed\n";
27          }
28        }
29      } else if (Event.type == SDL_MOUSEBUTTONUP) {
30        if (Event.button.button == SDL_BUTTON_LEFT) {
31          SDL_ShowCursor(SDL_ENABLE);
32          AppWindow.FreeMouse();
33        }
34      } else if (Event.type == SDL_MOUSEWHEEL) {
35        AppWindow.ChangeWindowSize(Event.wheel.y * 3);
36        AppWindow.SetTitle("Focused");
37      } else if (Event.type == SDL_MOUSEMOTION) [[likely]] {
38        AppWindow.SetBackgroundColor(
39          Event.motion.x * 255 / AppWindow.GetWindowWidth(),
40          Event.motion.y * 255 / AppWindow.GetWindowHeight(),
41          0
42        );
43      } else if (Event.type == SDL_WINDOWEVENT) {
44        if (
45          Event.window.event == SDL_WINDOWEVENT_ENTER
46        ) {
47          AppWindow.SetTitle("Focused");
48        } else if (
49          Event.window.event == SDL_WINDOWEVENT_LEAVE
50        ) {
51          AppWindow.SetTitle("Unfocused");
52        }
53      }
54
55      // Keyboard Input
56      else if (Event.type == SDL_KEYDOWN) {
57        if (Event.key.keysym.sym == SDLK_UP) {
58          AppWindow.MoveRelative(0, -10);
59        } else if (Event.key.keysym.sym == SDLK_DOWN) {
60          AppWindow.MoveRelative(0, 10);
61        } else if (Event.key.keysym.sym == SDLK_LEFT) {
62          AppWindow.MoveRelative(-10, 0);
63        } else if (Event.key.keysym.sym == SDLK_RIGHT) {
64          AppWindow.MoveRelative(10, 0);
65        } else if (Event.key.keysym.sym == SDLK_RETURN) {
66          int x, y;
67          Uint32 Buttons { SDL_GetMouseState(&x, &y) };
68
69          std::cout << "Mouse is at " << x << ", " << y;
70          if ((Buttons & SDL_BUTTON_LMASK)) {
71            std::cout << " - Left Button is pressed";
72          }
73          if ((Buttons & SDL_BUTTON_RMASK)) {
74            std::cout << " - Right Button is pressed";
75          }
76          std::cout << "\n";
77        } else {
78          std::cout
79            << "Key Pressed! Key Code: "
80            << Event.key.keysym.sym
81            << ", Key Name: "
82            << SDL_GetKeyName(Event.key.keysym.sym)
83            << '\n';
84        }
85      }
86    }
87    AppWindow.Update();
88    AppWindow.RenderFrame();
89  }
90}
91

Up next, we'll introduce SDL rectangles and colours. Combined with our new knowledge of events, we'll combine these concepts to start creating a user interface!