38.12.2 Face Attributes

The effect of using a face is determined by a fixed set of face attributes. This table lists all the face attributes, their possible values, and their effects. You can specify more than one face for a given piece of text; Emacs merges the attributes of all the faces to determine how to display the text. See Displaying Faces.

In addition to the values given below, each face attribute can also have the value unspecified. This special value means the face doesn't specify that attribute. In face merging, when the first face fails to specify a particular attribute, the next face gets a chance. However, the default face must specify all attributes.

Some of these font attributes are meaningful only on certain kinds of displays. If your display cannot handle a certain attribute, the attribute is ignored.

:family

Font family name or fontset name (a string). If you specify a font family name, the wild-card characters ‘*’ and ‘?’ are allowed. The function font-family-list, described below, returns a list of available family names. See Fontsets, for information about fontsets.

:foundry

The name of the font foundry in which the font family specified by the :family attribute is located (a string). The wild-card characters ‘*’ and ‘?’ are allowed.

:width

Relative proportionate character width, also known as the character set width. This should be one of the symbols ultra-condensed, extra-condensed, condensed, semi-condensed, normal, semi-expanded, expanded, extra-expanded, or ultra-expanded.

:height

The height of the font. In the simplest case, this is an integer in units of 1/10 point.

The value can also be a floating point number or a function, which specifies the height relative to an underlying face (i.e., a face that has a lower priority in the list described in Displaying Faces). If the value is a floating point number, that specifies the amount by which to scale the height of the underlying face. If the value is a function, that function 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.

:weight

Font weight—one of the symbols (from densest to faintest) ultra-bold, extra-bold, bold, semi-bold, normal, semi-light, light, extra-light, or ultra-light. On text-only terminals that 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.

:slant

Font slant—one of the symbols italic, oblique, normal, reverse-italic, or reverse-oblique. On text-only terminals that support variable-brightness text, slanted text is displayed as half-bright.

:foreground

Foreground color, a string. The value can be a system-defined color name, or a hexadecimal color specification. See Color Names. On black-and-white displays, certain shades of gray are implemented by stipple patterns.

:background

Background color, a string. The value can be a system-defined color name, or a hexadecimal color specification. See Color Names.

:underline

Whether or not characters should be underlined, and in what color. If the value is t, underlining uses the foreground color of the face. If the value is a string, underlining uses that color. The value nil means do not underline.

:overline

Whether or not characters should be overlined, and in what color. The value is used like that of :underline.

:strike-through

Whether or not characters should be strike-through, and in what color. The value is used like that of :underline.

:box

Whether or not a box should be drawn around characters, its color, the width of the box lines, and 3D appearance. Here are the possible values of the :box attribute, and what they mean:

nil

Don't draw a box.

t

Draw a box with lines of width 1, in the foreground color.

color

Draw a box with lines of width 1, in color color.

(:line-width width :color color :style style)

This way you can explicitly specify all aspects of the box. The value width specifies the width of the lines to draw; it defaults to 1.

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 is used.

:inverse-video

Whether or not characters should be displayed in inverse video. The value should be t (yes) or nil (no).

:stipple

The background stipple, a bitmap.

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 x-bitmap-file-path.

Alternatively, the value can specify the bitmap directly, with a list of the form (width height data). Here, 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.

:font

The font used to display the face. Its value should be a font object. See Font Selection, for information about font objects.

When specifying this attribute using set-face-attribute (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 Font Specification Options); 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 :family, :foundry, :width, :height, :weight, and :slant attributes.

:inherit

The name of a face from which to inherit attributes, or a list of face names. Attributes from inherited faces are merged into the face like an underlying face would be, with higher priority than underlying faces (see Displaying Faces). If a list of faces is used, attributes from faces earlier in the list override those from later faces.

For compatibility with Emacs 20, you can also specify values for two “fake” face attributes: :bold and :italic. Their values must be either t or nil; a value of unspecified is not allowed. Setting :bold to t is equivalent to setting the :weight attribute to bold, and setting it to nil is equivalent to setting :weight to normal. Setting :italic to t is equivalent to setting the :slant attribute to italic, and setting it to nil is equivalent to setting :slant to normal.