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)} @kindex cursor @r{(text property)}
Normally, the cursor is displayed at the beginning or the end of any Normally, the cursor is displayed at the beginning or the end of any
overlay and text property strings present at the current buffer overlay and text property strings present at the current buffer
position. You can place the cursor on any desired character of these position. You can instead tell Emacs to place the cursor on any
strings by giving that character a non-@code{nil} @code{cursor} text desired character of these strings by giving that character a
property. In addition, if the value of the @code{cursor} property is non-@code{nil} @code{cursor} text property. In addition, if the value
an integer, it specifies the number of buffer's character of the @code{cursor} property is an integer, it specifies the number
positions, starting with the position where the overlay or the of buffer's character positions, starting with the position where the
@code{display} property begins, for which the cursor should be overlay or the @code{display} property begins, for which the cursor
displayed on that character. Specifically, if the value of the should be displayed on that character. Specifically, if the value of
@code{cursor} property of a character is the number @var{n}, the 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 cursor will be displayed on this character for any buffer position in
the range @code{[@var{ovpos}..@var{ovpos}+@var{n})}, where @var{ovpos} the range @code{[@var{ovpos}..@var{ovpos}+@var{n})}, where @var{ovpos}
is the overlay's starting position given by @code{overlay-start} 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 In other words, the string character with the @code{cursor} property
of any non-@code{nil} value is the character where to display the 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 cursor when the overlay or display string make point not visible on
display the cursor there. If the value is an integer @var{n}, display. The value of the property says for which buffer positions to
the cursor is displayed there when point is anywhere between the display the cursor there. If the value is an integer @var{n}, the
beginning of the overlay or @code{display} property and @var{n} cursor is displayed there when point is anywhere between the beginning
positions after that. If the value is anything else and of the overlay or @code{display} property and @var{n} positions after
non-@code{nil}, the cursor is displayed there only when point is at that. If the value is anything else and non-@code{nil}, the cursor is
the beginning of the @code{display} property or at displayed there only when point is at the buffer position that is the
@code{overlay-start}. 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 @cindex cursor position for @code{display} properties and overlays
When the buffer has many overlay strings (e.g., @pxref{Overlay When the buffer has many overlay strings (e.g., @pxref{Overlay