Functions for Working with Faces

The attributes a face can specify include the font, the foreground color, the background color, and underlining. The face can also leave these unspecified by giving the value nil for them.

Here are the primitives for creating and changing faces.

Function: make-face name

This function defines a new face named name, initially with all attributes nil. It does nothing if there is already a face named name.

Function: face-list

This function returns a list of all defined face names.

Function: copy-face old-face new-name &optional frame new-frame

This function defines the face new-name as a copy of the existing face named old-face. It creates the face new-name if that doesn't already exist.

If the optional argument frame is given, this function applies only to that frame. Otherwise it applies to each frame individually, copying attributes from old-face in each frame to new-face in the same frame.

If the optional argument new-frame is given, then copy-face copies the attributes of old-face in frame to new-name in new-frame.

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-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. The argument font should be a string, either a valid font name for your system or the name of an Emacs fontset (see section Fontsets). Note that if you set the font explicitly, the bold and italic attributes cease to have any effect, because the precise font that you specified is always used.

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

This function sets the bold attribute of face face. Non-nil means bold; nil means non-bold.

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

This function sets the italic attribute of face face. Non-nil means italic; nil means non-italic.

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

Swap the foreground and background colors of face face. If the face doesn't specify both foreground and background, then its foreground and background are set to the default background and foreground, respectively.

These functions examine the attributes of a face. If you don't specify frame, they refer to the default data for new frames.

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 the bold attribute of face face.

Function: face-italic-p face &optional frame

This function returns the italic attribute of face face.

Function: face-underline-p face &optional frame

This function returns the underline attribute of face face.

Function: face-id face

This function returns the face number of face face.

Function: face-documentation face

This function returns the documentation string of face face, or nil if none was specified for it.

Function: face-equal face1 face2 &optional frame

This returns t if the faces face1 and face2 have the same attributes for display.

Function: face-differs-from-default-p face &optional frame

This returns t if the face face displays differently from the default face. A face is considered to be "the same" as the normal face if each attribute is either the same as that of the default face or nil (meaning to inherit from the default).

Variable: region-face

This variable's value specifies the face number to use to display characters in the region when it is active (in Transient Mark mode only). The face thus specified takes precedence over all faces that come from text properties and overlays, for characters in the region. See section The Mark, for more information about Transient Mark mode.

Normally, the value is the face number of the face named region.

Function: frame-update-face-colors frame

This function updates the way faces display on frame, for a change in frame's foreground or background color.

Go to the first, previous, next, last section, table of contents.