The @code{left}, @code{center}, and @code{right} positions can be
used with @code{:align-to} to specify a position relative to the left
edge, center, or right edge of the text area. When the window
-displays line numbers, the @code{left} and the @code{center} positions
-are offset to account for the screen space taken by the line-number
-display.
+displays line numbers, and @code{:align-to} is used in display
+properties of buffer text (as opposed to header line, see below), the
+@code{left} and the @code{center} positions are offset to account for
+the screen space taken by the line-number display.
Any of the above window elements (except @code{text}) can also be
used with @code{:align-to} to specify that the position is relative to
:align-to (+ left-margin (0.5 . left-margin))
@end example
- If no specific base offset is set for alignment, it is always relative
-to the left edge of the text area. For example, @samp{:align-to 0} in a
-header-line aligns with the first text column in the text area. When
-the window displays line numbers, the text is considered to start where
-the space used for line-number display ends.
+ If no specific base offset is set for alignment, it is always
+relative to the left edge of the text area. For example,
+@samp{:align-to 0} aligns with the first text column in the text area.
+When the window displays line numbers, the text is considered to start
+where the space used for line-number display ends.
A value of the form @code{(@var{num} . @var{expr})} stands for the
product of the values of @var{num} and @var{expr}. For example,
expressions. The form @code{(- @var{expr} ...)} negates or subtracts
the value of the expressions.
+@vindex header-line-format@r{, and } :align-to
+@cindex aligning header line, when line numbers are displayed
+@cindex header line alignment when line numbers are displayed
+ Text shown in the header line that uses @code{:align-to} display
+specifications is not automatically realigned when
+@code{display-line-numbers-mode} is turned on and off, or when the
+width of line numbers on display changes. To arrange for the
+header-line text alignment to be updated, thus keeping the header-line
+text aligned with the buffer text, turn on the
+@code{header-line-indent-mode} in the buffer and use its two
+variables, @code{header-line-indent} and
+@code{header-line-indent-width}, in the display specification.
+@xref{Header Lines}. Here's a simple example:
+
+@lisp
+(setq header-line-format
+ (concat (propertize " "
+ 'display
+ '(space :align-to
+ (+ header-line-indent-width 10)))
+ "Column"))
+@end lisp
+
+@noindent
+This will keep the text @samp{Column} on the header line aligned with
+column 10 of buffer text, regardless of whether
+@code{display-line-numbers-mode} is on or off, and also when
+line-number display changes its width.
+
@node Other Display Specs
@subsection Other Display Specifications
is the same as for @code{mode-line-format} (@pxref{Mode Line Data}).
It is normally @code{nil}, so that ordinary buffers have no header
line.
+@end defvar
+
+If @code{display-line-numbers-mode} is turned on in a buffer
+(@pxref{Display Custom, display-line-numbers-mode,, emacs, 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
+@code{tabulated-list-mode} does, @pxref{Tabulated List Mode}), it
+should turn on the minor mode @code{header-line-indent-mode}.
+
+@deffn 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 @code{header-line-indent}
+and @code{header-line-indent-width} in the @code{header-line-format}
+to ensure it is adjusted to the text indentation at all times.
+@end deffn
-@findex header-line-indent-mode
-If @code{display-line-numbers-mode} is used, and you want the header
-line to be indented by the same amount as the buffer contents, you can
-use the @code{header-line-indent-mode} minor mode. This minor mode
-keeps the @code{header-line-indent} variable updated, so that you can
-say something like:
+@defvar 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
+@code{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
+@code{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
+@code{header-line-format}:
@lisp
(setq header-line-format
- `("" header-line-format ,my-header-line))
+ `("" header-line-indent ,my-header-line))
@end lisp
-This can be useful if you're displaying columnar data, and the header
-line should align with that data in the buffer.
+@noindent
+where @code{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.
+@end defvar
+
+@defvar 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 @code{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
+@code{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 @code{frame-char-width} (@pxref{Frame Font}), and
+then use the result to align header-line text using the
+@code{:align-to} display property spec (@pxref{Specified Space}) in
+pixels on the relevant parts of @code{header-line-frormat}.
@end defvar
@defun window-header-line-height &optional window
+++
** New minor mode 'header-line-indent-mode'.
-This is meant to be used in modes that have a header line that should
-be kept aligned with the buffer contents when the user switches
-'display-line-numbers-mode' on or off.
+This is meant to be used by Lisp programs that show a header line
+which should be kept aligned with the buffer contents when the user
+switches 'display-line-numbers-mode' on or off, and when the width of
+line-number display changes. See the "(elisp) Header Lines" node in
+the Emacs Lisp Reference manual for more information.
+++
** New global minor mode 'lost-selection-mode'.
;;;###autoload
(defvar header-line-indent ""
- "String to indent at the start if the header line.
-This is used in `header-line-indent-mode', and buffers that have
-this switched on should have a `header-line-format' that look like:
+ "String of spaces to indent the beginning of header-line due to line numbers.
+This is intended to be used in `header-line-format', and requires
+the `header-line-indent-mode' to be turned on, in order for the width
+of this string to be kept updated when the line-number width changes
+on display. An example of a `header-line-format' that uses this
+variable might look like this:
(\"\" header-line-indent THE-REST...)
+where THE-REST is the format string which produces the actual text
+of the header-line.
Also see `header-line-indent-width'.")
;;;###autoload
(defvar header-line-indent-width 0
- "The width of the current line numbers displayed.
-This is updated when `header-line-indent-mode' is switched on.
-
+ "The width of the current line number display in the window.
+This is measured in units of the frame's canonical columns.
+This is updated when `header-line-indent-mode' is switched on,
+and is intended for use in `:align-to' display specifications
+that are part of `header-line-format', when portions of header-line
+text should be aligned to respective parts of buffer text.
Also see `header-line-indent'.")
(defun header-line-indent--line-number-width ()
;;;###autoload
(define-minor-mode header-line-indent-mode
- "Mode to indent the header line in `display-line-numbers-mode' buffers.
-This means that the header line will be kept indented so that it
-has blank space that's as wide as the displayed line numbers in
-the buffer.
+ "Minor mode to help with alignment of header line when line numbers are shown.
+This minor mode should be turned on in buffers which dispay header-line
+that needs to be aligned with buffer text when `display-line-numbers-mode'
+is turned on in the buffer.
-Buffers that have this switched on should have a
-`header-line-format' that look like:
+Buffers that have this switched on should have a `header-line-format'
+that uses the `header-line-indent' or the `header-line-indent-width'
+variables, which this mode will keep up-to-date with the current
+display of line numbers. For example, a `header-line-format' that
+looks like this:
(\"\" header-line-indent THE-REST...)
-The `header-line-indent-width' variable is also kept updated, and
-has the width of `header-line-format'. This can be used, for
-instance, in `:align-to' specs, like:
+will make sure the text produced by THE-REST (which should be
+a header-line format string) is always indented to be aligned on
+display with the first column of buffer text.
+
+The `header-line-indent-width' variable is also kept updated,
+and can be used, for instance, in `:align-to' specs as part
+of `header-line-format', like this:
+
+ (space :align-to (+ header-line-indent-width 10))
- (space :align-to (+ header-line-indent-width 10))"
+See also `line-number-display-width'."
:lighter nil
(if header-line-indent-mode
(progn
The header line appears, optionally, at the top of a window; the mode
line appears at the bottom.
-Also see `header-line-indent-mode' if `display-line-number-mode' is
-used. */);
+Also see `header-line-indent-mode' if `display-line-numbers-mode' is
+turned on and header-line text should be aligned with buffer text. */);
DEFVAR_PER_BUFFER ("mode-line-format", &BVAR (current_buffer, mode_line_format),
Qnil,
projects / emacs.git / commitdiff