add MouseWheelTurnsPage, fix wheel page turn at page edge (fixes #5069)

Two mouse-wheel problems on a page zoomed past the window.

RememberViewOffsetOnPageTurn applied to the page turn the wheel does when
it runs off the bottom of a page. That offset is the bottom - that is how
you got there - so the next page opened at its bottom, skipping its top,
and since the view was still at the bottom every further notch flipped
another page (pages 2 to 8 in six notches, showing only a sliver of each).
Reaching a page edge by scrolling now opens the next page at its top:
DisplayModel::GoToNextPage(bool keepViewOffset), false from the wheel.
Explicit page turns (N / P, click-to-turn, toolbar) are unchanged, as is
the up direction, which already went to the bottom of the previous page.

MouseWheelTurnsPage (default false) makes one notch a page turn instead of
a scroll, even when the page needs scrolling. It goes through the same
GoToNextPage / GoToPrevPage as N / P, so it composes with
RememberViewOffsetOnPageTurn: the view stays parked on the part of the
page you are reading and the pages move under it. Alt + wheel still
scrolls so the rest of the page is reachable; Shift + wheel and
Ctrl + wheel are unchanged. Deltas accumulate against WHEEL_DELTA so a
precision touchpad doesn't fly through the document.

Toggle it without editing settings with the existing
CmdToggleBoolSetting MouseWheelTurnsPage, documented in Commands.md and
Scrolling-and-zooming.md with a Key + ToolbarText shortcut example.

prompt: analyze issue 5069 and decide what the mouse wheel should do when RememberViewOffsetOnPageTurn is on, then implement it, documenting the existing CmdToggleBoolSetting instead of adding a new toggle command

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: kjk

cmd/gen-settings.ts

@@ -1172,6 +1172,14 @@ const globalPrefs: Field[] = [
     "if true, next/previous page keeps the same view position on the page " +
       "instead of jumping to the top (useful when zoomed in on similarly sized pages)",
   ).ver("3.7"),
+  field(
+    "MouseWheelTurnsPage",
+    Bool,
+    false,
+    "if true, one mouse-wheel notch goes to the next / previous page instead of scrolling; " +
+      "combine with RememberViewOffsetOnPageTurn to read zoomed-in pages without touching the keyboard. " +
+      "Alt + wheel still scrolls, Shift + wheel scrolls horizontally and Ctrl + wheel zooms",
+  ).ver("3.7"),
   field(
     "ShowDocumentFocusIndicator",
     Bool,

docs/md/Advanced-options-settings.md

@@ -178,6 +178,12 @@ DisableLinks = false
 ; (introduced in version 3.7)
 RememberViewOffsetOnPageTurn = false
 
+; if true, one mouse-wheel notch goes to the next / previous page instead of
+; scrolling; combine with RememberViewOffsetOnPageTurn to read zoomed-in pages
+; without touching the keyboard. Alt + wheel still scrolls, Shift + wheel
+; scrolls horizontally and Ctrl + wheel zooms (introduced in version 3.7)
+MouseWheelTurnsPage = false
+
 ; if true, draw a focus ring around the document when it has keyboard focus (Tab
 ; to the page area) (introduced in version 3.7)
 ShowDocumentFocusIndicator = false

docs/md/Commands.md

@@ -537,6 +537,21 @@ Shortcuts [
 ]
 ```
 
+Add `ToolbarText` to the same entry to also get a toolbar button for it. Example: turn the reading mode of [`MouseWheelTurnsPage`](Advanced-options-settings.md) on and off with `w` or from the toolbar:
+
+```
+Shortcuts [
+	[
+		Cmd = CmdToggleBoolSetting MouseWheelTurnsPage
+		Key = w
+		Name = Wheel Turns Page
+		ToolbarText = Wheel Turns Page
+	]
+]
+```
+
+The same works for any other boolean advanced setting, e.g. `CmdToggleBoolSetting RememberViewOffsetOnPageTurn` or `CmdToggleBoolSetting ClickEdgeToTurnPage`.
+
 ## `CmdZoomCustom`
 
 **Ver 3.6+**

docs/md/Scrolling-and-zooming.md

@@ -23,6 +23,26 @@ There are many ways to navigate around the document.
 - press `Alt` while scrolling : scrolls faster (by half page instead of by line)
 - mouse over scrollbar : scrolls faster (by half page instead of by line)
 
+## Reading zoomed-in pages without the keyboard
+
+When a page is zoomed past the window you usually care about one band of it — the music staves, the text inside wide scan margins — and want the next page to open at that same place. Two advanced settings do that:
+
+- `RememberViewOffsetOnPageTurn = true` : next / previous page keeps the view where it is instead of jumping to the top of the new page. It applies to page turns you ask for (`n` / `p`, click-to-turn, the toolbar arrows). Wheeling off the bottom of a page still opens the next page at its top, since that is you reading on, not turning a page.
+- `MouseWheelTurnsPage = true` : one wheel notch is a page turn rather than a scroll. `Alt + wheel` still scrolls, so you can always reach the rest of the page; `Shift + wheel` (horizontal) and `Ctrl + wheel` (zoom) are unchanged.
+
+Turn on both and the wheel becomes a page turner while the view stays parked where you put it. To switch the mode on and off without editing the settings file, bind it to a key or a toolbar button with [`CmdToggleBoolSetting`](Commands.md#cmdtoggleboolsetting):
+
+```
+Shortcuts [
+    [
+        Cmd = CmdToggleBoolSetting MouseWheelTurnsPage
+        Key = w
+        Name = Wheel Turns Page
+        ToolbarText = Wheel Turns Page
+    ]
+]
+```
+
 # Zooming and changing view
 
 ## With keyboard

docs/md/Version-history.md

@@ -28,7 +28,8 @@ Available in [pre-release](https://www.sumatrapdfreader.org/prerelease) builds.
 - PDF bookmark / link destinations now apply Adobe-style view modes (`/Fit`, `/FitH`, `/FitV`, `/FitB`, `/FitBH`, `/FitBV`, `/XYZ` zoom) instead of only jumping to the page (fixes #5828)
 - add `IgnoreDestinationZoom` advanced setting: when true, clicking a bookmark or a link inside the document keeps the zoom you are reading at instead of switching to the zoom the destination asks for; it still goes to the page and the position on it. The same option Adobe Reader and Foxit call "forbid the change of the current Zoom factor during execution of 'Go to Destination' actions"; off by default (discussion #5938)
 - add `DisableLinks` advanced setting (default **false**): when true, document links are ignored so you can select and read without accidentally following them — useful for drawings and schematics with many links. Toggle it from the command palette. The existing **Toggle Show Links** only draws a blue outline around links; it does not disable them (fixes #5939)
-- add `RememberViewOffsetOnPageTurn` advanced setting (default **false**): next/previous page keeps the same view position on the new page instead of jumping to the top, so zoomed-in pages of similar size stay lined up (fixes #5069)
+- add `RememberViewOffsetOnPageTurn` advanced setting (default **false**): next/previous page keeps the same view position on the new page instead of jumping to the top, so zoomed-in pages of similar size stay lined up. It applies to explicit page turns (`N` / `P`, click-to-turn, the toolbar arrows); wheeling off the bottom of a page still opens the next page at its top, because there you are continuing to read rather than turning a page (fixes #5069)
+- add `MouseWheelTurnsPage` advanced setting (default **false**): one wheel notch goes to the next / previous page instead of scrolling, even when the page is zoomed past the window. Together with `RememberViewOffsetOnPageTurn` the view stays parked on the part of the page you are reading and the pages move under it, which is how sheet music and scans with wide margins are read without touching the keyboard. `Alt + wheel` still scrolls, so the rest of the page stays reachable, and `Shift + wheel` (horizontal) and `Ctrl + wheel` (zoom) are unchanged. Bind it to a key or a toolbar button with `CmdToggleBoolSetting MouseWheelTurnsPage` (fixes #5069)
 - `EBookUI` and `ComicBookUI` each have their own `DefaultDisplayMode` so ebooks and comics can open in a different layout than PDFs (empty keeps the global `DefaultDisplayMode`) (fixes #2588)
 - `ComicBookUI.DefaultZoom` sets the first-open zoom for comic archives (`.cbz`, `.cbr`, …); empty keeps the global `DefaultZoom`. Use `fit width` so new comics fill the window while PDFs stay at Fit Page (fixes #5946)
 - add `EBookUI.FontName` advanced setting: the font family for ebooks (EPUB, MOBI, FB2, …), e.g. `Segoe UI` or `Microsoft YaHei`. Empty (the default) keeps the engine serif. When set, it overrides the document's own `font-family` so you can read in a sans-serif or a CJK UI font without editing the file (fixes #3138)

src/Canvas.cpp

@@ -3507,6 +3507,25 @@ static LRESULT CanvasOnMouseWheel(MainWindow* win, UINT msg, WPARAM wp, LPARAM l
         scrollIntent.armed = true;
     }
 
+    // MouseWheelTurnsPage: a wheel notch is a page turn, not a scroll, even when
+    // the page is zoomed past the window. Pairs with RememberViewOffsetOnPageTurn
+    // for reading zoomed-in pages (sheet music, scans with wide margins) without
+    // the keyboard. Alt + wheel still scrolls, so the rest of the page is
+    // reachable; Shift + wheel and Ctrl + wheel are unchanged
+    if (vScroll && !isAlt && gGlobalPrefs->mouseWheelTurnsPage) {
+        win->wheelAccumDelta += delta;
+        if (win->wheelAccumDelta >= WHEEL_DELTA) {
+            win->ctrl->GoToPrevPage();
+            win->wheelAccumDelta -= WHEEL_DELTA;
+            ReadAloudOnUserViewChanged(win);
+        } else if (win->wheelAccumDelta <= -WHEEL_DELTA) {
+            win->ctrl->GoToNextPage();
+            win->wheelAccumDelta += WHEEL_DELTA;
+            ReadAloudOnUserViewChanged(win);
+        }
+        return 0;
+    }
+
     // fit content: flip page on wheel, regardless of scrollbar state
     if (vScroll && dm && FitContentWheelFlipsPage(dm) && IsSingle(dm->GetDisplayMode())) {
         win->wheelAccumDelta += delta;
@@ -3700,6 +3719,11 @@ static LRESULT CanvasOnMouseWheel(MainWindow* win, UINT msg, WPARAM wp, LPARAM l
     // logf("  flip page: delta: %d, accumDelta: %d\n", (int)delta, (int)win->wheelAccumDelta);
     if (delta > 0) {
         win->ctrl->GoToPrevPage(true);
+    } else if (dm) {
+        // this page turn continues a scroll, so start the new page at its top
+        // even with RememberViewOffsetOnPageTurn on - we're at the bottom of the
+        // old page only because we scrolled there (see GoToNextPage(bool))
+        dm->GoToNextPage(false);
     } else {
         win->ctrl->GoToNextPage();
     }

src/DisplayModel.cpp

@@ -1989,6 +1989,16 @@ static void GetRememberedViewOffset(DisplayModel* dm, int pageNo, int* scrollXOu
    Returns true if advanced to the next page or false if couldn't advance
    (e.g. because already was at the last page) */
 bool DisplayModel::GoToNextPage() {
+    return GoToNextPage(gGlobalPrefs->rememberViewOffsetOnPageTurn);
+}
+
+// keepViewOffset: land on the new page at the same offset we're at now
+// (RememberViewOffsetOnPageTurn) instead of at its top. It's false when the
+// page turn is the continuation of a scroll (wheeling past the bottom of a
+// page), because then "where we are now" is the bottom - keeping it would skip
+// the top of the new page and, since we'd still be at the bottom, every further
+// notch would flip another page
+bool DisplayModel::GoToNextPage(bool keepViewOffset) {
     int columns = ColumnsFromDisplayMode(GetDisplayMode());
     int currPageNo = CurrentPageNo();
     // Fully display the current page, if the previous page is still visible
@@ -2004,7 +2014,7 @@ bool DisplayModel::GoToNextPage() {
     }
     int scrollY = 0;
     int scrollX = -1;
-    if (gGlobalPrefs->rememberViewOffsetOnPageTurn) {
+    if (keepViewOffset) {
         GetRememberedViewOffset(this, currPageNo, &scrollX, &scrollY);
     }
     GoToPage(firstPageInNewRow, scrollY, false, scrollX);

src/DisplayModel.h

@@ -227,6 +227,7 @@ struct DisplayModel : DocController {
     RectF GetContentBox(int pageNo) const;
     void CalcZoomReal(float zoomVirtual);
     void GoToPage(int pageNo, int scrollY, bool addNavPt = false, int scrollX = -1);
+    bool GoToNextPage(bool keepViewOffset);
     bool GoToPrevPage(int scrollY);
     int GetPageNextToPoint(Point pt) const;