diff options
Diffstat (limited to 'devdocs/elisp/face-remapping.html')
| -rw-r--r-- | devdocs/elisp/face-remapping.html | 32 |
1 files changed, 32 insertions, 0 deletions
diff --git a/devdocs/elisp/face-remapping.html b/devdocs/elisp/face-remapping.html new file mode 100644 index 00000000..ed1498d3 --- /dev/null +++ b/devdocs/elisp/face-remapping.html @@ -0,0 +1,32 @@ + <h4 class="subsection">Face Remapping</h4> <p>The variable <code>face-remapping-alist</code> is used for buffer-local or global changes in the appearance of a face. For instance, it is used to implement the <code>text-scale-adjust</code> command (see <a href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Text-Scale.html#Text-Scale">Text Scale</a> in <cite>The GNU Emacs Manual</cite>). </p> <dl> <dt id="face-remapping-alist">Variable: <strong>face-remapping-alist</strong> +</dt> <dd> +<p>The value of this variable is an alist whose elements have the form <code>(<var>face</var> . <var>remapping</var>)</code>. This causes Emacs to display any text having the face <var>face</var> with <var>remapping</var>, rather than the ordinary definition of <var>face</var>. </p> <p><var>remapping</var> may be any face spec suitable for a <code>face</code> text property: either a face (i.e., a face name or a property list of attribute/value pairs), or a list of faces. For details, see the description of the <code>face</code> text property in <a href="special-properties">Special Properties</a>. <var>remapping</var> serves as the complete specification for the remapped face—it replaces the normal definition of <var>face</var>, instead of modifying it. </p> <p>If <code>face-remapping-alist</code> is buffer-local, its local value takes effect only within that buffer. If <code>face-remapping-alist</code> includes faces applicable only to certain windows, by using the <code>(:filtered (:window <var>param</var> <var>val</var>) <var>spec</var>)</code>, that face takes effect only in windows that match the filter conditions (see <a href="special-properties">Special Properties</a>). To turn off face filtering temporarily, bind <code>face-filters-always-match</code> to a non-<code>nil</code> value, then all face filters will match any window. </p> <p>Note: face remapping is non-recursive. If <var>remapping</var> references the same face name <var>face</var>, either directly or via the <code>:inherit</code> attribute of some other face in <var>remapping</var>, that reference uses the normal definition of <var>face</var>. For instance, if the <code>mode-line</code> face is remapped using this entry in <code>face-remapping-alist</code>: </p> <div class="example"> <pre class="example">(mode-line italic mode-line) +</pre> +</div> <p>then the new definition of the <code>mode-line</code> face inherits from the <code>italic</code> face, and the <em>normal</em> (non-remapped) definition of <code>mode-line</code> face. </p> +</dd> +</dl> <p>The following functions implement a higher-level interface to <code>face-remapping-alist</code>. Most Lisp code should use these functions instead of setting <code>face-remapping-alist</code> directly, to avoid trampling on remappings applied elsewhere. These functions are intended for buffer-local remappings, so they all make <code>face-remapping-alist</code> buffer-local as a side-effect. They manage <code>face-remapping-alist</code> entries of the form </p> <div class="example"> <pre class="example"> (<var>face</var> <var>relative-spec-1</var> <var>relative-spec-2</var> <var>...</var> <var>base-spec</var>) +</pre> +</div> <p>where, as explained above, each of the <var>relative-spec-N</var> and <var>base-spec</var> is either a face name, or a property list of attribute/value pairs. Each of the <em>relative remapping</em> entries, <var>relative-spec-N</var>, is managed by the <code>face-remap-add-relative</code> and <code>face-remap-remove-relative</code> functions; these are intended for simple modifications like changing the text size. The <em>base remapping</em> entry, <var>base-spec</var>, has the lowest priority and is managed by the <code>face-remap-set-base</code> and <code>face-remap-reset-base</code> functions; it is intended for major modes to remap faces in the buffers they control. </p> <dl> <dt id="face-remap-add-relative">Function: <strong>face-remap-add-relative</strong> <em>face &rest specs</em> +</dt> <dd> +<p>This function adds <var>specs</var> as relative remappings for face <var>face</var> in the current buffer. <var>specs</var> should be a list where each element is either a face name, or a property list of attribute/value pairs. </p> <p>The return value is a Lisp object that serves as a cookie; you can pass this object as an argument to <code>face-remap-remove-relative</code> if you need to remove the remapping later. </p> <div class="example"> <pre class="example">;; Remap the 'escape-glyph' face into a combination +;; of the 'highlight' and 'italic' faces: +(face-remap-add-relative 'escape-glyph 'highlight 'italic) + +;; Increase the size of the 'default' face by 50%: +(face-remap-add-relative 'default :height 1.5) +</pre> +</div> </dd> +</dl> <dl> <dt id="face-remap-remove-relative">Function: <strong>face-remap-remove-relative</strong> <em>cookie</em> +</dt> <dd><p>This function removes a relative remapping previously added by <code>face-remap-add-relative</code>. <var>cookie</var> should be the Lisp object returned by <code>face-remap-add-relative</code> when the remapping was added. </p></dd> +</dl> <dl> <dt id="face-remap-set-base">Function: <strong>face-remap-set-base</strong> <em>face &rest specs</em> +</dt> <dd> +<p>This function sets the base remapping of <var>face</var> in the current buffer to <var>specs</var>. If <var>specs</var> is empty, the default base remapping is restored, similar to calling <code>face-remap-reset-base</code> (see below); note that this is different from <var>specs</var> containing a single value <code>nil</code>, which has the opposite result (the global definition of <var>face</var> is ignored). </p> <p>This overwrites the default <var>base-spec</var>, which inherits the global face definition, so it is up to the caller to add such inheritance if so desired. </p> +</dd> +</dl> <dl> <dt id="face-remap-reset-base">Function: <strong>face-remap-reset-base</strong> <em>face</em> +</dt> <dd><p>This function sets the base remapping of <var>face</var> to its default value, which inherits from <var>face</var>’s global definition. </p></dd> +</dl><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/Face-Remapping.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Face-Remapping.html</a> + </p> +</div> |