Defining Faces

The way to define a new face is with defface. This creates a kind of customization item (see section Writing Customization Definitions) which the user can customize using the Customization buffer (see section `Easy Customization' in The GNU Emacs Manual).

Macro: defface face spec doc [keyword value]...

Declare face as a customizable face that defaults according to spec. Do not quote the symbol face. The argument doc specifies the face documentation.

When defface executes, it defines the face according to spec, then uses any customizations that were read from the `.emacs' file to override that specification.

The purpose of spec is to specify how the face should appear on different kinds of terminals. It should be an alist whose elements have the form (display atts). The element's CAR, display, specifies a class of terminals. The CDR, atts, is a list of face attributes and their values; it specifies what the face should look like on that kind of terminal. The possible attributes are defined in the value of custom-face-attributes.

The display part of an element of spec determines which frames the element applies to. If more than one element of spec matches a given frame, the first matching element is the only one used for that frame. There are two possibilities for display:

t

This element of spec matches all frames. Therefore, any subsequent elements of spec are never used. Normally t is used in the last (or only) element of spec.

a list

If display is a list, each element should have the form (characteristic value...). Here characteristic specifies a way of classifying frames, and the values are possible classifications which display should apply to. Here are the possible values of characteristic:

type

The kind of window system the frame uses--either x, pc (for the MS-DOS console), w32 (for MS Windows 9X/NT), or tty.

class

What kinds of colors the frame supports--either color, grayscale, or mono.

background

The kind of background--either light or dark.

If an element of display specifies more than one value for a given characteristic, any of those values is acceptable. If display has more than one element, each element should specify a different characteristic; then each characteristic of the frame must match one of the values specified for it in display.

Here's how the standard face region could be defined with defface:

(defface region
         ((((class color) (background dark))
           (:background "blue"))
          (t (:background "gray")))
  "Used for displaying the region.")

Internally, defface uses the symbol property face-defface-spec to record the face attributes specified in defface, saved-face for the attributes saved by the user with the customization buffer, and face-documentation for the documentation string.

User Option: frame-background-mode

This option, if non-nil, specifies the background type to use for interpreting face definitions. If it is dark, then Emacs treats all frames as if they had a dark background, regardless of their actual background colors. If it is light, then Emacs treats all frames as if they had a light background.

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