GNU Info

(elisp)Defining Faces

---

Next: Face Attributes Prev: Standard Faces Up: Faces

---

Enter node , (file) or (file)node

Defining Faces
--------------

   The way to define a new face is with `defface'.  This creates a kind
of customization item (Note: Customization) which the user can
customize using the Customization buffer (*note Easy Customization:
(emacs)Easy Customization.).

 - Macro: defface face spec doc [keyword value]...
     This declares FACE as a customizable face that defaults according
     to SPEC.  You should not quote the symbol FACE.  The argument DOC
     specifies the face documentation.  The keywords you can use in
     `defface' are the same ones that are meaningful in both `defgroup'
     and `defcustom' (Note: Common Keywords).

     When `defface' executes, it defines the face according to SPEC,
     then uses any customizations that were read from the init file
     (Note: Init 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)'.  Each element's CAR,
     DISPLAY, specifies a class of terminals.  The element's second
     element, 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
               `graphic' (any graphics-capable display), `x', `pc' (for
               the MS-DOS console), `w32' (for MS Windows 9X/NT), or
               `tty' (a non-graphics-capable display).

         `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' is defined:

     (defface region
       `((((type tty) (class color))
          (:background "blue" :foreground "white"))
         (((type tty) (class mono))
          (:inverse-video t))
         (((class color) (background dark))
          (:background "blue"))
         (((class color) (background light))
          (:background "lightblue"))
         (t (:background "gray")))
       "Basic face for highlighting the region."
       :group 'basic-faces)

   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.