Add MouseWheelSource and InputState::scroll_source() (#8665)

Lets you tell what is driving a scroll: a mouse wheel, fingers on a
trackpad (not a touch screen), or the OS continuing a trackpad swipe
with momentum.

```rust
pub enum MouseWheelSource {
    Unknown,
    Wheel,
    Trackpad,
    Momentum,
}
```

* `Event::MouseWheel` gains `source: MouseWheelSource`. Integrations set
it to `Unknown` if they don't know.
* `InputState::scroll_source() -> Option<MouseWheelSource>`: what is
driving the current scrolling, `Some` while `is_scrolling()`. For a
trackpad that covers the whole gesture (`TouchPhase::Start`…`End`); for
a mouse wheel, until the smoothing of the last notch is done. Touch
screens scroll by dragging with the pointer, not with wheel events, so
`None` there.

Use cases: a `ScrollArea` can rubber-band and hold while fingers rest on
the trackpad, but bounce during momentum (#8663, built on this). A
slider or plot can ignore `Momentum` so a flick doesn't keep changing a
value after the fingers lift.

**Where the source is known**
* macOS (eframe): `Wheel`, `Trackpad` or `Momentum`. winit folds the
macOS momentum phase into the regular `TouchPhase`, so egui-winit reads
`NSEvent::momentumPhase` itself through a local event monitor
(`macos_scroll_momentum.rs`, owned by `State`, removed on drop). Precise
deltas are `Trackpad`, line deltas `Wheel`. Goes away once we are on a
winit with rust-windowing/winit#4732; marked with TODOs.
* winit `PanGesture`: `Trackpad`.
* Everywhere else: `Unknown`. Web `WheelEvent`s carry no phase or source
at all.

**Also**: the 150 ms scroll-action timeout from #8636 is tuned for
flowing events. Fingers resting on a trackpad produce none, so a known
`Trackpad` gesture now survives a 1 s gap before being considered over.
The enum mirrors the one proposed for winit.

* [x] I have followed the instructions in the PR template

🤖 Generated with [Claude Code](https://claude.com/claude-code)
This commit is contained in:
Emil Ernerfeldt authored and GitHub committed 2026-10-04 18:45:20 +00:00
1 parent 69a8b71eb5
commit e45775e450
12 files changed
+273 -7

No files matched your search

+2
View File
@@ -1336,11 +1336,13 @@ version = "0.36.2"
dependencies = [
"accesskit_winit",
"arboard",
"block2 0.6.2",
"bytemuck",
"document-features",
"egui",
"log",
"objc2 0.6.4",
"objc2-app-kit 0.3.2",
"objc2-foundation 0.3.2",
"objc2-ui-kit 0.3.2",
"profiling",
+1
View File
@@ -112,6 +112,7 @@ mimalloc = "0.1.52"
mime_guess2 = { version = "2.3", default-features = false }
mint = "0.5.9"
nohash-hasher = "0.2.0"
block2 = "0.6.2"
objc2 = "0.6.4"
objc2-app-kit = { version = "0.3.2", default-features = false }
objc2-foundation = { version = "0.3.2", default-features = false }
+1
View File
@@ -849,6 +849,7 @@ fn install_wheel(runner_ref: &WebRunner, target: &EventTarget) -> Result<(), JsV
delta,
modifiers,
phase: egui::TouchPhase::Move,
source: egui::MouseWheelSource::Unknown,
}
};
let should_stop_propagation = (runner.web_options.should_stop_propagation)(&egui_event);
+11
View File
@@ -79,6 +79,17 @@ document-features = { workspace = true, optional = true }
serde = { workspace = true, optional = true }
webbrowser = { workspace = true, optional = true }
# TODO(emilk): remove these once we are on a winit with https://github.com/rust-windowing/winit/pull/4732
[target.'cfg(target_os = "macos")'.dependencies]
block2.workspace = true
objc2.workspace = true
objc2-app-kit = { workspace = true, default-features = false, features = [
"std",
"block2",
"NSEvent",
"NSResponder",
] }
[target.'cfg(target_os = "ios")'.dependencies]
objc2.workspace = true
objc2-foundation = { workspace = true, features = ["std", "NSThread"] }
+38
View File
@@ -20,6 +20,10 @@ use egui::accesskit;
use egui::{Pos2, Rect, Theme, Vec2, ViewportBuilder, ViewportCommand, ViewportId, ViewportInfo};
pub use winit;
// TODO(emilk): remove once we are on a winit with https://github.com/rust-windowing/winit/pull/4732
#[cfg(target_os = "macos")]
mod macos_scroll_momentum;
pub mod clipboard;
#[cfg(not(target_arch = "wasm32"))]
mod dropped_file;
@@ -128,6 +132,10 @@ pub struct State {
ime_rect_px: Option<egui::Rect>,
old_ime_purpose: egui::IMEPurpose,
// TODO(emilk): remove once we are on a winit with https://github.com/rust-windowing/winit/pull/4732
#[cfg(target_os = "macos")]
scroll_momentum_monitor: Option<macos_scroll_momentum::ScrollMomentumMonitor>,
/// Used by [`State::try_on_ime_processed_keyboard_input`] to track key
/// release events that should be filtered out. See comments in that method
/// for details.
@@ -178,6 +186,8 @@ impl State {
allow_ime: false,
ime_rect_px: None,
old_ime_purpose: egui::IMEPurpose::Normal,
#[cfg(target_os = "macos")]
scroll_momentum_monitor: macos_scroll_momentum::ScrollMomentumMonitor::install(),
#[cfg(target_os = "windows")]
pressed_processed_physical_keys: HashSet::new(),
};
@@ -577,6 +587,7 @@ impl State {
unit: egui::MouseWheelUnit::Point,
delta: Vec2::new(delta.x, delta.y) / pixels_per_point,
phase: to_egui_touch_phase(*phase),
source: egui::MouseWheelSource::Trackpad,
modifiers: self.modifiers,
});
EventResponse {
@@ -974,10 +985,37 @@ impl State {
};
let phase = to_egui_touch_phase(phase);
let modifiers = self.modifiers;
// winit doesn't tell us what is driving the scroll, and collapses the macOS
// momentum phase into the regular `TouchPhase`, so we detect that ourselves.
// TODO(emilk): use `WindowEvent::MouseWheel::source` once we are on a winit
// with https://github.com/rust-windowing/winit/pull/4732
let source = cfg_select! {
target_os = "macos" => {
if self
.scroll_momentum_monitor
.as_ref()
.is_some_and(|monitor| monitor.latest_scroll_event_is_momentum())
{
egui::MouseWheelSource::Momentum
} else {
// On macOS, only trackpads (and the Magic Mouse) report precise deltas:
match unit {
egui::MouseWheelUnit::Point => egui::MouseWheelSource::Trackpad,
egui::MouseWheelUnit::Line | egui::MouseWheelUnit::Page => {
egui::MouseWheelSource::Wheel
}
}
}
}
_ => egui::MouseWheelSource::Unknown,
};
self.egui_input.events.push(egui::Event::MouseWheel {
unit,
delta,
phase,
source,
modifiers,
});
}
@@ -0,0 +1,89 @@
//! Detect the OS-driven momentum ("kinetic") phase of trackpad scrolling on macOS.
//!
//! `AppKit` reports it via `NSEvent::momentumPhase`, but winit collapses that into the
//! regular `TouchPhase`, so a momentum scroll looks just like a second finger scroll.
//! We observe the raw `NSEvent`s ourselves with a local event monitor and remember
//! whether the latest scroll event was part of the momentum phase.
//!
//! TODO(emilk): remove this module once we are on a winit version that includes
//! <https://github.com/rust-windowing/winit/pull/4732>, which adds `ScrollSource`
//! to `WindowEvent::MouseWheel`. Then read `source == ScrollSource::Momentum` instead.
//!
//! The monitor runs before the event is dispatched to the window, so when winit hands us
//! the corresponding `MouseWheel` event, the flag describes it. If several scroll events
//! are delivered before winit dispatches them, the flag describes the last one; only the
//! `Start` of a gesture reads the flag, so the worst case is a very short momentum
//! phase being taken for a finger scroll.
#![allow(unsafe_code)] // Talking to AppKit
use core::ptr::NonNull;
use core::sync::atomic::{AtomicBool, Ordering};
use std::sync::Arc;
use objc2::MainThreadMarker;
use objc2::rc::Retained;
use objc2::runtime::AnyObject;
use objc2_app_kit::{NSEvent, NSEventMask, NSEventPhase};
/// Observes scroll events for as long as it lives.
pub struct ScrollMomentumMonitor {
/// The `NSEvent` local monitor. Removed on drop.
monitor: Retained<AnyObject>,
/// Keeps the handler alive for as long as the monitor is installed.
_handler: block2::RcBlock<dyn Fn(NonNull<NSEvent>) -> *mut NSEvent>,
/// Was the latest scroll event part of the OS-driven momentum phase?
latest_is_momentum: Arc<AtomicBool>,
}
impl ScrollMomentumMonitor {
/// Start observing scroll events.
///
/// Returns `None` when not on the main thread, since `AppKit` requires it.
pub fn install() -> Option<Self> {
if MainThreadMarker::new().is_none() {
log::debug!("Not on the main thread; cannot detect momentum scrolling");
return None;
}
let latest_is_momentum = Arc::new(AtomicBool::new(false));
let handler = {
let latest_is_momentum = Arc::clone(&latest_is_momentum);
block2::RcBlock::new(move |event: NonNull<NSEvent>| -> *mut NSEvent {
// SAFETY: AppKit hands us a valid event for the duration of the call.
let is_momentum = unsafe { event.as_ref() }.momentumPhase() != NSEventPhase::None;
latest_is_momentum.store(is_momentum, Ordering::Relaxed);
event.as_ptr() // Pass the event on unchanged
})
};
// SAFETY: we are on the main thread, and the handler returns a valid event pointer.
let monitor = unsafe {
NSEvent::addLocalMonitorForEventsMatchingMask_handler(
NSEventMask::ScrollWheel,
&handler,
)
}?;
Some(Self {
monitor,
_handler: handler,
latest_is_momentum,
})
}
/// Was the latest scroll event part of the OS-driven momentum phase?
pub fn latest_scroll_event_is_momentum(&self) -> bool {
self.latest_is_momentum.load(Ordering::Relaxed)
}
}
impl Drop for ScrollMomentumMonitor {
fn drop(&mut self) {
// SAFETY: `monitor` came from `addLocalMonitorForEventsMatchingMask_handler`.
unsafe { NSEvent::removeMonitor(&self.monitor) };
}
}
+7
View File
@@ -1,5 +1,6 @@
use epaint::ColorImage;
use crate::MouseWheelSource;
use crate::{
Key,
emath::{Pos2, Vec2},
@@ -176,6 +177,12 @@ pub enum Event {
/// If unknown set this to [`TouchPhase::Move`].
phase: TouchPhase,
/// What is driving the scroll: a wheel, fingers on a trackpad,
/// or the system continuing a finger scroll with momentum.
///
/// Set this to [`MouseWheelSource::Unknown`] if unknown.
source: MouseWheelSource,
/// The state of the modifier keys at the time of the event.
modifiers: Modifiers,
},
+2
View File
@@ -8,6 +8,7 @@ mod ime_event;
mod keyboard_shortcut;
mod modifier_names;
mod modifiers;
mod mouse_wheel_source;
mod mouse_wheel_unit;
mod pointer_button;
mod raw_input;
@@ -24,6 +25,7 @@ pub use self::{
keyboard_shortcut::KeyboardShortcut,
modifier_names::ModifierNames,
modifiers::Modifiers,
mouse_wheel_source::MouseWheelSource,
mouse_wheel_unit::MouseWheelUnit,
pointer_button::{NUM_POINTER_BUTTONS, PointerButton},
raw_input::RawInput,
@@ -0,0 +1,36 @@
/// What is driving an [`crate::Event::MouseWheel`] event.
///
/// This lets a [`crate::ScrollArea`] treat the different kinds of scrolling differently,
/// e.g. rubber-band past the edge while the fingers are on the trackpad,
/// but bounce during the system-driven momentum phase.
///
/// This is about mice and trackpads. Touch screens don't produce [`crate::Event::MouseWheel`]
/// events at all; they scroll by dragging with the pointer (see [`crate::Event::Touch`]).
///
/// ## Platform-specific
/// * **macOS**: [`Self::Wheel`], [`Self::Trackpad`] or [`Self::Momentum`].
/// * **Wayland, Windows, X11, web**: always [`Self::Unknown`], until winit reports the source.
#[derive(Clone, Copy, Debug, Eq, PartialEq, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Deserialize, serde::Serialize))]
pub enum MouseWheelSource {
/// The platform doesn't say.
Unknown,
/// A physical wheel, usually on a mouse.
Wheel,
/// Fingers moving on a trackpad (or similar touch surface, like a Magic Mouse).
///
/// Not a touch screen: those scroll by dragging with the pointer, see [`crate::Event::Touch`].
///
/// On platforms that report a [`crate::TouchPhase`], the fingers are on the trackpad
/// from [`crate::TouchPhase::Start`] until [`crate::TouchPhase::End`].
Trackpad,
/// The system is continuing a finger scroll after the fingers were lifted,
/// with decaying speed, such as the "momentum phase" on macOS.
///
/// On platforms that report a [`crate::TouchPhase`], this gets its own
/// [`crate::TouchPhase::Start`] … [`crate::TouchPhase::End`] cycle after the finger one.
Momentum,
}
+21 -1
View File
@@ -2,7 +2,7 @@ mod touch_state;
mod wheel_state;
use crate::{
SafeAreaInsets,
MouseWheelSource, SafeAreaInsets,
emath::{NumExt as _, Pos2, Rect, Vec2, vec2},
util::History,
};
@@ -416,6 +416,7 @@ impl InputState {
unit,
delta,
phase,
source,
modifiers,
} => {
self.wheel.on_wheel_event(
@@ -425,6 +426,7 @@ impl InputState {
*unit,
*delta,
*phase,
*source,
*modifiers,
);
}
@@ -639,6 +641,24 @@ impl InputState {
self.wheel.is_scrolling()
}
/// What is driving the current scrolling, if any: a mouse wheel, fingers on a trackpad,
/// or the OS continuing a trackpad scroll with momentum.
///
/// `Some` while [`Self::is_scrolling`]. For trackpads, that is between the
/// [`crate::TouchPhase::Start`] and [`crate::TouchPhase::End`] of the gesture;
/// for mouse wheels, until the smoothing of the last notch is done.
///
/// Touch screens don't scroll with wheel events but by dragging with the pointer,
/// so this is `None` for them.
///
/// ## Platform-specific
/// * **macOS**: `Wheel`, `Trackpad` or `Momentum`, all reliable.
/// * **Everywhere else**: `Unknown`, until winit reports the source
/// (`Trackpad` for winit's `PanGesture`).
pub fn scroll_source(&self) -> Option<MouseWheelSource> {
self.wheel.is_scrolling().then_some(self.wheel.source)
}
/// How long has it been (in seconds) since the last scroll event?
#[inline(always)]
pub fn time_since_last_scroll(&self) -> f32 {
+62 -3
View File
@@ -1,6 +1,6 @@
use emath::{Rect, Vec2, vec2};
use crate::{InputOptions, Modifiers, MouseWheelUnit, TouchPhase};
use crate::{InputOptions, Modifiers, MouseWheelSource, MouseWheelUnit, TouchPhase};
/// If there has been no scroll event for this many seconds, the scroll action is over.
///
@@ -8,6 +8,11 @@ use crate::{InputOptions, Modifiers, MouseWheelUnit, TouchPhase};
/// was 68 ms. But we add some margin to be safe.
const SCROLL_ACTION_TIMEOUT: f64 = 0.150;
/// Like [`SCROLL_ACTION_TIMEOUT`], but for fingers resting on a trackpad mid-gesture,
/// which produce no events at all. Where we know the source is a finger (macOS),
/// the [`TouchPhase::End`] is reliable, so this is just a safety net.
const RESTING_FINGER_TIMEOUT: f64 = 1.0;
/// The current state of scrolling.
///
/// There are two important types of scroll input deviced:
@@ -53,6 +58,9 @@ pub struct WheelState {
/// but we are in a kinetic scroll or in a smoothed scroll.
pub status: Status,
/// What drove the latest scroll event: a wheel, fingers on a trackpad, OS momentum…
pub source: MouseWheelSource,
/// The modifiers at the start of the scroll.
pub modifiers: Modifiers,
@@ -81,6 +89,7 @@ impl Default for WheelState {
fn default() -> Self {
Self {
status: Status::Static,
source: MouseWheelSource::Unknown,
modifiers: Default::default(),
last_wheel_event: f64::NEG_INFINITY,
unprocessed_wheel_delta: Vec2::ZERO,
@@ -99,6 +108,7 @@ impl WheelState {
unit: MouseWheelUnit,
delta: Vec2,
phase: TouchPhase,
source: MouseWheelSource,
latest_modifiers: Modifiers,
) {
if self.is_scroll_action_over(time) {
@@ -110,6 +120,7 @@ impl WheelState {
}
self.last_wheel_event = time;
self.source = source;
match phase {
crate::TouchPhase::Start => {
self.status = Status::InTouch;
@@ -203,7 +214,13 @@ impl WheelState {
/// and on others (e.g. some mouse wheels on Wayland) we get a start but no stop event,
/// so we rely on a timer.
fn is_scroll_action_over(&self, time: f64) -> bool {
self.status != Status::Static && SCROLL_ACTION_TIMEOUT < time - self.last_wheel_event
let timeout = if self.status == Status::InTouch && self.source == MouseWheelSource::Trackpad
{
RESTING_FINGER_TIMEOUT
} else {
SCROLL_ACTION_TIMEOUT
};
self.status != Status::Static && timeout < time - self.last_wheel_event
}
fn end_scroll_action(&mut self) {
@@ -219,6 +236,7 @@ impl WheelState {
pub fn ui(&self, ui: &mut crate::Ui) {
let Self {
status,
source,
modifiers,
last_wheel_event,
unprocessed_wheel_delta,
@@ -234,6 +252,10 @@ impl WheelState {
ui.monospace(format!("{status:?}"));
ui.end_row();
ui.label("source");
ui.monospace(format!("{source:?}"));
ui.end_row();
ui.label("modifiers");
ui.monospace(format!("{modifiers:?}"));
ui.end_row();
@@ -257,13 +279,20 @@ impl WheelState {
mod tests {
use emath::{Vec2, vec2};
use crate::{Context, Event, Modifiers, MouseWheelUnit, RawInput, TouchPhase};
use crate::{
Context, Event, Modifiers, MouseWheelSource, MouseWheelUnit, RawInput, TouchPhase,
};
fn wheel(phase: TouchPhase, modifiers: Modifiers) -> Event {
wheel_from(phase, MouseWheelSource::Unknown, modifiers)
}
fn wheel_from(phase: TouchPhase, source: MouseWheelSource, modifiers: Modifiers) -> Event {
Event::MouseWheel {
unit: MouseWheelUnit::Point,
delta: vec2(0.0, -5.0),
phase,
source,
modifiers,
}
}
@@ -384,4 +413,34 @@ mod tests {
"a new scroll action without shift is vertical"
);
}
/// Fingers resting on a trackpad produce no events, but the scroll action is still going.
#[test]
fn resting_fingers_keep_the_scroll_action_alive() {
let ctx = Context::default();
let finger = MouseWheelSource::Trackpad;
run_frame(
&ctx,
0.0,
vec![
wheel_from(TouchPhase::Start, finger, Modifiers::NONE),
wheel_from(TouchPhase::Move, finger, Modifiers::NONE),
],
);
let (_, _, is_scrolling) = run_frame(&ctx, 0.5, vec![]);
assert!(is_scrolling, "fingers are resting on the trackpad");
let (_, _, is_scrolling) = run_frame(&ctx, 1.5, vec![]);
assert!(
!is_scrolling,
"but we give up eventually, in case the end got lost"
);
// Without a known finger source, the short timeout applies:
run_frame(&ctx, 2.0, vec![wheel(TouchPhase::Start, Modifiers::NONE)]);
let (_, _, is_scrolling) = run_frame(&ctx, 2.5, vec![]);
assert!(!is_scrolling);
}
}
+3 -3
View File
@@ -490,9 +490,9 @@ pub use self::{
Key, ScreenshotCallback,
input::{
DroppedFile, DroppedFileHandle, Event, EventFilter, HoveredFile, ImeEvent,
KeyboardShortcut, ModifierNames, Modifiers, MouseWheelUnit, NUM_POINTER_BUTTONS,
PointerButton, RawInput, SafeAreaInsets, TouchDeviceId, TouchId, TouchPhase,
ViewportEvent, ViewportInfo,
KeyboardShortcut, ModifierNames, Modifiers, MouseWheelSource, MouseWheelUnit,
NUM_POINTER_BUTTONS, PointerButton, RawInput, SafeAreaInsets, TouchDeviceId, TouchId,
TouchPhase, ViewportEvent, ViewportInfo,
},
output::{
self, CursorIcon, CustomCursorImage, FullOutput, LogicOutput, OpenUrl, OutputCommand,