Handling Mouse Input

In this lesson, we will cover in detail how we can detect and react to the two main forms of mouse input - the user moving their cursor, and the user clicking their mouse buttons.

When these forms of input are detected, an SDL_Event is pushed onto 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, and an application loop set up in our main function:

1#include <SDL.h>
2
Window Class|Show
3class Window {/*...*/};
30
31int main(int argc, char** argv) {
32  SDL_Init(SDL_INIT_VIDEO);
33  Window GameWindow;
34  SDL_Event Event;
35
36  while(true) {
37    while(SDL_PollEvent(&Event)) {
38      // Detect and handle input events
39      // ...
40    }
41    GameWindow.RenderFrame();
42  }
43
44  SDL_Quit();
45  return 0;
46}

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

Mouse Motion Events

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

1while (SDL_PollEvent(&Event)) {
2  if (Event.type == SDL_MOUSEMOTION) {
3    std::cout << "x: " << Event.motion.x
4      << ", y: " << Event.motion.y << '\n';
5  }
6}

1x: 619, y: 201
2x: 643, y: 214
3x: 667, y: 228
4x: 676, y: 234

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

So for example, if x is 30, the pointer was moved to a position that is 30 pixels from the left edge of our window. If y is 40, that means the pointer is 40 pixels from the top edge of the window.

We can calculate the distance from the right and bottom edges with some arithmetic involving our window’s width and height respectively:

1void MousePosition(const SDL_Event& E) {
2  int DistanceFromLeft{E.motion.x};
3  int DistanceFromTop{E.motion.y};
4  
5  int DistanceFromRight{WindowWidth - E.motion.x};
6  int DistanceFromBottom{WindowHeight - E.motion.y};
7}

Later in the course, we’ll introduce more ways of tracking mouse motion, including handling scenarios where the mouse pointer is outside of our window.

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// Event Loop
2while (SDL_PollEvent(&Event)) {
3  if (Event.type == SDL_MOUSEMOTION) {
4    HandleMotion(Event.motion);
5  }
6}

1// Handler
2void HandleMotion(const SDL_MouseMotionEvent& E) {
3  int DistanceFromLeft{E.x};
4  int DistanceFromTop{E.y};
5  
6  int DistanceFromRight{WindowWidth - E.x};
7  int DistanceFromBottom{WindowHeight - E.y};
8}

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(&Event)) {
2  if (Event.type == SDL_MOUSEBUTTONDOWN) {
3    std::cout << "Button Pressed\n";
4  } else if (Event.type == SDL_MOUSEBUTTONUP) {
5    std::cout << "Button Released\n";
6  }
7}

1Button Pressed
2Button Released

When we have a mouse button event, we can find out which button was pressed or released within the Event.button.button value. This is an integer, and SDL includes 5 other integer variables to compare it against:

• 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 first extra mouse button, which is on the side of some mice

We can use the variables like this:

1if (Event.type == SDL_MOUSEBUTTONDOWN) {
2   if (Event.button.button == SDL_BUTTON_LEFT) {
3     std::cout << "Left Button Pressed\n";
4   } else if (Event.button.button == SDL_BUTTON_RIGHT) {
5     std::cout << "Right Button Pressed\n";
6   }
7}

1Left Button Pressed
2Right Button Pressed

Mouse Click Position

If we’re interested in where the mouse was when the user clicked a button, we don’t need to track mouse motion events separately. The SDL_MouseButtonEvent includes x and y coordinates representing where the cursor was when the click occurred.

Similar to motion events, by default, the x coordinate is the distance from the left edge of the window, and the y coordinate represents the distance from the top edge of the window:

1void MousePosition(const SDL_Event& E) {
2  int DistanceFromLeft{E.button.x};
3  int DistanceFromTop{E.button.y};
4  
5  int DistanceFromRight{WindowWidth - E.button.x};
6  int DistanceFromBottom{WindowHeight - E.button.y};
7  
8  // ...
9}

SDL_MouseButtonEvent

When we have an SDL_Event that has a type of SDL_MOUSEBUTTONDOWN or SDL_MOUSEBUTTONUP, the button struct within the event has the SDL_MouseButtonEvent type. This type is slightly easier to use than the more generic SDL_Event, as it does not require us to access the intermediate button subobject to retrieve the information we care about.

As such, when we’re storing or transferring a mouse button event to be processed elsewhere, the button subobject of the SDL_Event is typically what we use:

1// Event Loop
2while(SDL_PollEvent(&Event)) {
3  if (Event.type == SDL_MOUSEBUTTONDOWN ||
4      Event.type == SDL_MOUSEBUTTONUP) {
5    HandleButton(Event.button);
6  }
7}

1// Handler
2void HandleButton(const SDL_MouseButtonEvent& E) {  
3  if (E.button == SDL_BUTTON_LEFT) {
4    std::cout << "Left Button\n";
5  } else if (E.button == SDL_BUTTON_RIGHT) {
6    std::cout << "Right Button\n";
7  }
8  
9  int DistanceFromLeft{E.x};
10  int DistanceFromTop{E.y};
11
12  // ...
13}

1Left Button
2Left Button
3Right Button
4Right Button

When we have an SDL_MouseButtonEvent object, we can understand if it represents a button press or a button release by accessing the type member. As before, we can compare this type to SDL_MOUSEBUTTONDOWN or SDL_MOUSEBUTTONUP.

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

1void HandleButton(const SDL_MouseButtonEvent& E) {
2  if (Event.type == SDL_MOUSEBUTTONDOWN) {
3    // Button Pressed
4  } else if (Event.type == SDL_MOUSEBUTTONUP) {
5    // Button Released
6  }
7  
8  // Equivalently:
9  if (Event.state == SDL_PRESSED) {
10    // Button Pressed
11  } else if (Event.type == SDL_RELEASED) {
12    // Button Released
13  }
14}

Double Clicks

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

1void HandleButton(const SDL_MouseButtonEvent& E) {
2  if (Event.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:

1. On the SDL_MOUSEBUTTONDOWN event of the second click
2. On the SDL_MOUSEBUTTONUP event of the second click

We’ll often want to filter on the specific event we care about:

1void HandleButton(const SDL_MouseButtonEvent& E) {  
2  if (E.type == SDL_MOUSEBUTTONDOWN &&
3    E.clicks == 2) {
4    // Double Click Detected
5  }
6}

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.

Mouse Enter / Mouse Leave Events

Finally, we may want to detect when the user’s cursor entered or left our window. To do this, we first need to detect events whose type matches SDL_WINDOWEVENT:

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

A wide range of events is categorized under the SDL_WINDOWEVENT type. If our event has this type, we can access the 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 was raised because the user’s cursor entered the 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  }
5  if (E.window.event == SDL_WINDOWEVENT_LEAVE) {
6    std::cout << "Mouse Left Window\n";
7  }
8}

1Mouse Entered Window
2Mouse Left Window

SDL_MouseWindowEvent

Similar to the other event categories, a standalone SDL_WindowEvent type is available, which can help us store and transfer events whose type is within the SDL_WINDOWEVENT category. The window member of a window event has this type:

1// Event Loop
2while (SDL_PollEvent(&E)) {
3  if (E.type == SDL_WINDOWEVENT) {
4    HandleWindowEvent(E.window);
5  }
6}

1// Handler
2void HandleWindowEvent(const SDL_WindowEvent& E) {  
3  if (E.event == SDL_WINDOWEVENT_ENTER) {
4    std::cout << "Mouse Entered Window\n";
5  }
6  if (E.event == SDL_WINDOWEVENT_LEAVE) {
7    std::cout << "Mouse Left Window\n";
8  }
9}

Summary

In this lesson, we explored how to detect and handle different types of mouse input in SDL. Key topics included:

• Detecting mouse motion events and retrieving cursor positions.
• Handling mouse button events for clicks and releases.
• Managing mouse enter and leave events for window interaction.

Next Lesson

Building a Modular UI System

Learn how to create a flexible and extensible UI system using C++ and SDL, focusing on component hierarchy and polymorphism.

ContinueView Course