Function: pdf-util-required-vscroll

pdf-util-required-vscroll is a natively compiled function defined in pdf-util.el.

Signature

(pdf-util-required-vscroll EDGES &optional EAGER-P CONTEXT-PIXEL)

Documentation

Return the amount of scrolling necessary, to make image EDGES visible.

Scroll as little as necessary. Unless EAGER-P is non-nil, in which case scroll as much as possible.

Keep CONTEXT-PIXEL pixel of the image visible at the bottom and top of the window. CONTEXT-PIXEL defaults to an equivalent pixel value of next-screen-context-lines.

Return the required vscroll in pixels or nil, if scrolling is not needed.

Note: For versions of emacs before 27 this will return lines instead of pixels. This is because of a change that occurred to image-mode in 27.

Source Code

;; Defined in /nix/store/63h5z2vmzn0mfavcxi2idi23g5xcgkbl-emacs-packages-deps/share/emacs/site-lisp/elpa/pdf-tools-20260102.1101/pdf-util.el
(defun pdf-util-required-vscroll (edges &optional eager-p context-pixel)
  "Return the amount of scrolling necessary, to make image EDGES visible.

Scroll as little as necessary.  Unless EAGER-P is non-nil, in
which case scroll as much as possible.

Keep CONTEXT-PIXEL pixel of the image visible at the bottom and
top of the window.  CONTEXT-PIXEL defaults to an equivalent pixel
value of `next-screen-context-lines'.

Return the required vscroll in pixels or nil, if scrolling is not
needed.

Note: For versions of emacs before 27 this will return lines instead of
pixels. This is because of a change that occurred to `image-mode' in 27."
  (pdf-util-assert-pdf-window)
  (if pdf-view-roll-minor-mode
      (max 0 (- (nth 1 edges)
                (or context-pixel
                    (* next-screen-context-lines (frame-char-height)))))
    (let* ((win (window-inside-pixel-edges))
           (image-height (cdr (pdf-view-image-size
                               (unless pdf-view-roll-minor-mode
                                 t))))
           (image-top (window-vscroll nil t))
           (edges (pdf-util-translate
                   edges
                   (pdf-view-image-offset) t)))
      (pdf-util-with-edges (win edges)
        (let* ((context-pixel (or context-pixel
                                  (* next-screen-context-lines
                                     (frame-char-height))))
               ;;Be careful not to modify edges.
               (edges-top (- edges-top context-pixel))
               (edges-bot (+ edges-bot context-pixel))
               (vscroll
                (cond ((< edges-top image-top)
                       (max 0 (if eager-p
                                  (- edges-bot win-height)
                                edges-top)))
                      ((> (min image-height
                               edges-bot)
                          (+ image-top win-height))
                       (min (- image-height win-height)
                            (if eager-p
                                edges-top
                              (- edges-bot win-height)))))))


          (when vscroll
            (round
             ;; `image-set-window-vscroll' changed in version 27 to using
             ;; pixels, not lines.
             (if (version< emacs-version "27")
                 (/ vscroll (float (frame-char-height)))
               vscroll))))))))