GNU Info

(elisp)Face Attributes

---

Next: Attribute Functions Prev: Defining Faces Up: Faces

---

Enter node , (file) or (file)node

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.  Note that in general, more than one face can be specified for a
given piece of text; when that happens, the attributes of all the faces
are merged to specify how to display the text.  Note: Merging Faces.

   In Emacs 21, 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 (Note: 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.

`:background'
     Background color, a string.

`: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 consecutie bytes in the string (which should be a unibyte
     string for best results).

     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.

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

   The attributes `:overline', `:strike-through' and `:box' are new in
Emacs 21.  The attributes `:family', `:height', `:width', `:weight',
`:slant' are also new; previous versions used the following attributes,
now semi-obsolete, to specify some of the same information:

`: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" in Emacs 21,
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.

 - Variable: x-bitmap-file-path
     This variable specifies a list of directories for searching for
     bitmap files, for the `:stipple' attribute.

 - Function: bitmap-spec-p object
     This returns `t' if OBJECT is a valid bitmap specification,
     suitable for use with `:stipple'.  It returns `nil' otherwise.