1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
|
<h4 class="subsection">Face Attribute Functions</h4> <p>This section describes functions for directly accessing and modifying the attributes of a named face. </p> <dl> <dt id="face-attribute">Function: <strong>face-attribute</strong> <em>face attribute &optional frame inherit</em>
</dt> <dd>
<p>This function returns the value of the <var>attribute</var> attribute for <var>face</var> on <var>frame</var>. See <a href="face-attributes">Face Attributes</a>, for the supported attributes. </p> <p>If <var>frame</var> is omitted or <code>nil</code>, that means the selected frame (see <a href="input-focus">Input Focus</a>). If <var>frame</var> is <code>t</code>, this function returns the value of the specified attribute for newly-created frames, i.e. the value of the attribute before applying the face spec in the face’s <code>defface</code> definition (see <a href="defining-faces">Defining Faces</a>) or the spec set by <code>face-spec-set</code>. This default value of <var>attribute</var> is normally <code>unspecified</code>, unless you have specified some other value using <code>set-face-attribute</code>; see below. </p> <p>If <var>inherit</var> is <code>nil</code>, only attributes directly defined by <var>face</var> are considered, so the return value may be <code>unspecified</code>, or a relative value. If <var>inherit</var> is non-<code>nil</code>, <var>face</var>’s definition of <var>attribute</var> is merged with the faces specified by its <code>:inherit</code> attribute; however the return value may still be <code>unspecified</code> or relative. If <var>inherit</var> is a face or a list of faces, then the result is further merged with that face (or faces), until it becomes specified and absolute. </p> <p>To ensure that the return value is always specified and absolute, use a value of <code>default</code> for <var>inherit</var>; this will resolve any unspecified or relative values by merging with the <code>default</code> face (which is always completely specified). </p> <p>For example, </p> <div class="example"> <pre class="example">(face-attribute 'bold :weight)
⇒ bold
</pre>
</div> </dd>
</dl> <dl> <dt id="face-attribute-relative-p">Function: <strong>face-attribute-relative-p</strong> <em>attribute value</em>
</dt> <dd>
<p>This function returns non-<code>nil</code> if <var>value</var>, when used as the value of the face attribute <var>attribute</var>, is relative. This means it would modify, rather than completely override, any value that comes from a subsequent face in the face list or that is inherited from another face. </p> <p><code>unspecified</code> is a relative value for all attributes. For <code>:height</code>, floating point and function values are also relative. </p> <p>For example: </p> <div class="example"> <pre class="example">(face-attribute-relative-p :height 2.0)
⇒ t
</pre>
</div> </dd>
</dl> <dl> <dt id="face-all-attributes">Function: <strong>face-all-attributes</strong> <em>face &optional frame</em>
</dt> <dd><p>This function returns an alist of attributes of <var>face</var>. The elements of the result are name-value pairs of the form <code>(<var><span class="nolinebreak">attr-name</span></var> . <var><span class="nolinebreak">attr-value</span></var>)</code>. Optional argument <var>frame</var> specifies the frame whose definition of <var>face</var> to return; if omitted or <code>nil</code>, the returned value describes the default attributes of <var>face</var> for newly created frames, i.e. the values these attributes have before applying the face spec in the face’s <code>defface</code> definition or the spec set by <code>face-spec-set</code>. These default values of the attributes are normally <code>unspecified</code>, unless you have specified some other value using <code>set-face-attribute</code>; see below. </p></dd>
</dl> <dl> <dt id="merge-face-attribute">Function: <strong>merge-face-attribute</strong> <em>attribute value1 value2</em>
</dt> <dd><p>If <var>value1</var> is a relative value for the face attribute <var>attribute</var>, returns it merged with the underlying value <var>value2</var>; otherwise, if <var>value1</var> is an absolute value for the face attribute <var>attribute</var>, returns <var>value1</var> unchanged. </p></dd>
</dl> <p>Normally, Emacs uses the face specs of each face to automatically calculate its attributes on each frame (see <a href="defining-faces">Defining Faces</a>). The function <code>set-face-attribute</code> can override this calculation by directly assigning attributes to a face, either on a specific frame or for all frames. This function is mostly intended for internal usage. </p> <dl> <dt id="set-face-attribute">Function: <strong>set-face-attribute</strong> <em>face frame &rest arguments</em>
</dt> <dd>
<p>This function sets one or more attributes of <var>face</var> for <var>frame</var>. The attributes specified in this way override the face spec(s) belonging to <var>face</var>. See <a href="face-attributes">Face Attributes</a>, for the supported attributes. </p> <p>The extra arguments <var>arguments</var> specify the attributes to set, and the values for them. They should consist of alternating attribute names (such as <code>:family</code> or <code>:underline</code>) and values. Thus, </p> <div class="example"> <pre class="example">(set-face-attribute 'foo nil :weight 'bold :slant 'italic)
</pre>
</div> <p>sets the attribute <code>:weight</code> to <code>bold</code> and the attribute <code>:slant</code> to <code>italic</code>. </p> <p>If <var>frame</var> is <code>t</code>, this function sets the default attributes for newly created frames; they will effectively override the attribute values specified by <code>defface</code>. If <var>frame</var> is <code>nil</code>, this function sets the attributes for all existing frames, as well as for newly created frames. However, if you want to <em>reset</em> the value of an attribute to <code>unspecified</code> in a way that also affects newly created frames, you <em>must</em> explicitly call this function with <var>frame</var> set to <code>t</code> and the value of the attribute set to <code>unspecified</code> (<em>not</em> <code>nil</code>!), in addition to the call with <var>frame</var> set to <code>nil</code>. This is because the default attributes for newly created frames are merged with the face’s spec in <code>defface</code> when a new frame is created, and so having <code>unspecified</code> in the default attributes for new frames will be unable to override <code>defface</code>; the special call to this function as described above will arrange for <code>defface</code> to be overridden. </p>
</dd>
</dl> <p>The following commands and functions mostly provide compatibility with old versions of Emacs. They work by calling <code>set-face-attribute</code>. Values of <code>t</code> and <code>nil</code> (or omitted) for their <var>frame</var> argument are handled just like <code>set-face-attribute</code> and <code>face-attribute</code>. The commands read their arguments using the minibuffer, if called interactively. </p> <dl> <dt id="set-face-foreground">Command: <strong>set-face-foreground</strong> <em>face color &optional frame</em>
</dt> <dt id="set-face-background">Command: <strong>set-face-background</strong> <em>face color &optional frame</em>
</dt> <dd><p>These set the <code>:foreground</code> attribute (or <code>:background</code> attribute, respectively) of <var>face</var> to <var>color</var>. </p></dd>
</dl> <dl> <dt id="set-face-stipple">Command: <strong>set-face-stipple</strong> <em>face pattern &optional frame</em>
</dt> <dd><p>This sets the <code>:stipple</code> attribute of <var>face</var> to <var>pattern</var>. </p></dd>
</dl> <dl> <dt id="set-face-font">Command: <strong>set-face-font</strong> <em>face font &optional frame</em>
</dt> <dd><p>Change the font-related attributes of <var>face</var> to those of <var>font</var> (a string or a font object). See <a href="face-attributes#face_002dfont_002dattribute">face-font-attribute</a>, for the supported formats of the <var>font</var> argument. This function sets the attribute <code>:font</code> of the face, and indirectly also the <code>:family</code>, <code>:foundry</code>, <code>:width</code>, <code>:height</code>, <code>:weight</code>, and <code>:slant</code> attributes, as defined by the font. If <var>frame</var> is non-<code>nil</code>, only change the attributes on the specified frame. </p></dd>
</dl> <dl> <dt id="set-face-bold">Function: <strong>set-face-bold</strong> <em>face bold-p &optional frame</em>
</dt> <dd><p>This sets the <code>:weight</code> attribute of <var>face</var> to <var>normal</var> if <var>bold-p</var> is <code>nil</code>, and to <var>bold</var> otherwise. </p></dd>
</dl> <dl> <dt id="set-face-italic">Function: <strong>set-face-italic</strong> <em>face italic-p &optional frame</em>
</dt> <dd><p>This sets the <code>:slant</code> attribute of <var>face</var> to <var>normal</var> if <var>italic-p</var> is <code>nil</code>, and to <var>italic</var> otherwise. </p></dd>
</dl> <dl> <dt id="set-face-underline">Command: <strong>set-face-underline</strong> <em>face underline &optional frame</em>
</dt> <dd><p>This sets the <code>:underline</code> attribute of <var>face</var> to <var>underline</var>. </p></dd>
</dl> <dl> <dt id="set-face-inverse-video">Command: <strong>set-face-inverse-video</strong> <em>face inverse-video-p &optional frame</em>
</dt> <dd><p>This sets the <code>:inverse-video</code> attribute of <var>face</var> to <var>inverse-video-p</var>. </p></dd>
</dl> <dl> <dt id="invert-face">Command: <strong>invert-face</strong> <em>face &optional frame</em>
</dt> <dd><p>This swaps the foreground and background colors of face <var>face</var>. </p></dd>
</dl> <dl> <dt id="set-face-extend">Command: <strong>set-face-extend</strong> <em>face extend &optional frame</em>
</dt> <dd><p>This sets the <code>:extend</code> attribute of <var>face</var> to <var>extend</var>. </p></dd>
</dl> <p>The following functions examine the attributes of a face. They mostly provide compatibility with old versions of Emacs. If you don’t specify <var>frame</var>, they refer to the selected frame; <code>t</code> refers to the default data for new frames. They return <code>unspecified</code> if the face doesn’t define any value for that attribute. If <var>inherit</var> is <code>nil</code>, only an attribute directly defined by the face is returned. If <var>inherit</var> is non-<code>nil</code>, any faces specified by its <code>:inherit</code> attribute are considered as well, and if <var>inherit</var> is a face or a list of faces, then they are also considered, until a specified attribute is found. To ensure that the return value is always specified, use a value of <code>default</code> for <var>inherit</var>. </p> <dl> <dt id="face-font">Function: <strong>face-font</strong> <em>face &optional frame character</em>
</dt> <dd>
<p>This function returns the name of the font used by the specified <var>face</var>. </p> <p>If the optional argument <var>frame</var> is specified, it returns the name of the font of <var>face</var> for that frame; <var>frame</var> defaults to the selected frame if it is <code>nil</code> or omitted. If <var>frame</var> is <code>t</code>, the function reports on the font defaults for <var>face</var> to be used for new frames. </p> <p>By default, the returned font is for displaying ASCII characters, but if <var>frame</var> is anything but <code>t</code>, and the optional third argument <var>character</var> is supplied, the function returns the font name used by <var>face</var> for that character. </p>
</dd>
</dl> <dl> <dt id="face-foreground">Function: <strong>face-foreground</strong> <em>face &optional frame inherit</em>
</dt> <dt id="face-background">Function: <strong>face-background</strong> <em>face &optional frame inherit</em>
</dt> <dd><p>These functions return the foreground color (or background color, respectively) of face <var>face</var>, as a string. If the color is unspecified, they return <code>nil</code>. </p></dd>
</dl> <dl> <dt id="face-stipple">Function: <strong>face-stipple</strong> <em>face &optional frame inherit</em>
</dt> <dd><p>This function returns the name of the background stipple pattern of face <var>face</var>, or <code>nil</code> if it doesn’t have one. </p></dd>
</dl> <dl> <dt id="face-bold-p">Function: <strong>face-bold-p</strong> <em>face &optional frame inherit</em>
</dt> <dd><p>This function returns a non-<code>nil</code> value if the <code>:weight</code> attribute of <var>face</var> is bolder than normal (i.e., one of <code>semi-bold</code>, <code>bold</code>, <code>extra-bold</code>, or <code>ultra-bold</code>). Otherwise, it returns <code>nil</code>. </p></dd>
</dl> <dl> <dt id="face-italic-p">Function: <strong>face-italic-p</strong> <em>face &optional frame inherit</em>
</dt> <dd><p>This function returns a non-<code>nil</code> value if the <code>:slant</code> attribute of <var>face</var> is <code>italic</code> or <code>oblique</code>, and <code>nil</code> otherwise. </p></dd>
</dl> <dl> <dt id="face-underline-p">Function: <strong>face-underline-p</strong> <em>face &optional frame inherit</em>
</dt> <dd><p>This function returns non-<code>nil</code> if face <var>face</var> specifies a non-<code>nil</code> <code>:underline</code> attribute. </p></dd>
</dl> <dl> <dt id="face-inverse-video-p">Function: <strong>face-inverse-video-p</strong> <em>face &optional frame inherit</em>
</dt> <dd><p>This function returns non-<code>nil</code> if face <var>face</var> specifies a non-<code>nil</code> <code>:inverse-video</code> attribute. </p></dd>
</dl> <dl> <dt id="face-extend-p">Function: <strong>face-extend-p</strong> <em>face &optional frame inherit</em>
</dt> <dd><p>This function returns non-<code>nil</code> if face <var>face</var> specifies a non-<code>nil</code> <code>:extend</code> attribute. The <var>inherit</var> argument is passed to <code>face-attribute</code>. </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/Attribute-Functions.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Attribute-Functions.html</a>
</p>
</div>
|
