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:
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.
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.
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.
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.
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.