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

; Improve documentation of overlay priorities

Browse source 
* doc/lispref/display.texi (Overlay Properties): Don't advise
against using overlay property values that are cons cells.
(Bug#64101)
This commit is contained in:
Eli Zaretskii 2023-06-18 09:13:02 +03:00
parent b3f11e94fa
commit eacd75df4e
1 changed files with 32 additions and 23 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

55
doc/lispref/display.texi
View file

@ -1792,34 +1792,43 @@ of them:
@table @code
@item priority
@kindex priority @r{(overlay property)}
This property's value determines the priority of the overlay.
If you want to specify a priority value, use either @code{nil}
(or zero), or a positive integer. Any other value has undefined behavior.
This property's value determines the priority of the overlay. If you
want to specify a priority value, use either @code{nil} (or zero), or
a positive integer, or a cons of two values. Any other value triggers
undefined behavior.
The priority matters when two or more overlays cover the same
character and both specify the same property with different values;
the one whose @code{priority} value is larger overrides the other.
the one whose @code{priority} value is higher overrides the other.
(For the @code{face} property, the higher priority overlay's value
does not completely override the other value; instead, its face
attributes override the face attributes of the @code{face} property
whose priority is lower.) If two overlays have the same priority
value, and one is nested in the other, then the inner one will prevail
over the outer one. If neither is nested in the other then you should
not make assumptions about which overlay will prevail.
does not completely override the other value; instead, its individual
face attributes override the corresponding face attributes of the
@code{face} property whose priority is lower.) If two overlays have
the same priority value, and one is ``nested'' in the other (i.e.,
covers fewer buffer or string positions), then the inner one will
prevail over the outer one. If neither is nested in the other then
you should not make assumptions about which overlay will prevail.
When a Lisp program puts overlays with defined priorities on text that
might have overlays without priorities, this could cause undesirable
results, because any overlay with a positive priority value will
override all the overlays without a priority. Since most Emacs
features that use overlays don't specify priorities for their
overlays, integer priorities should be used with care. Instead of
using integer priorities and risk overriding other overlays, you can
use priority values of the form @w{@code{(@var{primary} . @var{secondary})}},
where the @var{primary} value is used as described above, and
@var{secondary} is the fallback value used when @var{primary} and the
nesting considerations fail to resolve the precedence between
overlays. In particular, priority value @w{@code{(nil . @var{n})}},
with @var{n} a positive integer, allows to have the overlays ordered
by priority when necessary without completely overriding other
overlays.
Currently, all overlays take priority over text properties.
Note that Emacs sometimes uses non-numeric priority values for some of
its internal overlays, so do not try to do arithmetic on the priority
of an overlay (unless it is one that you created). In particular, the
overlay used for showing the region uses a priority value of the form
@w{@code{(@var{primary} . @var{secondary})}}, where the @var{primary}
value is used as described above, and @var{secondary} is the fallback
value used when @var{primary} and the nesting considerations fail to
resolve the precedence between overlays. However, you are advised not
to design Lisp programs based on this implementation detail; if you
need to put overlays in priority order, use the @var{sorted} argument
of @code{overlays-at}. @xref{Finding Overlays}.
If you need to put overlays in priority order, use the @var{sorted}
argument of @code{overlays-at}. @xref{Finding Overlays}.
@item window
@kindex window @r{(overlay property)}
@ -3329,8 +3338,8 @@ enough to the overlay, Emacs applies the face or face attributes
specified by the @code{mouse-face} property instead. @xref{Overlay
Properties}.
When multiple overlays cover one character, an overlay with higher
priority overrides those with lower priority. @xref{Overlays}.
When multiple overlays cover the same character, an overlay with
higher priority overrides those with lower priority. @xref{Overlays}.
@item
If the text contains a @code{face} or @code{mouse-face} property,