Face attributes determine the visual appearance of a face. The following table lists all the face attributes, their possible values, and their effects.
Apart from the values given below, each face attribute can have the
unspecified. This special value means that the face
doesn't specify that attribute directly. An
attribute tells Emacs to refer instead to a parent face (see the
:inherit attribute below); or, failing that, to an
underlying face (see Displaying Faces). The
must specify all attributes.
Some of these attributes are meaningful only on certain kinds of displays. If your display cannot handle a certain attribute, the attribute is ignored.
font-family-list(see below) returns a list of available family names. See Fontsets, for information about fontsets.
:familyattribute (a string). See Fonts.
The value can also be floating point or a function, which specifies the height relative to an underlying face (see Displaying Faces). A floating-point value specifies the amount by which to scale the height of the underlying face. A function value is called with one argument, the height of the underlying face, and returns the height of the new face. If the function is passed an integer argument, it must return an integer.
The height of the default face must be specified using an integer;
floating point and function values are not allowed.
ultra-light. On text terminals which support variable-brightness text, any weight greater than normal is displayed as extra bright, and any weight less than normal is displayed as half-bright.
reverse-oblique. On text terminals that support variable-brightness text, slanted text is displayed as half-bright.
:foregroundbut the color is only used as a foreground when the background color is near to the foreground that would have been used. This is useful for example when marking text (i.e., the region face). If the text has a foreground that is visible with the region face, that foreground is used. If the foreground is near the region face background,
:distant-foregroundis used instead so the text is readable.
foreground-color, meaning the foreground color of the face. Omitting the attribute
:colormeans to use the foreground color of the face. style should be a symbol
wave, meaning to use a straight or wavy line. Omitting the attribute
:stylemeans to use a straight line.
t, overlining uses the foreground color of the face. If the value is a string, overlining uses that color. The value
nilmeans do not overline.
:boxattribute, and what they mean:
The value color specifies the color to draw with. The default is the foreground color of the face for simple boxes, and the background color of the face for 3D boxes.
The value style specifies whether to draw a 3D box. If it is
released-button, the box looks like a 3D button that is not being
pressed. If it is
pressed-button, the box looks like a 3D button
that is being pressed. If it is
nil or omitted, a plain 2D box
The value can be a string; that should be the name of a file containing
external-format X bitmap data. The file is found in the directories
listed in the variable
Alternatively, the value can specify the bitmap directly, with a list
of the form
(width height data
width and height specify the size in pixels, and
data is a string containing the raw bits of the bitmap, row by
row. Each row occupies (width + 7) / 8 consecutive bytes
in the string (which should be a unibyte string for best results).
This means that each row always occupies at least one whole byte.
If the value is
nil, that means use no stipple pattern.
Normally you do not need to set the stipple attribute, because it is
used automatically to handle certain shades of gray.
When specifying this attribute using
(see Attribute Functions), you may also supply a font spec, a font
entity, or a string. Emacs converts such values to an appropriate
font object, and stores that font object as the actual attribute
value. If you specify a string, the contents of the string should be
a font name (see Fonts); if the
font name is an XLFD containing wildcards, Emacs chooses the first
font matching those wildcards. Specifying this attribute also changes
the values of the
This function returns a list of available font family names. The optional argument frame specifies the frame on which the text is to be displayed; if it is
nil, the selected frame is used.
This variable specifies the minimum distance between the baseline and the underline, in pixels, when displaying underlined text.
This variable specifies a list of directories for searching for bitmap files, for the