24.4.7 Window Header Lines

A window can have a header line at the top, just as it can have a mode line at the bottom. The header line feature works just like the mode line feature, except that it’s controlled by header-line-format:

Variable: header-line-format

This variable, local in every buffer, specifies how to display the header line, for windows displaying the buffer. The format of the value is the same as for mode-line-format (see The Data Structure of the Mode Line). It is normally nil, so that ordinary buffers have no header line.

If display-line-numbers-mode is turned on in a buffer (see display-line-numbers-mode in The GNU Emacs Manual), the buffer text is indented on display by the amount of screen space needed to show the line numbers. By contrast, text of the header line is not automatically indented, because a header line never displays a line number, and because the text of the header line is not necessarily directly related to buffer text below it. If a Lisp program needs the header-line text to be aligned with buffer text (for example, if the buffer displays columnar data, like tabulated-list-mode does, see Tabulated List mode), it should turn on the minor mode header-line-indent-mode.

Command: header-line-indent-mode

This buffer-local minor mode tracks the changes of the width of the line-number display on screen (which may vary depending on the range of line numbers shown in the window), and allows Lisp programs to arrange that header-line text is always aligned with buffer text when the line-number width changes. Such Lisp programs should turn on this mode in the buffer, and use the variables header-line-indent and header-line-indent-width in the header-line-format to ensure it is adjusted to the text indentation at all times.

Variable: header-line-indent

This variable’s value is a whitespace string whose width is kept equal to the current width of line-numbers on display, provided that header-line-indent-mode is turned on in the buffer shown in the window. The number of spaces is calculated under the assumption that the face of the header-line text uses the same font, including size, as the frame’s default font; if that assumption is false, use header-line-indent-width, described below, instead. This variable is intended to be used in simple situations where the header-line text needs to be indented as a whole to be realigned with buffer text, by prepending this variable’s value to the actual header-line text. For example, the following definition of header-line-format:

(setq header-line-format
      `("" header-line-indent ,my-header-line))

where my-header-line is the format string that produces the actual text of the header line, will make sure the header-line text is always indented like the buffer text below it.

Variable: header-line-indent-width

This variable’s value is kept updated to provide the current width, in units of the frame’s canonical character width, used for displaying the line numbers, provided that header-line-indent-mode is turned on in the buffer shown in the window. It can be used for aligning the header-line text with the buffer text when header-line-indent is not flexible enough. For example, if the header line uses a font whose metrics is different from the default face’s font, your Lisp program can calculate the width of line-number display in pixels, by multiplying the value of this variable by the value returned by frame-char-width (see Frame Font), and then use the result to align header-line text using the :align-to display property spec (see Specified Spaces) in pixels on the relevant parts of header-line-format.

Function: window-header-line-height &optional window

This function returns the height in pixels of window’s header line. window must be a live window, and defaults to the selected window.

A window that is just one line tall never displays a header line. A window that is two lines tall cannot display both a mode line and a header line at once; if it has a mode line, then it does not display a header line.