-
-
Notifications
You must be signed in to change notification settings - Fork 2
Home
This page contains notes about the design and workings of doc-scroll.
Emacs can show images via text properties or overlays. Using text properties should be faster, although after the latests works on overlays the difference probably is small. An important difference is that for text-properties there is no mechanism to display different text-properties in different windows of the same buffer, while for overlays, different windows can display different overlays by setting the overlay window display property.
Another additional, but not essential, reason to use overlays is that
Emacs provides a function overlays-in that greatly simplifies the
logic for dynamically displaying images (image-roll, a precursor to
doc-scroll, does not use this function and instead reimplements the
logic in lisp, because the author (me) was not aware of the
overlays-in function at the time of its development). Another
library that is required for independently displaying a single buffer
in two windows is the image-mode library, as explained in the next
section.
Except for window-parameters, emacs provides no window local variables
in a way similar to buffer local variables. However, a way to manage,
for a single buffer, displaying images differently in different
windows, is provided by the not very well documented
image-mode-winprops. As described in its docstring, a winprops object
has the shape (WINDOW . ALIST). Three important points that are not
mentioned in the image-mode-winprops docstring are:
- for image-mode-winprops to work, the buffer local variable should be a list
- the function image-mode-reapply-winprops or a similar function should have been added to the window-configuration-change-hook
- image-mode-winprops runs the image-mode-new-window-functions
function, passing it the
winpropsas its argument
Doc-scroll does not use the image-mode-setup-winprops function to set
up the winprops, as it would add image-mode-reapply-winprops to the
window-configuration-change-hook. Instead doc-scroll add
doc-scroll-redisplay to that hook.
Doc scroll only has doc-scroll-new-window-function in the
image-mode-new-window-functions hook.
When opening a document, doc-scroll mode is activated (either via auto-mode-alist or via magic-mode-alist) in the buffer before the buffer is displayed in any window. doc-scroll-mode sets up (adds) the hook functions and then runs doc-scroll-new-window-function via image-mode-new-window-functions by running image-mode-winprops.
The image-mode-new-window-functions creates a (single column) grid of
overlays, and because the buffer is not yet displayed in a window,
these overlays are added in the alist associated to t in the
image-mode-winprops-alist (see also image-mode-winprops
docstring). Subsequently, when the buffer gets displayed, the
image-mode-new-window-functions is called again from the
window-configuration-change-hook and another set of overlays is
created that are given the window display property so that they only
apply to the ‘current window’. For each extra window in which the
buffer gets displayed, the window-configuration-change-hook and
image-mode-new-window-functions take care that new ‘window local
overlays’ get created.
The image grid is created by adding groups of characters as placeholders in a similar configuration as the final image grid. As it is not possible to have different contents (text) in a single buffer, doc-scroll uses a configuration that can support multiple ‘grid configurations’. To make possible to display the buffer with a different number of columns in different windows, each line, by default, contains 120 (1 x 2 x 3 x 4 x 5) characters so that a grid with a nultiple of any combination of these numbers of columns can be displayed by moving the overlays (move-overlay).
In order to display a certain page we must move point to the correct line for efficiency (instead of merely adapting the vscroll, see this message by Po Lu). To scroll the page to a certain location, the window vscroll should be set additionally. The window-vscroll is given either in units of character height or in pixels (doc-scroll always uses pixeils). However, to make sure that the document is always redisplayed for different sizes/fit/zoom/magnification at the correct location, the amount of scroll should be given as a fraction of the current displayed page size. For that doc-scroll uses the function doc-scroll-set-window-fscroll (will be renamed to pscroll, where p for page units. f in fscroll stands for fraction).