Previous: Window Parameters, Up: Windows

28.30 Hooks for Window Scrolling and Changes

This section describes how a Lisp program can take action whenever a window displays a different part of its buffer or a different buffer. There are three actions that can change this: scrolling the window, switching buffers in the window, and changing the size of the window. The first two actions run window-scroll-functions; the last runs window-size-change-functions.

— Variable: window-scroll-functions

This variable holds a list of functions that Emacs should call before redisplaying a window with scrolling. Displaying a different buffer in the window also runs these functions.

This variable is not a normal hook, because each function is called with two arguments: the window, and its new display-start position. At the time of the call, the display-start position of the window argument is already set to its new value, and the buffer to be displayed in the window is already set as the current buffer.

These functions must take care when using window-end (see Window Start and End); if you need an up-to-date value, you must use the update argument to ensure you get it.

Warning: don't use this feature to alter the way the window is scrolled. It's not designed for that, and such use probably won't work.

— Function: run-window-scroll-functions &optional window

This function calls window-scroll-functions for the specified window, which defaults to the selected window.

— Variable: window-size-change-functions

This variable holds a list of functions to be called if the size of any window changes for any reason. The functions are called once per redisplay, and once for each frame on which size changes have occurred.

Each function receives the frame as its sole argument. To find out whether a specific window has changed size, compare the return values of window-pixel-width-before-size-change and window-pixel-width respectively window-pixel-height-before-size-change and window-pixel-height for that window (see Window Sizes).

These function are usually only called when at least one window was added or has changed size since the last time this hook was run for the associated frame. In some rare cases this hook also runs when a window that was added intermittently has been deleted afterwards. In these cases none of the windows on the frame will appear to have changed its size.

You may use save-selected-window in these functions (see Selecting Windows). However, do not use save-window-excursion (see Window Configurations); exiting that macro counts as a size change, which would cause these functions to be called again.

— Variable: window-configuration-change-hook

A normal hook that is run every time the window configuration of a frame changes. Window configuration changes include splitting and deleting windows, and the display of a different buffer in a window. Resizing the frame or individual windows do not count as configuration changes. Use window-size-change-functions, see above, when you want to track size changes that are not caused by the deletion or creation of windows.

The buffer-local value of this hook is run once for each window on the affected frame, with the relevant window selected and its buffer current. The global value of this hook is run once for the modified frame, with that frame selected.

— Function: run-window-configuration-change-hook &optional frame

This function runs window-configuration-change-hook for the specified frame, which defaults to the selected frame.

In addition, you can use jit-lock-register to register a Font Lock fontification function, which will be called whenever parts of a buffer are (re)fontified because a window was scrolled or its size changed. See Other Font Lock Variables.