From 3296031ad74f8cdc9638ae948b5372a81a43a2d1 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sun, 20 Aug 2023 11:09:40 +0300 Subject: [PATCH] ; Another improvement for documentation of pixelwise scrolling * doc/lispref/commands.texi (Misc Events): More details about pixelwise mouse-wheel scrolling events. (Bug#65070) --- doc/lispref/commands.texi | 32 ++++++++++++++++++++++---------- 1 file changed, 22 insertions(+), 10 deletions(-) diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi index 028209b2bc1..110b2479d11 100644 --- a/doc/lispref/commands.texi +++ b/doc/lispref/commands.texi @@ -2242,11 +2242,12 @@ mouse cursor when the finger moved off the mouse wheel. @cindex @code{wheel-down} event @item (wheel-up @var{position} @var{clicks} @var{lines} @var{pixel-delta}) @itemx (wheel-down @var{position} @var{clicks} @var{lines} @var{pixel-delta}) -These kinds of event are generated by moving a mouse wheel. The +These events are generated by moving a mouse wheel. The @var{position} element is a mouse position list (@pxref{Click Events}), specifying the position of the mouse cursor when the event occurred. +@vindex mwheel-coalesce-scroll-events @var{clicks}, if present, is the number of times that the wheel was moved in quick succession. @xref{Repeat Events}. @var{lines}, if present and not @code{nil}, is the positive number of screen lines @@ -2254,24 +2255,35 @@ that should be scrolled (either up, when the event is @code{wheel-up}, or down when the event is @code{wheel-down}). @var{pixel-delta}, if present, is a cons cell of the form @w{@code{(@var{x} . @var{y})}}, where @var{x} and @var{y} are the numbers of pixels by which to scroll -in each axis, a.k.a.@: @dfn{pixelwise deltas}. +in each axis, a.k.a.@: @dfn{pixelwise deltas}. Usually, only one of +the two will be non-zero, the other will be either zero or very close +to zero; the larger number indicates the axis to scroll the window. +When the variable @code{mwheel-coalesce-scroll-events} is @code{nil}, +the scroll commands ignore the @var{lines} element, even if it's +non-@code{nil}, and use the @var{pixel-delta} data instead; in that +case, the direction of scrolling is determined by the sign of the +pixelwise deltas, and the direction (up or down) implied by the event +kind is ignored. @cindex pixel-resolution wheel events You can use these @var{x} and @var{y} pixelwise deltas to determine how much the mouse wheel has actually moved at pixel resolution. For example, the pixelwise deltas could be used to scroll the display at pixel resolution, exactly according to the user's turning the mouse -wheel. +wheel. This pixelwise scrolling is possible only when +@code{mwheel-coalesce-scroll-events} is @code{nil}, and in general the +@var{pixel-delta} data is not generated when that variable is +non-@code{nil}. @vindex mouse-wheel-up-event @vindex mouse-wheel-down-event -This kind of event is generated only on some kinds of systems. On -some systems, @code{mouse-4} and @code{mouse-5} are used instead. For -portable code, use the variables @code{mouse-wheel-up-event}, -@code{mouse-wheel-up-alternate-event}, @code{mouse-wheel-down-event} -and @code{mouse-wheel-down-alternate-event} defined in -@file{mwheel.el} to determine what event types to expect for the mouse -wheel. +The @code{wheel-up} and @code{wheel-down} events are generated only on +some kinds of systems. On other systems, @code{mouse-4} and +@code{mouse-5} are used instead. For portable code, use the variables +@code{mouse-wheel-up-event}, @code{mouse-wheel-up-alternate-event}, +@code{mouse-wheel-down-event} and +@code{mouse-wheel-down-alternate-event} defined in @file{mwheel.el} to +determine what event types to expect from the mouse wheel. @vindex mouse-wheel-left-event @vindex mouse-wheel-right-event -- 2.39.5