Next: Property Search, Previous: Examining Properties, Up: Text Properties
The primitives for changing properties apply to a specified range of
text in a buffer or string. The function set-text-properties
(see end of section) sets the entire property list of the text in that
range; more often, it is useful to add, change, or delete just certain
properties specified by name.
Since text properties are considered part of the contents of the buffer (or string), and can affect how a buffer looks on the screen, any change in buffer text properties marks the buffer as modified. Buffer text property changes are undoable also (see Undo).
This function sets the prop property to value for the text between start and end in the string or buffer object. If object is
nil
, it defaults to the current buffer.
This function adds or overrides text properties for the text between start and end in the string or buffer object. If object is
nil
, it defaults to the current buffer.The argument props specifies which properties to add. It should have the form of a property list (see Property Lists): a list whose elements include the property names followed alternately by the corresponding values.
The return value is
t
if the function actually changed some property's value;nil
otherwise (if props isnil
or its values agree with those in the text).For example, here is how to set the
comment
andface
properties of a range of text:(add-text-properties start end '(comment t face highlight))
This function deletes specified text properties from the text between start and end in the string or buffer object. If object is
nil
, it defaults to the current buffer.The argument props specifies which properties to delete. It should have the form of a property list (see Property Lists): a list whose elements are property names alternating with corresponding values. But only the names matter—the values that accompany them are ignored. For example, here's how to remove the
face
property.(remove-text-properties start end '(face nil))The return value is
t
if the function actually changed some property's value;nil
otherwise (if props isnil
or if no character in the specified text had any of those properties).To remove all text properties from certain text, use
set-text-properties
and specifynil
for the new property list.
This function completely replaces the text property list for the text between start and end in the string or buffer object. If object is
nil
, it defaults to the current buffer.The argument props is the new property list. It should be a list whose elements are property names alternating with corresponding values.
After
set-text-properties
returns, all the characters in the specified range have identical properties.If props is
nil
, the effect is to get rid of all properties from the specified range of text. Here's an example:(set-text-properties start end nil)
The easiest way to make a string with text properties
is with propertize
:
This function returns a copy of string which has the text properties properties. These properties apply to all the characters in the string that is returned. Here is an example that constructs a string with a
face
property and amouse-face
property:(propertize "foo" 'face 'italic 'mouse-face 'bold-italic) => #("foo" 0 3 (mouse-face bold-italic face italic))To put different properties on various parts of a string, you can construct each part with
propertize
and then combine them withconcat
:(concat (propertize "foo" 'face 'italic 'mouse-face 'bold-italic) " and " (propertize "bar" 'face 'italic 'mouse-face 'bold-italic)) => #("foo and bar" 0 3 (face italic mouse-face bold-italic) 3 8 nil 8 11 (face italic mouse-face bold-italic))
See also the function buffer-substring-no-properties
(see Buffer Contents) which copies text from the buffer
but does not copy its properties.