Function: ghostel--anchor-window

ghostel--anchor-window is a natively compiled function defined in ghostel.el.

Signature

(ghostel--anchor-window &optional WINDOW FORCE FOLLOWING)

Documentation

Scroll WINDOW so that the last row is aligned to the bottom of the window.

In graphical frames, use Emacs's pixel layout for exact bottom alignment. In text frames, use line-count geometry with no vscroll. Do nothing unless WINDOW displays a live Ghostel terminal. A ghostel-inhibit-anchor-functions hook can veto anchoring a window.

The live cursor is never scrolled out of view: when bottom-aligning point-max would push the cursor's line above window-start (a shrunken window over a mostly-empty grid), the anchor starts at the cursor's line instead. ghostel--window-anchored-p recognizes such a clamped window as still following the output.

Copy mode is never anchored (the viewport is frozen). Otherwise WINDOW anchors while ghostel--window-follows-p holds, or when FOLLOWING (the caller established the follow before the render moved the cursor) or FORCE (deliberate anchors such as paste/yank) is non-nil. Semi-char/char/Emacs snap point to the live cursor; line mode keeps the user's point.

Source Code

;; Defined in /nix/store/1252krff0gb2kisjcpp45m50cpdskfrl-emacs-packages-deps/share/emacs/site-lisp/ghostel.el
(defun ghostel--anchor-window (&optional window force following)
  "Scroll WINDOW so that the last row is aligned to the bottom of the window.
In graphical frames, use Emacs's pixel layout for exact bottom alignment.
In text frames, use line-count geometry with no vscroll.
Do nothing unless WINDOW displays a live Ghostel terminal.
A `ghostel-inhibit-anchor-functions' hook can veto anchoring a window.

The live cursor is never scrolled out of view: when bottom-aligning
`point-max' would push the cursor's line above `window-start' (a shrunken
window over a mostly-empty grid), the anchor starts at the cursor's line
instead.  `ghostel--window-anchored-p' recognizes such a clamped window
as still following the output.

Copy mode is never anchored (the viewport is frozen).
Otherwise WINDOW anchors while `ghostel--window-follows-p' holds,
or when FOLLOWING (the caller established the follow before the render moved
the cursor) or FORCE (deliberate anchors such as paste/yank) is non-nil.
Semi-char/char/Emacs snap point to the live cursor;
line mode keeps the user's point."
  (when-let* ((window (or window (selected-window)))
              (buffer (window-buffer window))
              ((with-current-buffer buffer
                 (and (derived-mode-p 'ghostel-mode)
                      (ghostel--terminal-live-p)
                      (or force following
                          (ghostel--window-follows-p window))
                      ;; Per-window veto: a consumer (e.g. evil-ghostel) can
                      ;; keep point roaming off the live cursor while the
                      ;; buffer stays in a follow-capable input mode.
                      (not (run-hook-with-args-until-success
                            'ghostel-inhibit-anchor-functions window force))))))
    (with-selected-window window
      (with-current-buffer buffer
        (let* ((target (point-max))
               ;; Line mode's input region is user-owned; keep point instead
               ;; of snapping it to the terminal cursor.
               (orig (point))
               (cursor (and (not (eq ghostel--input-mode 'line))
                            ghostel--cursor-char-pos))
               (cursor-bol (and cursor
                                (save-excursion
                                  (goto-char cursor)
                                  (line-beginning-position))))
               (anchor (or (and (display-graphic-p (window-frame window))
                                ghostel--pixel-anchor-supported-p
                                (ghostel--balance-top-pad window target))
                           (save-excursion
                             (goto-char target)
                             (forward-line
                              (- (if (bolp) 0 1) (floor (window-screen-lines))))
                             (list (point) 0))))
               (start (if (and cursor-bol (< cursor-bol (car anchor)))
                          cursor-bol
                        (car anchor)))
               ;; A vscroll would partially clip the cursor's row whenever
               ;; it is the top line; a clamped start sits on a line
               ;; boundary anyway.
               (vscroll (if (and cursor-bol (= cursor-bol start))
                            0
                          (nth 1 anchor))))
          (set-window-start window start)
          (ghostel--set-window-vscroll window vscroll t t)
          (set-window-point window (if (eq ghostel--input-mode 'line)
                                       orig
                                     (or cursor target))))))))