diff options
Diffstat (limited to 'devdocs/elisp/defining-faces.html')
| -rw-r--r-- | devdocs/elisp/defining-faces.html | 38 |
1 files changed, 38 insertions, 0 deletions
diff --git a/devdocs/elisp/defining-faces.html b/devdocs/elisp/defining-faces.html new file mode 100644 index 00000000..339a4433 --- /dev/null +++ b/devdocs/elisp/defining-faces.html @@ -0,0 +1,38 @@ + <h4 class="subsection">Defining Faces</h4> <p>The usual way to define a face is through the <code>defface</code> macro. This macro associates a face name (a symbol) with a default <em>face spec</em>. A face spec is a construct which specifies what attributes a face should have on any given terminal; for example, a face spec might specify one foreground color on high-color terminals, and a different foreground color on low-color terminals. </p> <p>People are sometimes tempted to create a variable whose value is a face name. In the vast majority of cases, this is not necessary; the usual procedure is to define a face with <code>defface</code>, and then use its name directly. </p> <p>Note that once you have defined a face (usually with <code>defface</code>), you cannot later undefine this face safely, except by restarting Emacs. </p> <dl> <dt id="defface">Macro: <strong>defface</strong> <em>face spec doc [keyword value]…</em> +</dt> <dd> +<p>This macro declares <var>face</var> as a named face whose default face spec is given by <var>spec</var>. You should not quote the symbol <var>face</var>, and it should not end in ‘<samp>-face</samp>’ (that would be redundant). The argument <var>doc</var> is a documentation string for the face. The additional <var>keyword</var> arguments have the same meanings as in <code>defgroup</code> and <code>defcustom</code> (see <a href="common-keywords">Common Keywords</a>). </p> <p>If <var>face</var> already has a default face spec, this macro does nothing. </p> <p>The default face spec determines <var>face</var>’s appearance when no customizations are in effect (see <a href="customization">Customization</a>). If <var>face</var> has already been customized (via Custom themes or via customizations read from the init file), its appearance is determined by the custom face spec(s), which override the default face spec <var>spec</var>. However, if the customizations are subsequently removed, the appearance of <var>face</var> will again be determined by its default face spec. </p> <p>As an exception, if you evaluate a <code>defface</code> form with <kbd>C-M-x</kbd> (<code>eval-defun</code>) or with <kbd>C-x C-e</kbd> (<code>eval-last-sexp</code>) in Emacs Lisp mode, a special feature of these commands overrides any custom face specs on the face, causing the face to reflect exactly what the <code>defface</code> says. </p> <p>The <var>spec</var> argument is a <em>face spec</em>, which states how the face should appear on different kinds of terminals. It should be an alist whose elements each have the form </p> <div class="example"> <pre class="example">(<var>display</var> . <var>plist</var>) +</pre> +</div> <p><var>display</var> specifies a class of terminals (see below). <var>plist</var> is a property list of face attributes and their values, specifying how the face appears on such terminals. For backward compatibility, you can also write an element as <code>(<var>display</var> <var>plist</var>)</code>. </p> <p>The <var>display</var> part of an element of <var>spec</var> determines which terminals the element matches. If more than one element of <var>spec</var> matches a given terminal, the first element that matches is the one used for that terminal. There are three possibilities for <var>display</var>: </p> <dl compact> <dt><code>default</code></dt> <dd> +<p>This element of <var>spec</var> doesn’t match any terminal; instead, it specifies defaults that apply to all terminals. This element, if used, must be the first element of <var>spec</var>. Each of the following elements can override any or all of these defaults. </p> </dd> <dt><code>t</code></dt> <dd> +<p>This element of <var>spec</var> matches all terminals. Therefore, any subsequent elements of <var>spec</var> are never used. Normally <code>t</code> is used in the last (or only) element of <var>spec</var>. </p> </dd> <dt>a list</dt> <dd> +<p>If <var>display</var> is a list, each element should have the form <code>(<var>characteristic</var> <var>value</var>…)</code>. Here <var>characteristic</var> specifies a way of classifying terminals, and the <var>value</var>s are possible classifications which <var>display</var> should apply to. Here are the possible values of <var>characteristic</var>: </p> <dl compact> <dt><code>type</code></dt> <dd> +<p>The kind of window system the terminal uses—either <code>graphic</code> (any graphics-capable display), <code>x</code>, <code>pc</code> (for the MS-DOS console), <code>w32</code> (for MS Windows 9X/NT/2K/XP), or <code>tty</code> (a non-graphics-capable display). See <a href="window-systems">window-system</a>. </p> </dd> <dt><code>class</code></dt> <dd> +<p>What kinds of colors the terminal supports—either <code>color</code>, <code>grayscale</code>, or <code>mono</code>. </p> </dd> <dt><code>background</code></dt> <dd> +<p>The kind of background—either <code>light</code> or <code>dark</code>. </p> </dd> <dt><code>min-colors</code></dt> <dd> +<p>An integer that represents the minimum number of colors the terminal should support. This matches a terminal if its <code>display-color-cells</code> value is at least the specified integer. </p> </dd> <dt><code>supports</code></dt> <dd><p>Whether or not the terminal can display the face attributes given in <var>value</var>… (see <a href="face-attributes">Face Attributes</a>). See <a href="display-feature-testing#Display-Face-Attribute-Testing">Display Face Attribute Testing</a>, for more information on exactly how this testing is done. </p></dd> </dl> <p>If an element of <var>display</var> specifies more than one <var>value</var> for a given <var>characteristic</var>, any of those values is acceptable. If <var>display</var> has more than one element, each element should specify a different <var>characteristic</var>; then <em>each</em> characteristic of the terminal must match one of the <var>value</var>s specified for it in <var>display</var>. </p> +</dd> </dl> </dd> +</dl> <p>For example, here’s the definition of the standard face <code>highlight</code>: </p> <div class="example"> <pre class="example">(defface highlight + '((((class color) (min-colors 88) (background light)) + :background "darkseagreen2") + (((class color) (min-colors 88) (background dark)) + :background "darkolivegreen") + (((class color) (min-colors 16) (background light)) + :background "darkseagreen2") + (((class color) (min-colors 16) (background dark)) + :background "darkolivegreen") + (((class color) (min-colors 8)) + :background "green" :foreground "black") + (t :inverse-video t)) + "Basic face for highlighting." + :group 'basic-faces) +</pre> +</div> <p>Internally, Emacs stores each face’s default spec in its <code>face-defface-spec</code> symbol property (see <a href="symbol-properties">Symbol Properties</a>). The <code>saved-face</code> property stores any face spec saved by the user using the customization buffer; the <code>customized-face</code> property stores the face spec customized for the current session, but not saved; and the <code>theme-face</code> property stores an alist associating the active customization settings and Custom themes with the face specs for that face. The face’s documentation string is stored in the <code>face-documentation</code> property. </p> <p>Normally, a face is declared just once, using <code>defface</code>, and any further changes to its appearance are applied using the Customize framework (e.g., via the Customize user interface or via the <code>custom-set-faces</code> function; see <a href="applying-customizations">Applying Customizations</a>), or by face remapping (see <a href="face-remapping">Face Remapping</a>). In the rare event that you need to change a face spec directly from Lisp, you can use the <code>face-spec-set</code> function. </p> <dl> <dt id="face-spec-set">Function: <strong>face-spec-set</strong> <em>face spec &optional spec-type</em> +</dt> <dd> +<p>This function applies <var>spec</var> as a face spec for <code>face</code>. <var>spec</var> should be a face spec, as described in the above documentation for <code>defface</code>. </p> <p>This function also defines <var>face</var> as a valid face name if it is not already one, and (re)calculates its attributes on existing frames. </p> <p>The optional argument <var>spec-type</var> determines which spec to set. If it is omitted or <code>nil</code> or <code>face-override-spec</code>, this function sets the <em>override spec</em>, which overrides face specs on <var>face</var> of all the other types mentioned below. This is useful when calling this function outside of Custom code. If <var>spec-type</var> is <code>customized-face</code> or <code>saved-face</code>, this function sets the customized spec or the saved custom spec, respectively. If it is <code>face-defface-spec</code>, this function sets the default face spec (the same one set by <code>defface</code>). If it is <code>reset</code>, this function clears out all customization specs and override specs from <var>face</var> (in this case, the value of <var>spec</var> is ignored). The effect of any other value of <var>spec-type</var> on the face specs is reserved for internal use, but the function will still define <var>face</var> itself and recalculate its attributes, as described above. </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/Defining-Faces.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Defining-Faces.html</a> + </p> +</div> |