In this lesson, we cover how to detect and react to our user providing input through their mouse scroll wheel. Similar to other forms of input, when these interactions are detected, SDL pushes events into the event queue. Accordingly, we receive these events within our event loop and can react to them as needed.

Starting Point

This lesson builds on our earlier work. If you want to follow along, a minimal project containing a Window class and a main function with a basic application loop are provided below.

We've re-introduced the GetWidth() and GetHeight() methods to our Window class, which will be helpful for examples later in this lesson.

Files

src

Select a file to view its content

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

Mouse Wheel Events

When an event is created by the user interacting with their mouse wheel, the SDL_Event object will have a type of SDL_EVENT_MOUSE_WHEEL:

src/main.cpp

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include <iostream>
4#include "Window.h"
5
6int main(int, char**) {
7  SDL_Init(SDL_INIT_VIDEO);
8  Window GameWindow;
9  SDL_Event Event;
10
11  bool IsRunning{true};
12  while (IsRunning) {
13    while (SDL_PollEvent(&Event)) {
14      if (Event.type == SDL_EVENT_MOUSE_WHEEL) {
15        std::cout << "Mouse wheel input detected\n";
16      } else if (Event.type == SDL_EVENT_QUIT) {
17        IsRunning = false;
18      }
19    }
20    GameWindow.Render();
21    GameWindow.Update();
22  }
23
24  SDL_Quit();
25  return 0;
26}

1Mouse wheel input detected
2Mouse wheel input detected
3Mouse wheel input detected

Within the wheel object, the y member variable is a float in SDL3 that lets us know how far the wheel was scrolled. By default, positive values mean the user scrolled the wheel forward (away from them), while negative values mean they scrolled backward (toward them).

1if (Event.type == SDL_EVENT_MOUSE_WHEEL) {
2  std::cout << "Scroll amount: "
3    << Event.wheel.y << '\n';
4}

Unlike button presses, mouse scrolling is not a discrete input. Users can scroll for as long as they want, but even a tiny scroll that takes only a fraction of a second is likely to span multiple frames of our application.

As such, a single scroll input from the user will result in many SDL_EVENT_MOUSE_WHEEL events, each with a relatively small y value.

The previous program's output will be something like this:

1Scroll amount: 1
2Scroll amount: 2
3Scroll amount: 1
4Scroll amount: 1
5...

This implementation helps us make scroll input feel responsive and smooth. As soon as the user starts their input, we get an event we can react to immediately, even though the user may still be scrolling. The full extent of the scroll (5, in the previous example) is spread across multiple frames.

Using the `SDL_MouseWheelEvent` Type

If we want to store or transfer an SDL_Event that has a type of SDL_EVENT_MOUSE_WHEEL, we can use the more descriptive SDL_MouseWheelEvent subtype.

This type is slightly easier to use as it does not require us to access the intermediate wheel subobject to retrieve the information we care about:

src/main.cpp

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include <iostream>
4#include "Window.h"
5
6void HandleMouseWheel(const SDL_MouseWheelEvent& E) {
7  float ScrollAmount{E.y};
8  std::cout << "Scroll amount: " << ScrollAmount << '\n';
9}
10
11int main(int, char**) {
12  SDL_Init(SDL_INIT_VIDEO);
13  Window GameWindow;
14  SDL_Event Event;
15
16  bool IsRunning = true;
17  while (IsRunning) {
18    while (SDL_PollEvent(&Event)) {
19      if (Event.type == SDL_EVENT_MOUSE_WHEEL) {
20        HandleMouseWheel(Event.wheel);
21      } else if (Event.type == SDL_EVENT_QUIT) {
22        IsRunning = false;
23      }
24    }
25    GameWindow.Render();
26    GameWindow.Update();
27  }
28
29  SDL_Quit();
30  return 0;
31}

Scroll Wheel Button Events

On many mice, the scroll wheel is also a button that can be pressed. This interaction is handled like any other mouse button event, which we covered in a .

The scroll mouse button is typically represented by the SDL_BUTTON_MIDDLE variable, so we can detect scroll button keydown and keyup events like this:

src/main.cpp

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include <iostream>
4#include "Window.h"
5
6void HandleMouseButton(const SDL_MouseButtonEvent& E) {
7  if (E.button == SDL_BUTTON_MIDDLE) {
8    std::cout << "\nScroll button "
9      << (E.down ? "pressed" : "released");
10  }
11}
12
13int main(int, char**) {
14  SDL_Init(SDL_INIT_VIDEO);
15  Window GameWindow;
16  SDL_Event Event;
17
18  bool IsRunning = true;
19  while (IsRunning) {
20    while (SDL_PollEvent(&Event)) {
21      if (Event.type == SDL_EVENT_MOUSE_BUTTON_DOWN ||
22          Event.type == SDL_EVENT_MOUSE_BUTTON_UP) {
23        HandleMouseButton(Event.button);
24      } else if (Event.type == SDL_EVENT_QUIT) {
25        IsRunning = false;
26      }
27    }
28    GameWindow.Render();
29    GameWindow.Update();
30  }
31
32  SDL_Quit();
33  return 0;
34}

1Scroll button pressed
2Scroll button released

Horizontal Scrolling

Some mice allow the user to provide horizontal scroll input, typically by tilting their mouse wheel left or right.

These actions also generate SDL_EVENT_MOUSE_WHEEL events. The amount of horizontal scrolling is represented by the x member variable, where negative values indicate scrolling left and positive values indicate scrolling right:

src/main.cpp

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include <iostream>
4#include "Window.h"
5
6void HandleMouseWheel(const SDL_MouseWheelEvent& E) {
7  float HorizontalScrollAmount{E.x};
8
9  if (HorizontalScrollAmount != 0) {
10    std::cout << "Horizontal scroll detected: "
11      << HorizontalScrollAmount << '\n';
12  }
13}
14
15int main(int, char**) {
16  SDL_Init(SDL_INIT_VIDEO);
17  Window GameWindow;
18  SDL_Event Event;
19
20  bool IsRunning = true;
21  while (IsRunning) {
22    while (SDL_PollEvent(&Event)) {
23      if (Event.type == SDL_EVENT_MOUSE_WHEEL) {
24        HandleMouseWheel(Event.wheel);
25      } else if (Event.type == SDL_EVENT_QUIT) {
26        IsRunning = false;
27      }
28    }
29    GameWindow.Render();
30    GameWindow.Update();
31  }
32
33  SDL_Quit();
34  return 0;
35}

1Horizontal scroll detected: -1
2Horizontal scroll detected: 1

Flipped Scroll Direction

On some platforms, users can invert their scroll direction (often called "natural scrolling"). SDL detects this and reports it in the direction field of the SDL_MouseWheelEvent. This variable will be equal to either SDL_MOUSEWHEEL_NORMAL or SDL_MOUSEWHEEL_FLIPPED:

1void HandleMouseWheel(const SDL_MouseWheelEvent& E) {
2  if (E.direction == SDL_MOUSEWHEEL_NORMAL) {
3    std::cout << "Using normal direction\n";
4  } else if (E.direction == SDL_MOUSEWHEEL_FLIPPED) {
5    std::cout << "Using flipped direction\n";
6  }
7}

1Using normal direction

The x, y, integer_x, and integer_y values reported by SDL have already accounted for the user's preferred direction, so in most cases, we can ignore this.

However, if we wanted to override the user's individual preferences and ensure scrolling works the same for everyone, we can conditionally multiply the scroll values by -1 before using them:

1// Handler
2void HandleMouseWheel(const SDL_MouseWheelEvent& E) {
3  float ScrollAmount{E.direction ==
4    SDL_MOUSEWHEEL_NORMAL ? E.y : E.y * -1};
5    
6  // ...
7}

Mouse Position

Sometimes, we need to know where the cursor was when a scroll event occurred. These coordinates are available through the mouse_x and mouse_y variables of the SDL_MouseWheelEvent:

src/main.cpp

1// ...
2void HandleMouseWheel(const SDL_MouseWheelEvent& E) {
3  std::cout << "\nScroll event happened at "
4            << "x = " << E.mouse_x
5            << ", y = " << E.mouse_y;
6}
7// ...

1Scroll event happened at x = 446, y = 181

Similar to SDL_MouseMotionEvents, the coordinates are relative to the top-left corner of our window. If needed, we can determine the distance from the right and bottom edges by subtracting them from our window's width and height:

src/main.cpp

1// ...
2void HandleMouseWheel(
3  const SDL_MouseWheelEvent& E,
4  const Window& GameWindow
5) {
6  float DistanceFromLeft{E.mouse_x};
7  float DistanceFromTop{E.mouse_y};
8  float DistanceFromRight{
9    GameWindow.GetWidth() - E.mouse_x};
10  float DistanceFromBottom{
11    GameWindow.GetHeight() - E.mouse_y};
12}
13// ...

Summary

This lesson covered how to detect and handle mouse scroll wheel events. Key points include:

Understanding the SDL_EVENT_MOUSE_WHEEL event and the SDL_MouseWheelEvent structure.
Handling vertical (y) and horizontal (x) scrolling as float values.
Detecting and responding to scroll wheel button events.
Using preciseX and preciseY for high-precision scrolling when supported.
Accounting for flipped scroll directions and retrieving the mouse position (mouse_x, mouse_y) during scroll events.

Handling Mouse Scrolling

Starting Point

Files

Mouse Wheel Events

src/main.cpp

Using the `SDL_MouseWheelEvent` Type

src/main.cpp

Scroll Wheel Button Events

src/main.cpp

Horizontal Scrolling

src/main.cpp

Flipped Scroll Direction

Mouse Position

src/main.cpp

src/main.cpp

Summary

Managing Mouse Focus

Game Development with SDL3

Handling Mouse Scrolling

Starting Point

Files

Mouse Wheel Events

src/main.cpp

Using the SDL_MouseWheelEvent Type

src/main.cpp

Scroll Wheel Button Events

src/main.cpp

Horizontal Scrolling

src/main.cpp

Flipped Scroll Direction

Mouse Position

src/main.cpp

src/main.cpp

Summary

Managing Mouse Focus

Using the `SDL_MouseWheelEvent` Type