utils/gatelock/docs/scrollable-viewport.md

The scrollable lock viewport

Design rationale for gatelock/_scrollable.py and its collaborators (_scrollfit.py, _scrollkeys.py, _userintent.py). Kept here rather than in the module docstring so the module itself stays readable in one piece; the behaviour it describes is load-bearing, not historical.

A keyboard-scrollable, focus-following viewport for lock-surface content.

Lock surfaces cannot solve "content taller than the screen" the obvious way. A scrollable dialog would be a second Toplevel, and on an override-redirect lock surface a second toplevel steals the Tk grab, which the recovery tick then kills a second later -- the 2026-07-26 failure where a frozen sport selector logged a walk as table tennis. So the viewport has to live inside the surface's own widget tree, which is what this provides.

Three defects this exists to prevent, all of them Tk defaults rather than oversights in any one app:

1. Centered content clips symmetrically. A place-centered frame takes its requested size, so when it is too tall the parent shears equal amounts off the top and the bottom -- losing the header and the submit button together, with no scrollbar and no hint anything is missing. This top-anchors content inside a scroll region instead.
2. A Canvas viewport is not keyboard-scrollable. tk.Canvas has no class-level key bindings at all, so ::tk::FocusOK rejects it as a focus stop and the only way to move the view is dragging the scrollbar thumb with a pointer. This makes the canvas focusable and binds PageUp/PageDown, Home/End and arrows.
3. Focus walks into invisible widgets. Canvas clipping does not unmap a child, so every scrolled-out-of-view field stays winfo viewable and stays in the tab chain, while Tk never scrolls to follow focus. Tabbing therefore lands on fields the user cannot see and cannot bring into view. :meth:ScrollableSurface.scroll_into_view fixes that, but only for focus the user moved.

Wheel scrolling is bound too, but as an addition -- never as the only path.

Scrolling is the fallback, not the design. A lock screen is supposed to fit its screen; content that overflows is a layout defect, and :meth:finalize logs it at warning so it gets fixed rather than lived with. While the content fits -- the normal case -- the scroll region is pinned to the viewport and the scrollbar is hidden, so the view cannot move at all. When it does overflow, the view still only moves in response to a keypress, a click or the wheel: an earlier version followed programmatic focus too, and since the apps re-focus a widget on every repaint, the screen scrolled itself to mid-content and back while the user was doing nothing (reported 2026-08-03, 1366x768).