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.

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-underline-p face &optional frame

This function returns the underline attribute of face face.

Function: face-id face

This function returns the face id number of face face.

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 id 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 id number of the face named region.

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