diff options
| -rw-r--r-- | doc/lispref/ChangeLog | 6 | ||||
| -rw-r--r-- | doc/lispref/text.texi | 43 | ||||
| -rw-r--r-- | etc/NEWS | 1 | ||||
| -rw-r--r-- | src/ChangeLog | 5 | ||||
| -rw-r--r-- | src/textprop.c | 25 |
5 files changed, 55 insertions, 25 deletions
diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index af09f4371f9..3ae7e0040cc 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,9 @@ +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 diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi index aa19338ddaf..b814d553296 100644 --- a/doc/lispref/text.texi +++ b/doc/lispref/text.texi @@ -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. diff --git a/src/ChangeLog b/src/ChangeLog index 74ae25327ab..23857e33a6d 100644 --- a/src/ChangeLog +++ b/src/ChangeLog @@ -1,3 +1,8 @@ +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 diff --git a/src/textprop.c b/src/textprop.c index 5597a781a61..d5f86922ade 100644 --- a/src/textprop.c +++ b/src/textprop.c @@ -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; |