Improve documentation of 'header-line-indent-mode'
* doc/lispref/modes.texi (Header Lines): Rewrite the documentation of 'header-line-indent-mode' and its two variables. Fix the example. * doc/lispref/display.texi (Pixel Specification): More accurate description of what happens with :align-to in header-lines. Improve indexing. (Bug#61239) * src/buffer.c (syms_of_buffer) <header-line-format>: * lisp/display-line-numbers.el (header-line-indent) (header-line-indent-width, header-line-indent-mode): Doc fixes. * etc/NEWS: Enhance the announcement of 'header-line-indent-mode'.
This commit is contained in:
Eli Zaretskii
parent
c3f58a6651
commit
35e238cae8
5 changed files with 136 additions and 38 deletions
|
|
@ -5285,9 +5285,10 @@ space taken by the line-number display.
|
|||
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
|
||||
|
|
@ -5301,11 +5302,11 @@ the left-margin, use
|
|||
: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,
|
||||
|
|
@ -5317,6 +5318,35 @@ 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
|
||||
|
||||
|
|
|
|||
|
|
@ -2578,21 +2578,70 @@ header line, for windows displaying the buffer. The format of the value
|
|||
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
|
||||
|
||||
@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:
|
||||
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
|
||||
|
||||
@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
|
||||
|
|
|
|||
8
etc/NEWS
8
etc/NEWS
|
|
@ -3946,9 +3946,11 @@ This argument can be used to override values of print-related settings.
|
|||
|
||||
+++
|
||||
** 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'.
|
||||
|
|
|
|||
|
|
@ -112,19 +112,27 @@ the mode is on, set `display-line-numbers' directly."
|
|||
|
||||
;;;###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 ()
|
||||
|
|
@ -155,21 +163,30 @@ Also see `header-line-indent'.")
|
|||
|
||||
;;;###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.
|
||||
|
||||
(space :align-to (+ header-line-indent-width 10))"
|
||||
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))
|
||||
|
||||
See also `line-number-display-width'."
|
||||
:lighter nil
|
||||
(if header-line-indent-mode
|
||||
(progn
|
||||
|
|
|
|||
|
|
@ -5081,8 +5081,8 @@ the mode line appears at the bottom. */);
|
|||
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,
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue