diff options
Diffstat (limited to 'devdocs/elisp/changing-properties.html')
| -rw-r--r-- | devdocs/elisp/changing-properties.html | 54 |
1 files changed, 54 insertions, 0 deletions
diff --git a/devdocs/elisp/changing-properties.html b/devdocs/elisp/changing-properties.html new file mode 100644 index 00000000..3531e5d5 --- /dev/null +++ b/devdocs/elisp/changing-properties.html @@ -0,0 +1,54 @@ + <h4 class="subsection">Changing Text Properties</h4> <p>The primitives for changing properties apply to a specified range of text in a buffer or string. The function <code>set-text-properties</code> (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. </p> <p>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 <a href="undo">Undo</a>). Positions in a string start from 0, whereas positions in a buffer start from 1. </p> <dl> <dt id="put-text-property">Function: <strong>put-text-property</strong> <em>start end prop value &optional object</em> +</dt> <dd><p>This function sets the <var>prop</var> property to <var>value</var> for the text between <var>start</var> and <var>end</var> in the string or buffer <var>object</var>. If <var>object</var> is <code>nil</code>, it defaults to the current buffer. </p></dd> +</dl> <dl> <dt id="add-text-properties">Function: <strong>add-text-properties</strong> <em>start end props &optional object</em> +</dt> <dd> +<p>This function adds or overrides text properties for the text between <var>start</var> and <var>end</var> in the string or buffer <var>object</var>. If <var>object</var> is <code>nil</code>, it defaults to the current buffer. </p> <p>The argument <var>props</var> specifies which properties to add. It should have the form of a property list (see <a href="property-lists">Property Lists</a>): a list whose elements include the property names followed alternately by the corresponding values. </p> <p>The return value is <code>t</code> if the function actually changed some property’s value; <code>nil</code> otherwise (if <var>props</var> is <code>nil</code> or its values agree with those in the text). </p> <p>For example, here is how to set the <code>comment</code> and <code>face</code> properties of a range of text: </p> <div class="example"> <pre class="example">(add-text-properties <var>start</var> <var>end</var> + '(comment t face highlight)) +</pre> +</div> </dd> +</dl> <dl> <dt id="remove-text-properties">Function: <strong>remove-text-properties</strong> <em>start end props &optional object</em> +</dt> <dd> +<p>This function deletes specified text properties from the text between <var>start</var> and <var>end</var> in the string or buffer <var>object</var>. If <var>object</var> is <code>nil</code>, it defaults to the current buffer. </p> <p>The argument <var>props</var> specifies which properties to delete. It should have the form of a property list (see <a href="property-lists">Property Lists</a>): 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 <code>face</code> property. </p> <div class="example"> <pre class="example">(remove-text-properties <var>start</var> <var>end</var> '(face nil)) +</pre> +</div> <p>The return value is <code>t</code> if the function actually changed some property’s value; <code>nil</code> otherwise (if <var>props</var> is <code>nil</code> or if no character in the specified text had any of those properties). </p> <p>To remove all text properties from certain text, use <code>set-text-properties</code> and specify <code>nil</code> for the new property list. </p> +</dd> +</dl> <dl> <dt id="remove-list-of-text-properties">Function: <strong>remove-list-of-text-properties</strong> <em>start end list-of-properties &optional object</em> +</dt> <dd><p>Like <code>remove-text-properties</code> except that <var>list-of-properties</var> is a list of property names only, not an alternating list of property names and values. </p></dd> +</dl> <dl> <dt id="set-text-properties">Function: <strong>set-text-properties</strong> <em>start end props &optional object</em> +</dt> <dd> +<p>This function completely replaces the text property list for the text between <var>start</var> and <var>end</var> in the string or buffer <var>object</var>. If <var>object</var> is <code>nil</code>, it defaults to the current buffer. </p> <p>The argument <var>props</var> is the new property list. It should be a list whose elements are property names alternating with corresponding values. </p> <p>After <code>set-text-properties</code> returns, all the characters in the specified range have identical properties. </p> <p>If <var>props</var> is <code>nil</code>, the effect is to get rid of all properties from the specified range of text. Here’s an example: </p> <div class="example"> <pre class="example">(set-text-properties <var>start</var> <var>end</var> nil) +</pre> +</div> <p>Do not rely on the return value of this function. </p> +</dd> +</dl> <dl> <dt id="add-face-text-property">Function: <strong>add-face-text-property</strong> <em>start end face &optional appendp object</em> +</dt> <dd> +<p>This function acts on the text between <var>start</var> and <var>end</var>, adding the face <var>face</var> to the <code>face</code> text property. <var>face</var> should be a valid value for the <code>face</code> property (see <a href="special-properties">Special Properties</a>), such as a face name or an anonymous face (see <a href="faces">Faces</a>). </p> <p>If any text in the region already has a non-<code>nil</code> <code>face</code> property, those face(s) are retained. This function sets the <code>face</code> property to a list of faces, with <var>face</var> as the first element (by default) and the pre-existing faces as the remaining elements. If the optional argument <var>appendp</var> is non-<code>nil</code>, <var>face</var> is appended to the end of the list instead. Note that in a face list, the first occurring value for each attribute takes precedence. </p> <p>For example, the following code would assign an italicized green face to the text between <var>start</var> and <var>end</var>: </p> <div class="example"> <pre class="example">(add-face-text-property <var>start</var> <var>end</var> 'italic) +(add-face-text-property <var>start</var> <var>end</var> '(:foreground "red")) +(add-face-text-property <var>start</var> <var>end</var> '(:foreground "green")) +</pre> +</div> <p>The optional argument <var>object</var>, if non-<code>nil</code>, specifies a buffer or string to act on, rather than the current buffer. If <var>object</var> is a string, then <var>start</var> and <var>end</var> are zero-based indices into the string. </p> +</dd> +</dl> <p>The easiest way to make a string with text properties is with <code>propertize</code>: </p> <dl> <dt id="propertize">Function: <strong>propertize</strong> <em>string &rest properties</em> +</dt> <dd> +<p>This function returns a copy of <var>string</var> with the text properties <var>properties</var> added. These properties apply to all the characters in the string that is returned. Here is an example that constructs a string with a <code>face</code> property and a <code>mouse-face</code> property: </p> <div class="example"> <pre class="example">(propertize "foo" 'face 'italic + 'mouse-face 'bold-italic) + ⇒ #("foo" 0 3 (mouse-face bold-italic face italic)) +</pre> +</div> <p>To put different properties on various parts of a string, you can construct each part with <code>propertize</code> and then combine them with <code>concat</code>: </p> <div class="example"> <pre class="example">(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)) +</pre> +</div> </dd> +</dl> <p>See <a href="buffer-contents">Buffer Contents</a>, for the function <code>buffer-substring-no-properties</code>, which copies text from the buffer but does not copy its properties. </p> <p>If you wish to add text properties to a buffer or remove them without marking the buffer as modified, you can wrap the calls above in the <code>with-silent-modifications</code> macro. See <a href="buffer-modification">Buffer Modification</a>. </p><div class="_attribution"> + <p class="_attribution-p"> + Copyright © 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br> + <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Changing-Properties.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Changing-Properties.html</a> + </p> +</div> |