38.11.4 Face Attribute Functions

You can modify the attributes of an existing face with the following functions. If you specify frame, they affect just that frame; otherwise, they affect all frames as well as the defaults that apply to new frames.

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

This function sets one or more attributes of face face for frame frame. If frame is nil, it sets the attribute for all frames, and the defaults for new frames.

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 corresponding values. Thus,

(set-face-attribute 'foo nil :width :extended :weight :bold :underline "red")

sets the attributes :width, :weight and :underline to the corresponding values.

Function: face-attribute face attribute &optional frame

This returns the value of the attribute attribute of face face on frame. If frame is nil, that means the selected frame (see section 29.9 Input Focus).

If frame is t, the value is the default for face for new frames.

For example,

(face-attribute 'bold :weight) => bold

The functions above did not exist before Emacs 21. For compatibility with older Emacs versions, you can use the following functions to set and examine the face attributes which existed in those versions.

Function: set-face-foreground face color &optional frame

Function: set-face-background face color &optional frame

These functions set the foreground (or background, respectively) color of face face to color. The argument color should be a string, the name of a color.

Certain shades of gray are implemented by stipple patterns on black-and-white screens.

Function: set-face-stipple face pattern &optional frame

This function sets the background stipple pattern of face face to pattern. The argument pattern should be the name of a stipple pattern defined by the X server, or nil meaning don't use stipple.

Normally there is no need to pay attention to stipple patterns, because they are used automatically to handle certain shades of gray.

Function: set-face-font face font &optional frame

This function sets the font of face face.

In Emacs 21, this actually sets the attributes :family, :width, :height, :weight, and :slant according to the font name font.

In Emacs 20, this sets the font attribute. Once you set the font explicitly, the bold and italic attributes cease to have any effect, because the precise font that you specified is used.

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

This function specifies whether face should be bold. If bold-p is non-nil, that means yes; nil means no.

In Emacs 21, this sets the :weight attribute. In Emacs 20, it sets the :bold attribute.

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

This function specifies whether face should be italic. If italic-p is non-nil, that means yes; nil means no.

In Emacs 21, this sets the :slant attribute. In Emacs 20, it sets the :italic attribute.

Function: set-face-underline-p face underline-p &optional frame

This function sets the underline attribute of face face. Non-nil means do underline; nil means don't.

Function: invert-face face &optional frame

This function inverts the :inverse-video attribute of face face. If the attribute is nil, this function sets it to t, and vice versa.

These functions examine the attributes of a face. If you don't specify frame, they refer to the default data for new frames. They return the symbol unspecified if the face doesn't define any value for that attribute.

Function: face-foreground face &optional frame

Function: face-background face &optional frame

These functions return the foreground color (or background color, respectively) of face face, as a string.

Function: face-stipple face &optional frame

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

Function: face-font face &optional frame

This function returns the name of the font of face face.

Function: face-bold-p face &optional frame

This function returns t if face is bold--that is, if it is bolder than normal. It returns nil otherwise.

Function: face-italic-p face &optional frame

This function returns t if face is italic or oblique, nil otherwise.

Function: face-underline-p face &optional frame

This function returns the :underline attribute of face face.

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

This function returns the :inverse-video attribute of face face.