bug#22404: 25.1.50; Forcing `window-scroll-functions` to run.

[Keith David Bershatsky <esq@lawlist.com>]

I have a minor mode that draws overlays from `window-start` to `window-end`, and those two values are mission critical to making sure that the overlays are placed correctly.  I have `word-wrap` set to `t`.  I have a function that makes relevant calculations in the visible window, which begins at `window-start` and uses `vertical-motion` for every visual line until `window-end`.  Along the way, I gather 22 different elements of a list for EACH visible line:  points at the beginning/ending of visual line (pbovl/peovl); points at beginning/ending of full line (bol/eol); column at the end of visual line (col-at-eovl); line number `(format-mode-line "%l")`; and all of the following in a vertical line (from top to bottom of the window) where the cursor is:  column, point, character, foreground/b
 ackground colors of character.

When the list is assembled, I then take that list and place overlays to create a horizontal and vertical line compatible with `word-wrap` -- the result is a visual cross-hairs spanning the entire length and width of the visible window.  I am using XPM images for the vertical line, which permits me to achieve a thin vertical line to the left of each character -- it looks just like a thin vbar cursor.  I control the color of the vertical line -- the letters remain the same color they were, but the line color varies -- yellow for even column number; red for odd column number; green for when I am beyond the fill-column on the first visual line; a medium blue for a line that is visually wrapped when point is on a visual line subsequent to the first wrapped line; and a cyan color when point is a
 t the right window boundary.  The horizontal line stretches the entire length of the window, even for the word-wrapped lines.  I have some fancy XPM images that change depending upon where point is.  It works with active regions too.  I have line numbering (in the left-hand margin) for each line.  I placer certain bitmap images in the right fringe depending when point is at the last character at the window edge, or when there is a hard return at the right window edge.  Each line-end (eol) has a pilcrow symbol that is XPM, except when cursor is at eol, in which case it is a different XPM image.  The end of the buffer has a different XPM image and the vertical line extends to the last visual line, even if the point at the end of the buffer is a few inches to the left of the vertical line.

The calculations (primarily because of `vertical-motion`) are too costly time-wise to perform more than once during each command loop because it slows down performance.

If I run the calculations from the `post-command-hook`, I will have wasted precious time IF the `window-scroll-functions` hook will be running.  IF the `window-scroll-functions` hook will be running, then the `window-start` and `window-end` obtained from the `post-command-hook` will be wrong -- so there is no point using those PCH wrong numbers.

If I run the calculations from the INITIAL run of the `window-scroll-functions` hook, I will have wasted precious time IF the WSF hook will be running a SECOND time.  [WSF runs a SECOND time if point was PARTIALLY visible.]  IF the WSF will be running more than one time, then the INITIAL values for `window-start` and `window-end` will be wrong -- so there is no point using those WSF wrong numbers.  Instead, I have to wait until the LAST call on the WSF when the final correct values for `window-start` and `window-end` can be truly ascertained.

Without the benefit of feature request 22404, there are a couple of options that are not ideal.

OPTION # 1(a):  Devise an efficient/accurate test that can be called from the `post-command-hook` to ascertain whether the `window-scroll-functions` hook will be running one or more times.  [Without a forced trigger, WSF only runs SOME of the time.]  If the WSF will be running one or more times, then do NOT perform the overlay calculations because the PCH values for `window-start` and `window-end` are wrong.  If the WSF will NOT be running, then go ahead and perform the time-costly calculations and place the overlays immediately.

OPTION # 1(b):  When the `window-scroll-functions` hook runs, I need to figure out whether it will be running one more time (subsequently) because point was only partially visible.  The only test I am aware of is `(pos-visible-in-window-p nil nil nil)`.  The LAST call on the WSF is the mission critical because that produces the correct values for `window-start` and `window-end`.  If WSF will only be running once, then go ahead and perform the time-costly calculations and place the overlays immediately.  If the WSF will be running more than once, then the *initial* WSF values for `window-start and `window-end` are wrong -- in that case, wait until the last call of WSF to perform the calculations and place overlays.

OPTION # 2:  Call `set-window-buffer` from the `post-command-hook` as a means of forcing WSF to run during the latter part of redisplay.  In this case, we never use the PCH values of `window-start` and `window-end` -- instead, we wait for WSF to give us the correct values.  This solution is not preferred because `set-window-buffer` was not designed to be used solely as a WSF trigger.  In the context of my example, I don't need to set the window buffer and I don't need to run the `window-configuration-change-hook` -- I just want to force WSF to run during the latter part of redisplay.

OPTION # 3:  Trigger the WSF without all the hoopla -- e.g., w->optional_new_start = true;.  E.g., my sample C-function `force_wsf`.

OPTION # 4 (ideal):  Create an entirely new animal that knows whether WSF will run more than once, and only produces the correct values for `window-start` and `window-end` in ALL circumstances, and then permits the user to run a custom function that takes advantage of those values.

Thanks,

Keith