Commit f5df4ceb authored by Chong Yidong's avatar Chong Yidong
Browse files

Add/fix docs for add-face-text-property

* doc/lispref/text.texi (Changing Properties): Improve documentation for
add-face-text-property.
(Special Properties): Mention add-face-text-property.

* src/textprop.c (Fadd_face_text_property): Doc fix.  Rename `appendp'
argument to `append'.
parent ca65efcc
2013-12-20 Chong Yidong <cyd@gnu.org>
* text.texi (Changing Properties): Improve documentation for
add-face-text-property.
(Special Properties): Mention add-face-text-property.
2013-12-18 Chong Yidong <cyd@gnu.org>
* customize.texi (Custom Themes): Document custom-known-themes
......
......@@ -2825,29 +2825,37 @@ Do not rely on the return value of this function.
@end defun
@defun add-face-text-property start end face &optional appendp object
@code{face} text attributes can be combined. If you want to make a
section both italic and green, you can either define a new face that
have those attributes, or you can add both these attributes separately
to text:
This function acts on the text between @var{start} and @var{end},
adding the face @var{face} to the @code{face} text property.
@var{face} should be a valid value for the @code{face} property
(@pxref{Special Properties}), such as a face name or an anonymous face
(@pxref{Faces}).
If any text in the region already has a non-nil @code{face} property,
those face(s) are retained. This function sets the @code{face}
property to a list of faces, with @var{face} as the first element (by
default) and the pre-existing faces as the remaining elements. If the
optional argument @var{append} is non-@code{nil}, @var{face} is
appended to the end of the list instead. Note that in a face list,
the first occurring value for each attribute takes precedence.
For example, the following code would assign a italicized green face
to the text between @var{start} and @var{end}:
@example
(add-face-text-property @var{start} @var{end} 'italic)
(add-face-text-property @var{start} @var{end} '(:foreground "#00ff00"))
(add-face-text-property @var{start} @var{end} '(:foreground "red"))
(add-face-text-property @var{start} @var{end} '(:foreground "green"))
@end example
The attribute is (by default) prepended to the list of face
attributes, and the first attribute of the same type takes
precedence. So if you have two @code{:foreground} specifications, the
first one will take effect.
If you pass in @var{appendp}, the attribute will be appended instead
of prepended, which means that it will have no effect if there is
already an attribute of the same type.
The optional argument @var{object}, if non-@code{nil}, specifies a
buffer or string to act on, rather than the current buffer. If
@var{object} is a string, then @var{start} and @var{end} are
zero-based indices into the string.
@end defun
The easiest way to make a string with text properties
is with @code{propertize}:
The easiest way to make a string with text properties is with
@code{propertize}:
@defun propertize string &rest properties
This function returns a copy of @var{string} which has the text
......@@ -3081,6 +3089,9 @@ Font Lock mode (@pxref{Font Lock Mode}) works in most buffers by
dynamically updating the @code{face} property of characters based on
the context.
The @code{add-face-text-property} function provides a convenient way
to set this text property. @xref{Changing Properties}.
@item font-lock-face
@kindex font-lock-face @r{(text property)}
This property specifies a value for the @code{face} property that Font
......
......@@ -164,6 +164,7 @@ Available only on X, this option allows to control over-scrolling
using the scroll bar (i.e. dragging the thumb down even when the end
of the buffer is visible).
+++
** New function `add-face-text-property' has been added, which can be
used to conveniently prepend/append new face attributes to text.
......
2013-12-20 Chong Yidong <cyd@gnu.org>
* textprop.c (Fadd_face_text_property): Doc fix. Rename `appendp'
argument to `append'.
2013-12-19 Eli Zaretskii <eliz@gnu.org>
* xdisp.c (extend_face_to_end_of_line): Use default face, not the
......
......@@ -1338,20 +1338,27 @@ the designated part of OBJECT. */)
DEFUN ("add-face-text-property", Fadd_face_text_property,
Sadd_face_text_property, 3, 5, 0,
doc: /* Add the face property to the text from START to END.
The third argument FACE specifies the face to add.
If any text in the region already has any face properties, this new
face property will be added to the front of the face property list.
If the optional fourth argument APPENDP is non-nil, append to the end
of the face property list instead.
If the optional fifth argument OBJECT is a buffer (or nil, which means
the current buffer), START and END are buffer positions (integers or
FACE specifies the face to add. It should be a valid value of the
`face' property (typically a face name or a plist of face attributes
and values).
If any text in the region already has a non-nil `face' property, those
face(s) are retained. This is done by setting the `face' property to
a list of faces, with FACE as the first element (by default) and the
pre-existing faces as the remaining elements.
If optional fourth argument APPEND is non-nil, append FACE to the end
of the face list instead.
If optional fifth argument OBJECT is a buffer (or nil, which means the
current buffer), START and END are buffer positions (integers or
markers). If OBJECT is a string, START and END are 0-based indices
into it. */)
(Lisp_Object start, Lisp_Object end, Lisp_Object face,
Lisp_Object appendp, Lisp_Object object)
Lisp_Object append, Lisp_Object object)
{
add_text_properties_1 (start, end, list2 (Qface, face), object,
(NILP (appendp)
(NILP (append)
? TEXT_PROPERTY_PREPEND
: TEXT_PROPERTY_APPEND));
return Qnil;
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment