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, and what they mean. 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.

Any attribute in a face can have the value unspecified. This means the face doesn't specify that attribute. In face merging, when the first face fails to specify a particular attribute, that means 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. (The attributes :family, :width, :height, :weight, and :slant correspond to parts of an X Logical Font Descriptor.)

:family

Font family name, or fontset name (see Fontsets). If you specify a font family name, the wild-card characters `*' and `?' are allowed.

:width

Relative proportionate width, also known as the character set width or 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

Either the font height, an integer in units of 1/10 point, a floating point number specifying the amount by which to scale the height of any underlying face, or a function, which is called with the old height (from the underlying face), and should return the new height.

:weight

Font weight—a symbol from this series (from most dense to most faint): ultra-bold, extra-bold, bold, semi-bold, normal, semi-light, light, extra-light, or ultra-light.

On a text-only terminal, any weight greater than normal is displayed as extra bright, and any weight less than normal is displayed as half-bright (provided the terminal supports the feature).

:slant

Font slant—one of the symbols italic, oblique, normal, reverse-italic, or reverse-oblique.

On a text-only terminal, slanted text is displayed as half-bright, if the terminal supports the feature.

:foreground

Foreground color, a string. The value can be a system-defined color name, or a hexadecimal color specification of the form `#rrggbb'. (`#000000' is black, `#ff0000' is red, `#00ff00' is green, `#0000ff' is blue, and `#ffffff' is white.)

:background

Background color, a string, like the foreground color.

: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.

: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.

: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. If a list of faces is used, attributes from faces earlier in the list override those from later faces.

: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.

In older versions of Emacs, before :family, :height, :width, :weight, and :slant existed, these attributes were used to specify the type face. They are now semi-obsolete, but they still work:

:font

This attribute specifies the font name.

:bold

A non-nil value specifies a bold font.

:italic

A non-nil value specifies an italic font.

For compatibility, you can still set these “attributes,” even though they are not real face attributes. Here is what that does:

:font

You can specify an X font name as the “value” of this “attribute”; that sets the :family, :width, :height, :weight, and :slant attributes according to the font name.

If the value is a pattern with wildcards, the first font that matches the pattern is used to set these attributes.

:bold

A non-nil makes the face bold; nil makes it normal. This actually works by setting the :weight attribute.

:italic

A non-nil makes the face italic; nil makes it normal. This actually works by setting the :slant attribute.