---

41.12.3 Face Attribute Functions

This section describes functions for directly accessing and modifying the attributes of a named face.

Function: face-attribute face attribute &optional frame inherit ¶

This function returns the value of the attribute attribute for face on frame. See Face Attributes, for the supported attributes.

If frame is omitted or nil, that means the selected frame (see Input Focus). If frame is t, 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 defface definition (see Defining Faces) or the spec set by face-spec-set. This default value of attribute is normally unspecified, unless you have specified some other value using set-face-attribute; see below.

If inherit is nil, only attributes directly defined by face are considered, so the return value may be unspecified, or a relative value. If inherit is non-nil, face’s definition of attribute is merged with the faces specified by its :inherit attribute; however the return value may still be unspecified or relative. If inherit 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.

To ensure that the return value is always specified and absolute, use a value of default for inherit; this will resolve any unspecified or relative values by merging with the default face (which is always completely specified).

For example,

(face-attribute 'bold :weight)
     ⇒ bold

Function: face-attribute-relative-p attribute value ¶

This function returns non-nil if value, when used as the value of the face attribute attribute, 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.

unspecified is a relative value for all attributes. For :height, floating point and function values are also relative.

For example:

(face-attribute-relative-p :height 2.0)
     ⇒ t

Function: face-all-attributes face &optional frame ¶

This function returns an alist of attributes of face. The elements of the result are name-value pairs of the form (attr-name . attr-value). Optional argument frame specifies the frame whose definition of face to return; if omitted or nil, the returned value describes the default attributes of face for newly created frames, i.e. the values these attributes have before applying the face spec in the face’s defface definition or the spec set by face-spec-set. These default values of the attributes are normally unspecified, unless you have specified some other value using set-face-attribute; see below.

Function: merge-face-attribute attribute value1 value2 ¶

If value1 is a relative value for the face attribute attribute, returns it merged with the underlying value value2; otherwise, if value1 is an absolute value for the face attribute attribute, returns value1 unchanged.

Normally, Emacs uses the face specs of each face to automatically calculate its attributes on each frame (see Defining Faces). The function set-face-attribute 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.

Function: set-face-attribute face frame &rest arguments ¶

This function sets one or more attributes of face for frame. The attributes specified in this way override the face spec(s) belonging to face. See Face Attributes, for the supported attributes.

The extra arguments arguments specify the attributes to set, and the values for them. They should consist of alternating attribute names (such as :family or :underline) and values. Thus,

(set-face-attribute 'foo nil :weight 'bold :slant 'italic)

sets the attribute :weight to bold and the attribute :slant to italic.

If frame is t, this function sets the default attributes for newly created frames; they will effectively override the attribute values specified by defface. If frame is nil, this function sets the attributes for all existing frames, as well as for newly created frames.

To reset the value of an attribute, that is, to indicate that the face doesn’t by itself specify a value for the attribute, use the special value unspecified (not nil!) for the attribute, and set the frame argument to t, in addition to the call with frame set to nil. This is because the default attributes for newly created frames are merged with the face’s spec in defface when a new frame is created, and so having unspecified in the default attributes for new frames will be unable to override defface; the special call to this function as described above will arrange for defface to be overridden.

Note that the attribute-value pairs are evaluated in the order they are specified, with the exception of the :family and :foundry attributes, which are evaluated first. This means that if a certain attribute is specified more than once, only the last value will be used. It also means that in some cases a different order of attributes will produce different results. For example, when :weight is placed before :font, the weight value is applied to the current font of the face, and might be rounded to the closest available weight of that font, whereas when :font is placed before :weight the weight value is applied to the specified font.

The following commands and functions mostly provide compatibility with old versions of Emacs. They work by calling set-face-attribute. Values of t and nil (or omitted) for their frame argument are handled just like set-face-attribute and face-attribute. The commands read their arguments using the minibuffer, if called interactively.

Command: set-face-foreground face color &optional frame ¶

Command: set-face-background face color &optional frame ¶

These set the :foreground attribute (or :background attribute, respectively) of face to color.

Command: set-face-stipple face pattern &optional frame ¶

This sets the :stipple attribute of face to pattern.

Command: set-face-font face font &optional frame ¶

Change the font-related attributes of face to those of font (a string or a font object). See face-font-attribute, for the supported formats of the font argument. This function sets the attribute :font of the face, and indirectly also the :family, :foundry, :width, :height, :weight, and :slant attributes, as defined by the font. If frame is non-nil, only change the attributes on the specified frame.

Function: set-face-bold face bold-p &optional frame ¶

This sets the :weight attribute of face to normal if bold-p is nil, and to bold otherwise.

Function: set-face-italic face italic-p &optional frame ¶

This sets the :slant attribute of face to normal if italic-p is nil, and to italic otherwise.

Command: set-face-underline face underline &optional frame ¶

This sets the :underline attribute of face to underline.

Command: set-face-inverse-video face inverse-video-p &optional frame ¶

This sets the :inverse-video attribute of face to inverse-video-p.

Command: invert-face face &optional frame ¶

This swaps the foreground and background colors of face face.

Command: set-face-extend face extend &optional frame ¶

This sets the :extend attribute of face to extend.

The following functions examine the attributes of a face. They mostly provide compatibility with old versions of Emacs. If you don’t specify frame, they refer to the selected frame; t refers to the default data for new frames. They return unspecified if the face doesn’t define any value for that attribute. If inherit is nil, only an attribute directly defined by the face is returned. If inherit is non-nil, any faces specified by its :inherit attribute are considered as well, and if inherit 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 default for inherit.

Function: face-font face &optional frame character ¶

This function returns the name of the font used by the specified face.

If the optional argument frame is specified, it returns the name of the font of face for that frame; frame defaults to the selected frame if it is nil or omitted. If frame is t, the function reports on the font defaults for face to be used for new frames.

By default, the returned font is for displaying ASCII characters, but if frame is anything but t, and the optional third argument character is supplied, the function returns the font name used by face for that character.

Function: face-foreground face &optional frame inherit ¶

Function: face-background face &optional frame inherit ¶

These functions return the foreground color (or background color, respectively) of face face, as a string. If the color is unspecified, they return nil.

Function: face-stipple face &optional frame inherit ¶

This function returns the name of the background stipple pattern of face face, or nil if it doesn’t have one.

Function: face-bold-p face &optional frame inherit ¶

This function returns a non-nil value if the :weight attribute of face is bolder than normal (i.e., one of semi-bold, bold, extra-bold, or ultra-bold). Otherwise, it returns nil.

Function: face-italic-p face &optional frame inherit ¶

This function returns a non-nil value if the :slant attribute of face is italic or oblique, and nil otherwise.

Function: face-underline-p face &optional frame inherit ¶

This function returns non-nil if face face specifies a non-nil :underline attribute.

Function: face-inverse-video-p face &optional frame inherit ¶

This function returns non-nil if face face specifies a non-nil :inverse-video attribute.

Function: face-extend-p face &optional frame inherit ¶

This function returns non-nil if face face specifies a non-nil :extend attribute. The inherit argument is passed to face-attribute.