procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Document the subtleties of the 'cursor' text property

Browse source 
* doc/lispref/text.texi (Special Properties): Update the
documentation of the 'cursor' property per bug#8627.
This commit is contained in:
Eli Zaretskii 2021-12-05 16:38:49 +02:00
parent c086358574
commit 34f5656137
1 changed files with 25 additions and 16 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

41
doc/lispref/text.texi
View file

@ -3647,14 +3647,14 @@ Consecutive characters with the same @code{field} property constitute a
@kindex cursor @r{(text property)}
Normally, the cursor is displayed at the beginning or the end of any
overlay and text property strings present at the current buffer
position. You can place the cursor on any desired character of these
strings by giving that character a non-@code{nil} @code{cursor} text
property. In addition, if the value of the @code{cursor} property is
an integer, it specifies the number of buffer's character
positions, starting with the position where the overlay or the
@code{display} property begins, for which the cursor should be
displayed on that character. Specifically, if the value of the
@code{cursor} property of a character is the number @var{n}, the
position. You can instead tell Emacs to place the cursor on any
desired character of these strings by giving that character a
non-@code{nil} @code{cursor} text property. In addition, if the value
of the @code{cursor} property is an integer, it specifies the number
of buffer's character positions, starting with the position where the
overlay or the @code{display} property begins, for which the cursor
should be displayed on that character. Specifically, if the value of
the @code{cursor} property of a character is the number @var{n}, the
cursor will be displayed on this character for any buffer position in
the range @code{[@var{ovpos}..@var{ovpos}+@var{n})}, where @var{ovpos}
is the overlay's starting position given by @code{overlay-start}
@ -3663,14 +3663,23 @@ text property begins in the buffer.
In other words, the string character with the @code{cursor} property
of any non-@code{nil} value is the character where to display the
cursor. The value of the property says for which buffer positions to
display the cursor there. If the value is an integer @var{n},
the cursor is displayed there when point is anywhere between the
beginning of the overlay or @code{display} property and @var{n}
positions after that. If the value is anything else and
non-@code{nil}, the cursor is displayed there only when point is at
the beginning of the @code{display} property or at
@code{overlay-start}.
cursor when the overlay or display string make point not visible on
display. The value of the property says for which buffer positions to
display the cursor there. If the value is an integer @var{n}, the
cursor is displayed there when point is anywhere between the beginning
of the overlay or @code{display} property and @var{n} positions after
that. If the value is anything else and non-@code{nil}, the cursor is
displayed there only when point is at the buffer position that is the
beginning of the @code{display} property, or at @code{overlay-start}
if that position is not visible on display. Note that an integer
value of the @code{cursor} property could mean that the cursor is
displayed on that character even when point is visible on display.
One subtlety of this property is that it doesn't work to put this
property on a newline character that is part of a display or overlay
string. That's because the newline doesn't have a graphic
representation on the screen for Emacs to find when it looks for a
character on display with that @code{cursor} property.
@cindex cursor position for @code{display} properties and overlays
When the buffer has many overlay strings (e.g., @pxref{Overlay