Improve documentation for display property functions
Specifically, use the term "display specification" more consistently to distinguish from "display property", which is the full value of the 'display' text property. * src/xdisp.c (find_display_property): Rename PROP to SPEC. (Fget_display_property): Rename PROP to SPEC and improve docstring. * lisp/emacs-lisp/subr-x.el (add-display-text-property): Rename PROP to SPEC and improve docstring. * doc/lispref/display.texi (Display Property): Reword documentation to more-consistently refer to display specifications.
This commit is contained in:
Jim Porter
parent
4a3c8e6e1d
commit
24e6cd4233
3 changed files with 47 additions and 46 deletions
|
|
@ -5260,29 +5260,29 @@ Properties}.
|
|||
specification, or a list or vector containing several display
|
||||
specifications.
|
||||
|
||||
@defun get-display-property position prop &optional object properties
|
||||
This convenience function can be used to get a specific display
|
||||
property, no matter whether the @code{display} property is a vector, a
|
||||
list or a simple property. This is like @code{get-text-property}
|
||||
(@pxref{Examining Properties}), but works on the @code{display} property
|
||||
only. For properties with a single value (e.g.@: @code{height}, this
|
||||
returns the value itself; for properties with a list of values (e.g.@:
|
||||
@code{slice}), this returns the list of values.
|
||||
@defun get-display-property position spec &optional object properties
|
||||
This convenience function can be used to get the value of a specific
|
||||
display specification, no matter whether the @code{display} property is
|
||||
a vector, a list or a single display specification. This is like
|
||||
@code{get-text-property} (@pxref{Examining Properties}), but works on
|
||||
the @code{display} property only. For specifications with a single
|
||||
value (e.g.@: @code{height}), this returns the value itself; for
|
||||
properties with a list of values (e.g.@: @code{slice}), this returns the
|
||||
list of values.
|
||||
|
||||
@var{position} is the position in the buffer or string to examine, and
|
||||
@var{prop} is the @code{display} property to return. The optional
|
||||
@var{object} argument should be either a string or a buffer, and
|
||||
defaults to the current buffer. If the optional @var{properties}
|
||||
argument is non-@code{nil}, it should be a @code{display} property,
|
||||
and in that case, @var{position} and @var{object} are ignored. (This
|
||||
can be useful if you've already gotten the @code{display} property
|
||||
with @code{get-char-property}, for instance (@pxref{Examining
|
||||
Properties}).
|
||||
@var{spec} is the @sc{car} of the display specification to return. The
|
||||
optional @var{object} argument should be either a string or a buffer,
|
||||
and defaults to the current buffer. If the optional @var{properties}
|
||||
argument is non-@code{nil}, it should be a @code{display} property, and
|
||||
in that case, @var{position} and @var{object} are ignored. (This can be
|
||||
useful if you've already gotten the @code{display} property with
|
||||
@code{get-char-property}, for instance (@pxref{Examining Properties}).
|
||||
@end defun
|
||||
|
||||
@defun add-display-text-property start end prop value &optional object
|
||||
Add @code{display} property @var{prop} of @var{value} to the text from
|
||||
@var{start} to @var{end}.
|
||||
@defun add-display-text-property start end spec value &optional object
|
||||
Add the display specification @code{(@var{prop} @var{value})} to the
|
||||
text from @var{start} to @var{end}.
|
||||
|
||||
If any text in the region has a non-@code{nil} @code{display}
|
||||
property, those properties are retained. For instance:
|
||||
|
|
@ -5293,13 +5293,13 @@ property, those properties are retained. For instance:
|
|||
@end lisp
|
||||
|
||||
After doing this, the region from 2 to 4 will have the @code{raise}
|
||||
@code{display} property, the region from 4 to 8 will have both the
|
||||
@code{raise} and @code{height} @code{display} properties, and finally
|
||||
the region from 8 to 12 will only have the @code{raise} @code{display}
|
||||
property.
|
||||
display specification, the region from 4 to 8 will have both the
|
||||
@code{raise} and @code{height} display specifications, and finally the
|
||||
region from 8 to 12 will only have the @code{raise} display
|
||||
specification.
|
||||
|
||||
If @var{object} is non-@code{nil}, it should be a string or a buffer.
|
||||
If @code{nil}, this defaults to the current buffer.
|
||||
@var{object} is either a string or a buffer to add the specification to.
|
||||
If omitted, @var{object} defaults to the current buffer.
|
||||
@end defun
|
||||
|
||||
@cindex display property, unsafe evaluation
|
||||
|
|
|
|||
|
|
@ -417,14 +417,13 @@ indivisible unit."
|
|||
(nreverse result)))
|
||||
|
||||
;;;###autoload
|
||||
(defun add-display-text-property (start end prop value
|
||||
&optional object)
|
||||
"Add display property PROP with VALUE to the text from START to END.
|
||||
If any text in the region has a non-nil `display' property, those
|
||||
properties are retained.
|
||||
(defun add-display-text-property (start end spec value &optional object)
|
||||
"Add the display specification (SPEC VALUE) to the text from START to END.
|
||||
If any text in the region has a non-nil `display' property, the existing
|
||||
display specifications are retained.
|
||||
|
||||
If OBJECT is non-nil, it should be a string or a buffer. If nil,
|
||||
this defaults to the current buffer."
|
||||
OBJECT is either a string or a buffer to add the specification to.
|
||||
If omitted, OBJECT defaults to the current buffer."
|
||||
(let ((sub-start start)
|
||||
(sub-end 0)
|
||||
disp)
|
||||
|
|
@ -435,7 +434,7 @@ this defaults to the current buffer."
|
|||
(min end (point-max)))))
|
||||
(if (not (setq disp (get-text-property sub-start 'display object)))
|
||||
;; No old properties in this range.
|
||||
(put-text-property sub-start sub-end 'display (list prop value)
|
||||
(put-text-property sub-start sub-end 'display (list spec value)
|
||||
object)
|
||||
;; We have old properties.
|
||||
(let (type)
|
||||
|
|
@ -455,14 +454,14 @@ this defaults to the current buffer."
|
|||
(setq type 'list)
|
||||
disp)))
|
||||
;; Remove any old instances.
|
||||
(when-let* ((old (assoc prop disp)))
|
||||
(when-let* ((old (assoc spec disp)))
|
||||
;; If the property value was a list, don't modify the
|
||||
;; original value in place; it could be used by other
|
||||
;; regions of text.
|
||||
(setq disp (if (eq type 'list)
|
||||
(remove old disp)
|
||||
(delete old disp))))
|
||||
(setq disp (cons (list prop value) disp))
|
||||
(setq disp (cons (list spec value) disp))
|
||||
(when (eq type 'vector)
|
||||
(setq disp (seq-into disp 'vector)))
|
||||
;; Finally update the range.
|
||||
|
|
|
|||
24
src/xdisp.c
24
src/xdisp.c
|
|
@ -5570,7 +5570,7 @@ setup_for_ellipsis (struct it *it, int len)
|
|||
|
||||
|
||||
static Lisp_Object
|
||||
find_display_property (Lisp_Object disp, Lisp_Object prop)
|
||||
find_display_property (Lisp_Object disp, Lisp_Object spec)
|
||||
{
|
||||
Lisp_Object elem;
|
||||
if (NILP (disp))
|
||||
|
|
@ -5583,7 +5583,7 @@ find_display_property (Lisp_Object disp, Lisp_Object prop)
|
|||
elem = AREF (disp, i);
|
||||
if (CONSP (elem)
|
||||
&& CONSP (XCDR (elem))
|
||||
&& EQ (XCAR (elem), prop))
|
||||
&& EQ (XCAR (elem), spec))
|
||||
goto found;
|
||||
}
|
||||
return Qnil;
|
||||
|
|
@ -5597,7 +5597,7 @@ find_display_property (Lisp_Object disp, Lisp_Object prop)
|
|||
elem = XCAR (disp);
|
||||
if (CONSP (elem)
|
||||
&& CONSP (XCDR (elem))
|
||||
&& EQ (XCAR (elem), prop))
|
||||
&& EQ (XCAR (elem), spec))
|
||||
goto found;
|
||||
|
||||
/* Check that we have a proper list before going to the next
|
||||
|
|
@ -5612,7 +5612,7 @@ find_display_property (Lisp_Object disp, Lisp_Object prop)
|
|||
/* A simple display spec. */
|
||||
else if (CONSP (disp)
|
||||
&& CONSP (XCDR (disp))
|
||||
&& EQ (XCAR (disp), prop))
|
||||
&& EQ (XCAR (disp), spec))
|
||||
{
|
||||
elem = disp;
|
||||
goto found;
|
||||
|
|
@ -5753,13 +5753,15 @@ display_min_width (struct it *it, ptrdiff_t charpos,
|
|||
|
||||
DEFUN ("get-display-property", Fget_display_property,
|
||||
Sget_display_property, 2, 4, 0,
|
||||
doc: /* Get the value of the `display' property PROP at POSITION.
|
||||
If OBJECT, this should be a buffer or string where the property is
|
||||
fetched from. If omitted, OBJECT defaults to the current buffer.
|
||||
doc: /* Get the value of the display specification SPEC at POSITION.
|
||||
SPEC is the car of the display specification to fetch, e.g. `height'.
|
||||
|
||||
If PROPERTIES, look for value of PROP in PROPERTIES instead of the
|
||||
properties at POSITION. */)
|
||||
(Lisp_Object position, Lisp_Object prop, Lisp_Object object,
|
||||
OBJECT is either a string or a buffer to fetch the specification from.
|
||||
If omitted, OBJECT defaults to the current buffer.
|
||||
|
||||
If PROPERTIES is non-nil, look for value of SPEC in PROPERTIES instead
|
||||
of the properties at POSITION. */)
|
||||
(Lisp_Object position, Lisp_Object spec, Lisp_Object object,
|
||||
Lisp_Object properties)
|
||||
{
|
||||
if (NILP (properties))
|
||||
|
|
@ -5767,7 +5769,7 @@ properties at POSITION. */)
|
|||
else
|
||||
CHECK_LIST (properties);
|
||||
|
||||
return find_display_property (properties, prop);
|
||||
return find_display_property (properties, spec);
|
||||
}
|
||||
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue