Building on our basic SDL window setup, this lesson introduces interactivity by focusing on mouse input.

We'll explore how SDL represents mouse actions through its event system. You'll learn to detect when the user moves the mouse, clicks buttons, or even moves the cursor into or out of the application window.

Key topics include:

Processing SDL_MOUSEMOTION events to get cursor coordinates.
Understanding SDL's coordinate system.
Detecting mouse button presses and releases (SDL_MOUSEBUTTONDOWN, SDL_MOUSEBUTTONUP).
Identifying which mouse button was clicked.
Handling double clicks.
Responding to the cursor entering or leaving the windopullw (SDL_WINDOWEVENT_ENTER, SDL_WINDOWEVENT_LEAVE).

Starting Point

We'll start with the basic SDL application structure from our previous lessons. This includes initializing SDL, creating a window using our Window class, and setting up the main event loop. The code below provides this foundation:

As a reminder, our SDL_PollEvent(&Event) statement will update our Event object with any mouse action that the user performs. We'll then detect and react to those actions within the body of the event loop.

Mouse Motion Events

Every time the player moves their mouse within our window, an SDL_Event is pushed onto the event queue.

That event will have a type of SDL_MOUSEMOTION, and the mouse's new position is available through the x and y members of the motion object:

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
9  SDL_Event E;
10  while (true) {
11    while (SDL_PollEvent(&E)) {
12      if (E.type == SDL_MOUSEMOTION) {
13        std::cout << "Mouse Motion Detected - "
14          << "x: " << E.motion.x
15          << ", y: " << E.motion.y << '\n';
16      } else if (E.type == SDL_QUIT) {
17        SDL_Quit();
18        return 0;
19      }
20    }
21
22    GameWindow.Render();
23    GameWindow.Update();
24  }
25
26  return 0;
27}

1Mouse Motion Detected - x: 2, y: 77
2Mouse Motion Detected - x: 6, y: 79
3Mouse Motion Detected - x: 8, y: 80

SDL's Coordinate System

When working with SDL, and pixel data in general, the coordinate system that is used tends to be different to what we might expect.

It's common that the origin - that is, the position $(0, 0)$ - represents the top left of the window, surface, or image. Increasing x values corresponds to moving right, and increasing y values corresponds to moving down.

So, if our window was 700 units wide and 300 units tall, its coordinate system would look like this:

For example, if we have a mouse motion event with an x value of 300, that means the pointer was moved to a position that is 300 units from the left edge of our window. If y is 200, that means the pointer is 200 pixels from the top edge of the window.

Diagram showing a mouse position in screen space

This is sometimes called a y-down coordinate system. The system we typically use in other contexts, and we learn about in geometry class, is y-up

Diagram comparing y-up and y-down coordsinate systems

We cover coordinate systems and moving objects between them in much more detail later in the course.

Position Arithmetic

If we need to work with positions relative to some other location, such as the bottom-right of our window, that tends to be easy to work out with some arithmetic.

However, this arithmetic requires us to know the width and height of the window. We can add getters to our Window class to support that:

1// Window.h
2// ...
3
4class Window {
5public:
6  Window() {
7    SDLWindow = SDL_CreateWindow(
8      "Scene",
9      SDL_WINDOWPOS_UNDEFINED,
10      SDL_WINDOWPOS_UNDEFINED,
11      GetWidth(), GetHeight(),
12      0
13    );
14  }
15
16  int GetWidth() const { return 700; }
17  int GetHeight() const { return 300; }
18  
19  // ...
20};

Note that this code assumes our window is not resizable. We cover window sizing and resizing in a dedicated chapter later in the course.

With our getters in place, any code with access to our window can now easily retrieve it's dimensions when needed:

1if (E.type == SDL_MOUSEMOTION) {
2  int DistanceFromLeftEdge{E.motion.x};
3  int DistanceFromTopEdge{E.motion.y};
4  int DistanceFromRightEdge{
5    GameWindow.GetWidth() - E.motion.x};
6  int DistanceFromBottomEdge{
7    GameWindow.GetHeight() - E.motion.y};
8}

Using `SDL_MouseMotionEvent`

When we're dealing with an SDL_Event that has a type of SDL_MOUSEMOTION, the motion struct it contains has the SDL_MouseMotionEvent type.

When working with mouse motion events, this object is slightly easier to use than the top-level SDL_Event, as it does not require us to access the intermediate motion subobject to retrieve the information we care about.

This makes it useful for storing and transferring mouse motion events. The event loop body can get very large, so to mitigate this, we can move our mouse motion handler to a standalone function, and pass the Event.motion struct to it from our event loop:

1// main.cpp
2#include <SDL.h>
3#include "Window.h"
4
5void HandleMotion(SDL_MouseMotionEvent& E) {
6  int DistanceFromLeft{E.x};
7  int DistanceFromTop{E.y};
8  // ...
9}
10
11int main(int argc, char** argv) {
12  SDL_Init(SDL_INIT_VIDEO);
13  Window GameWindow;
14
15  SDL_Event E;
16  while (true) {
17    while (SDL_PollEvent(&E)) {
18      if (E.type == SDL_MOUSEMOTION) {
19        HandleMotion(E.motion);
20      } else if (E.type == SDL_QUIT) {
21        SDL_Quit();
22        return 0;
23      }
24    }
25
26    GameWindow.Render();
27    GameWindow.Update();
28  }
29
30  return 0;
31}

Mouse Enter / Mouse Leave Events

By default, SDL will only report mouse motion events when our window has mouse focus - that is, when the user's cursor is hovering over our window.

When the user's cursor enters or leaves our window, SDL provides events to notify us of this. These events have a type of SDL_WINDOWEVENT.

1while(SDL_PollEvent(&E)) {
2  if (E.type == SDL_WINDOWEVENT) {
3    // ...
4  }
5}

However, a wide range of other events are categorized under this SDL_WINDOWEVENT type too, which we'll cover in more detail later.

If our event is an SDL_WINDOWEVENT, we can access more specific information under the window struct of that SDL_Event. This subobject has another field called event, which gives us a more specific categorization.

If the window event represents the user's cursor entering our window, the window.event member will be equal to SDL_WINDOWEVENT_ENTER. When the event represents the cursor leaving the window, it will be equal to SDL_WINDOWEVENT_LEAVE:

1if (E.type == SDL_WINDOWEVENT) {
2  if (E.window.event == SDL_WINDOWEVENT_ENTER) {
3    std::cout << "Mouse Entered Window\n";
4  } else if (E.window.event == SDL_WINDOWEVENT_LEAVE) {
5    std::cout << "Mouse Left Window\n";
6  }
7}

Using `SDL_WindowEvent`

Similar to SDL_MouseMotionEvent, a dedicated SDL_WindowEvent type is available for window events, which is helpful if we want to send that event to some other function.

If the outer SDL_Event has a type of SDL_WINDOWEVENT, then the window variable of that event will contain the SDL_WindowEvent:

1#include <SDL.h>
2#include "Window.h"
3
4void HandleWindowEvent(SDL_WindowEvent& E) {
5  if (E.event == SDL_WINDOWEVENT_ENTER) {
6    std::cout << "Mouse Entered Window\n";
7  } else if (E.event == SDL_WINDOWEVENT_LEAVE) {
8    std::cout << "Mouse Left Window\n";
9  }
10}
11
12int main(int argc, char** argv) {
13  SDL_Init(SDL_INIT_VIDEO);
14  Window GameWindow;
15
16  SDL_Event E;
17  while (true) {
18    while (SDL_PollEvent(&E)) {
19      if (E.type == SDL_WINDOWEVENT) {
20        HandleWindowEvent(E.window);
21      } else if (E.type == SDL_QUIT) {
22        SDL_Quit();
23        return 0;
24      }
25    }
26
27    GameWindow.Render();
28    GameWindow.Update();
29  }
30
31  return 0;
32}

Reminder: Function Overloading

In our previous examples, we're giving our event handlers different names - HandleMotion() and HandleWindowEvent() - based on the type of events they are for. However, this is not entirely necessary as the functions also have different parameter types - SDL_MouseMotionEvent and SDL_WindowEvent.

We can give our functions the same name if we prefer, and let the compiler select the correct one based on the argument provided in our event loop:

1#include <SDL.h>
2#include "Window.h"
3
4void HandleEvent(SDL_MouseMotionEvent& E) {
5  // ...
6}
7
8void HandleEvent(SDL_WindowEvent& E) {
9  // ...
10}
11
12int main(int argc, char** argv) {
13  SDL_Init(SDL_INIT_VIDEO);
14  Window GameWindow;
15
16  SDL_Event E;
17  while (true) {
18    while (SDL_PollEvent(&E)) {
19      if (E.type == SDL_MOUSEMOTION) {
20        HandleEvent(E.motion);
21      } else if (E.type == SDL_WINDOWEVENT) {
22        HandleEvent(E.window);
23      } else if (E.type == SDL_QUIT) {
24        SDL_Quit();
25        return 0;
26      }
27    }
28
29    GameWindow.Render();
30    GameWindow.Update();
31  }
32
33  return 0;
34}

Mouse Click Events

When any mouse button is pressed or released, we get an SDL_Event whose type is equal to SDL_MOUSEBUTTONDOWN or SDL_MOUSEBUTTONUP respectively:

1while (SDL_PollEvent(&E)) {
2  if (E.type == SDL_MOUSEBUTTONDOWN) {
3    std::cout << "Button Pressed\n";
4  } else if (E.type == SDL_MOUSEBUTTONUP) {
5    std::cout << "Button Released\n";
6  }
7}

Both of these event types include an SDL_MouseButtonEvent in the button variable:

1#include <SDL.h>
2#include "Window.h"
3
4void HandleButtonEvent(SDL_MouseButtonEvent& E) {
5  // ...
6}
7
8int main(int argc, char** argv) {
9  SDL_Init(SDL_INIT_VIDEO);
10  Window GameWindow;
11
12  SDL_Event E;
13  while (true) {
14    while (SDL_PollEvent(&E)) {
15      if (
16        E.type == SDL_MOUSEBUTTONDOWN ||
17        E.type == SDL_MOUSEBUTTONUP
18      ) {
19        HandleButtonEvent(E.button);
20      } else if (E.type == SDL_QUIT) {
21        SDL_Quit();
22        return 0;
23      }
24    }
25
26    GameWindow.Render();
27    GameWindow.Update();
28  }
29
30  return 0;
31}

Button Pressed vs Button Released

This SDL_MouseButtonEvent also includes the type value, so we can still determine if it corresponds to a button being pressed or released. Alternatively, we can access the state variable, and compare it to SDL_PRESSED or SDL_RELEASED:

1#include <SDL.h>
2#include "Window.h"
3
4void HandleButtonEvent(SDL_MouseButtonEvent& E) {
5  if (E.type == SDL_MOUSEBUTTONDOWN) {
6    // Button Pressed
7  } else if (E.type == SDL_MOUSEBUTTONUP) {
8    // Button Released
9  }
10  
11  // Alternatively:
12  if (E.state == SDL_PRESSED) {
13    // Button Pressed
14  } else if (E.state == SDL_RELEASED) {
15    // Button Released
16  }
17}
18
19int main(int argc, char** argv) {/*...*/}

Which Button was Pressed or Released?

To understand which button was pressed or released, the SDL_MouseButtonEvent includes a button member, storing a numeric identifier for the mouse button that triggered the event.

SDL provides some helper values to compare this identifier to the common mouse buttons:

SDL_BUTTON_LEFT - The left mouse button
SDL_BUTTON_RIGHT - The right mouse button
SDL_BUTTON_MIDDLE - The middle mouse button
SDL_BUTTON_X1 - The first extra mouse button, which is on the side of some mice
SDL_BUTTON_X2 - The second extra mouse button, which is on the side of some mice

Using these values in code might look something like this:

1#include <SDL.h>
2#include "Window.h"
3
4void HandleButtonEvent(SDL_MouseButtonEvent& E) {
5  if (E.button == SDL_BUTTON_LEFT) {
6    // The left button was pressed or released
7  } else if (E.button == SDL_BUTTON_RIGHT) {
8    // The right button was pressed or released
9  }
10
11  if (
12    E.button == SDL_BUTTON_LEFT &&
13    E.state == SDL_PRESSED
14  ) {
15    // The left button was pressed
16  }
17}
18
19int main(int argc, char** argv) {/*...*/}

The `SDL_Event` Union

SDL_Event is an example of a union. With a union, all members are stored in the same memory location.

This is used when we want a variable to store one of several possible types. In the SDL_Event case, those types are things like SDL_MouseMotionEvent, SDL_WindowEvent, and SDL_MouseButtonEvent.

We cover unions, and modern, safer alternatives to them in our advanced course:

Constrained Dynamic Types using Unions and `std::variant`

Learn how to store dynamic data types in C++ using unions and the type-safe std::variant

View Related Lesson

For now, a key point to note about unions is that they're not type safe. That is, we don't know what data type is stored in that memory address. If get it wrong by, for example, assuming an SDL_MouseButtonEvent is stored there when it's actually an SDL_WindowEvent, then the compiler can't detect that error - we just have a bug.

Before we do almost anything with an SDL_Event, we should ascertain exactly what type it is pointing at. We do this by checking the type field, as shown in our earlier examples. The following code violates this principle:

1void HandleEvent(SDL_Event& E) {
2  bool isLeftClick{
3    E.button.button == SDL_BUTTON_LEFT &&
4    E.type == SDL_MOUSEBUTTONDOWN
5  };
6}

This is accessing the E.button.button variable before we confirmed that the memory address really is storing an SDL_MouseButtonEvent. If it's not, our program will have a bug.

To fix this, we should change the order of our operands to check the type first, and only access the button member once we know it's an SDL_MouseButtonEvent:

1void HandleEvent(SDL_Event& E) {
2  bool isLeftClick{
3    E.type == SDL_MOUSEBUTTONDOWN &&
4    E.button.button == SDL_BUTTON_LEFT
5  };
6}

As a reminder, C++, like most programming languages, performs short circuit evaluation. In the second example, if E.type == SDL_MOUSEBUTTONDOWN is false, then E.button.button == SDL_BUTTON_LEFT is never evaluated.

With the && operator, if the left operand is false, then the entire expression will be false. It doesn't matter what the right operand is, so it's effectively ignored.

Double Clicks

If our application needs to detect double clicks, we can check the clicks member variable of the SDL_MouseButtonEvent. This represents the number of times the user has clicked that same button in quick succession:

1void HandleButtonEvent(const SDL_MouseButtonEvent& E) {
2  if (E.clicks >= 2) {
3    // Double Click Detected
4  }
5}

Note that the clicks variable will also be set on the SDL_MOUSEBUTTONUP event, so the code in this if block will be executed twice:

On the SDL_MOUSEBUTTONDOWN event of the second click
On the SDL_MOUSEBUTTONUP event of the second click

It will also detect double-clicks of any button. We'll often want to filter on the specific user action we care about:

1#include <SDL.h>
2#include "Window.h"
3
4void HandleButtonEvent(SDL_MouseButtonEvent& E) {
5  if (E.button == SDL_BUTTON_LEFT &&
6      E.state == SDL_PRESSED &&
7      E.clicks >= 2
8  ) {
9    // The left button was double-clicked
10  }
11}
12
13int main(int argc, char** argv) {/*...*/}

Using the clicks variable tends to be preferred over trying to create double-click detection from scratch, as it's more complex than it first appears.

Additionally, most operating systems allow users to change their double-click sensitivity and, by using SDL's solution, our application can respect those settings.

Complete Code

Here's the complete code incorporating all the mouse event handling techniques discussed in this lesson. It demonstrates how to detect motion, window enter/leave events, button clicks, and double clicks using simple std::cout statements for illustration.

While the specific output functions like HandleMotionEvent() won't be carried forward into subsequent lessons, the fundamental principles - checking event types (Event.type), accessing specific event data (Event.motion, Event.window, Event.button), and processing input within the event loop - are crucial concepts that we will build upon throughout the rest of the course.

1Mouse Motion Detected - x: 200, y: 124
2  Distance from Right: 500
3  Distance from Bottom: 176
4Left Double Click
5Right Click or Release
6Right Click or Release

Summary

We've explored how to make SDL applications responsive to mouse input. By examining the SDL_Event structure within the main loop, we can detect and react to mouse movements, button clicks (including double clicks), and window boundary crossings by the cursor. This forms the basis for implementing mouse controls.

Key Takeaways:

The core of input handling is the while(SDL_PollEvent(&E)) loop.
Filter events based on E.type (e.g., SDL_MOUSEMOTION, SDL_MOUSEBUTTONDOWN).
Access event-specific data using union members (e.g., E.motion, E.button).
Mouse position is given by E.motion.x and E.motion.y (y-down).
Button identity uses constants like SDL_BUTTON_LEFT, SDL_BUTTON_RIGHT.
Button state is checked via E.button.state (SDL_PRESSED, SDL_RELEASED).
Double clicks are identified using E.button.clicks.
Window enter/leave events are a subtype of SDL_WINDOWEVENT.
Dedicated structs like SDL_MouseMotionEvent exist for specific event types.

Mouse Input Basics

Starting Point

Mouse Motion Events

SDL's Coordinate System

Using `SDL_MouseMotionEvent`

Mouse Enter / Mouse Leave Events

Using `SDL_WindowEvent`

Mouse Click Events

Button Pressed vs Button Released

Which Button was Pressed or Released?

Double Clicks

Complete Code

Summary

Rectangles and `SDL_Rect`

Game Development with SDL2

Questions & Answers

Mouse Input Basics

Starting Point

Mouse Motion Events

SDL's Coordinate System

Using SDL_MouseMotionEvent

Mouse Enter / Mouse Leave Events

Using SDL_WindowEvent

Mouse Click Events

Button Pressed vs Button Released

Which Button was Pressed or Released?

Double Clicks

Complete Code

Summary

Rectangles and SDL_Rect

Questions & Answers

Using `SDL_MouseMotionEvent`

Using `SDL_WindowEvent`

Rectangles and `SDL_Rect`