Handling Mouse Scrolling

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.

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. We receive and handle mouse wheel events within the SDL_PollEvent loop, highlighted below:

1#include <SDL.h>
2#include "Window.h"
3
4int main(int argc, char** argv) {
5  SDL_Init(SDL_INIT_VIDEO);
6  Window GameWindow;
7  SDL_Event Event;
8
9  while(true) {
10    while(SDL_PollEvent(&Event)) {
11      // Detect and handle input events
12      // ...
13    }
14    GameWindow.Update();
15  }
16
17  SDL_Quit();
18  return 0;
19}

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_MOUSEWHEEL:

1while (SDL_PollEvent(&Event)) {
2  if (Event.type == SDL_MOUSEWHEEL) {
3    std::cout << "Mouse wheel input detected\n";
4  }
5}

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

Within the wheel object, the y member variable is an integer that lets us know how far the wheel was scrolled. By default, positive values mean the user scrolled the wheel forward, while negative means they scrolled backward.

1while (SDL_PollEvent(&Event)) {
2  if (Event.type == SDL_MOUSEWHEEL) {
3    std::cout << "Scroll amount: "
4      << Event.wheel.y << '\n';
5  }
6}

Unlike button presses, mouse scrolling is not discreet. It typically takes some amount of time for the user to provide their full scroll input - that is, how far they want to move their wheel.

Even if they're performing a small scroll that may only take a fraction of a second, it is still likely to span multiple frames of our application. To handle this, a typical scroll from the user will result in several SDL_MOUSEWHEEL events, each with a relatively small y value.

The previous program output will be something like this:

1Scroll amount: 1
2Scroll amount: 2
3Scroll amount: 1
4Scroll amount: 1

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.

SDL_MouseWheelEvent

If we want to store or transfer an SDL_Event that has a type of SDL_MOUSEWHEEL, 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:

1// Event Loop
2while (SDL_PollEvent(&Event)) {
3  if (Event.type == SDL_MOUSEWHEEL) {
4    HandleMouseWheel(Event)
5  }
6}

1// Handler
2void HandleMouseWheel(const SDL_MouseWheelEvent& E) {
3  int ScrollAmount { Event.y };
4  // ...
5}

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 the previous lesson:

Handling Mouse Input

Learn how to detect and handle mouse input events in SDL, including mouse motion, button clicks, and window entry/exit.

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:

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

1// Handler
2void HandleMouseButton(SDL_MouseButtonEvent& E) {
3  if (E.button == SDL_BUTTON_MIDDLE) {
4    std::cout << "\nScroll button "
5      << (E.type == SDL_MOUSEBUTTONDOWN
6        ? "pressed" : "released");
7  }
8}

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_MouseWheelEvent 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:

1// Handler
2void HandleMouseWheel(SDL_MouseWheelEvent& E) {
3  int HorizontalScrollAmount{E.x};
4
5  if (HorizontalScrollAmount != 0) {
6    std::cout << "Horizontal scroll detected: "
7      << HorizontalScrollAmount << '\n';
8  }
9}

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

Precise Scroll Distance

On some devices, it is possible to get more precise scroll information than the integers reported in the x and y fields of the SDL_MouseWheelEvent.

If we want to support those devices, we can access the preciseX and preciseY fields instead. These will be floating point numbers:

1// Handler
2void HandleMouseWheel(SDL_MouseWheelEvent& E) {
3  std::cout << "preciseX: " << E.preciseX
4    << ", preciseY: " << E.preciseY << '\n';
5}

1preciseX: 0, preciseY: 1.023
2preciseX: 0, preciseY: 0.853
3preciseX: 0, preciseY: 1.911

When precise scroll distance isn’t supported, the preciseX and preciseY values will fall back to match the regular x and y values, albeit in float form.

Flipped Scroll Direction

On some platforms, users can invert their scroll direction. SDL detects this, and reports whether the user has inverted their scrolling in the direction field of the SDL_MouseWheelEvent. This variable will be an integer that is equal to either SDL_MOUSEWHEEL_NORMAL or SDL_MOUSEWHEEL_FLIPPED:

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

1Using normal direction

The x, y, preciseX, and preciseY values reported by SDL have already considered 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(SDL_MouseWheelEvent& E) {
3  int ScrollAmount{E.direction ==
4    SDL_MOUSEWHEEL_NORMAL ? E.y : E.y * -1};
5}

Mouse Position

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

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

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

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

1// Handler
2void HandleMouseWheel(SDL_MouseWheelEvent& E) {
3  int DistanceFromLeft{E.mouseX};
4  int DistanceFromTop{E.mouseY};
5  int DistanceFromRight{WindowWidth - E.mouseX};
6  int DistanceFromBottom{WindowHeight - E.mouseY};
7}

Summary

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

• Understanding the SDL_MouseWheelEvent structure and its member variables.
• Handling vertical and horizontal scrolling.
• Detecting and responding to scroll wheel button events.
• Using precise scroll distances when supported.
• Accounting for flipped scroll directions and mouse positions during scroll events.

Next Lesson

Managing Mouse Focus with SDL2

Learn how to track and respond to mouse focus events in SDL2, including handling multiple windows and customizing focus-related click behavior.

ContinueView Course