GNU Info

(elisp)Attribute Functions

---

Next: Merging Faces Prev: Face Attributes Up: Faces

---

Enter node , (file) or (file)node

Face Attribute Functions
------------------------

   You can modify the attributes of an existing face with the following
functions.  If you specify FRAME, they affect just that frame;
otherwise, they affect all frames as well as the defaults that apply to
new frames.

 - Function: set-face-attribute face frame &rest arguments
     This function sets one or more attributes of face FACE for frame
     FRAME.  If FRAME is `nil', it sets the attribute for all frames,
     and the defaults for new frames.

     The extra arguments ARGUMENTS specify the attributes to set, and
     the values for them.  They should consist of alternating attribute
     names (such as `:family' or `:underline') and corresponding values.
     Thus,

          (set-face-attribute 'foo nil
                              :width :extended
                              :weight :bold
                              :underline "red")

     sets the attributes `:width', `:weight' and `:underline' to the
     corresponding values.

 - Function: face-attribute face attribute &optional frame
     This returns the value of the ATTRIBUTE attribute of face FACE on
     FRAME.  If FRAME is `nil', that means the selected frame (Note:
     Input Focus).

     If FRAME is `t', the value is the default for FACE for new frames.

     For example,

          (face-attribute 'bold :weight)
               => bold

   The functions above did not exist before Emacs 21.  For compatibility
with older Emacs versions, you can use the following functions to set
and examine the face attributes which existed in those versions.

 - Function: set-face-foreground face color &optional frame
 - Function: set-face-background face color &optional frame
     These functions set the foreground (or background, respectively)
     color of face FACE to COLOR.  The argument COLOR should be a
     string, the name of a color.

     Certain shades of gray are implemented by stipple patterns on
     black-and-white screens.

 - Function: set-face-stipple face pattern &optional frame
     This function sets the background stipple pattern of face FACE to
     PATTERN.  The argument PATTERN should be the name of a stipple
     pattern defined by the X server, or `nil' meaning don't use
     stipple.

     Normally there is no need to pay attention to stipple patterns,
     because they are used automatically to handle certain shades of
     gray.

 - Function: set-face-font face font &optional frame
     This function sets the font of face FACE.

     In Emacs 21, this actually sets the attributes `:family',
     `:width', `:height', `:weight', and `:slant' according to the font
     name FONT.

     In Emacs 20, this sets the font attribute.  Once you set the font
     explicitly, the bold and italic attributes cease to have any
     effect, because the precise font that you specified is used.

 - Function: set-face-bold-p face bold-p &optional frame
     This function specifies whether FACE should be bold.  If BOLD-P is
     non-`nil', that means yes; `nil' means no.

     In Emacs 21, this sets the `:weight' attribute.  In Emacs 20, it
     sets the `:bold' attribute.

 - Function: set-face-italic-p face italic-p &optional frame
     This function specifies whether FACE should be italic.  If
     ITALIC-P is non-`nil', that means yes; `nil' means no.

     In Emacs 21, this sets the `:slant' attribute.  In Emacs 20, it
     sets the `:italic' attribute.

 - Function: set-face-underline-p face underline-p &optional frame
     This function sets the underline attribute of face FACE.
     Non-`nil' means do underline; `nil' means don't.

 - Function: invert-face face &optional frame
     This function inverts the `:inverse-video' attribute of face FACE.
     If the attribute is `nil', this function sets it to `t', and vice
     versa.

   These functions examine the attributes of a face.  If you don't
specify FRAME, they refer to the default data for new frames.  They
return the symbol `unspecified' if the face doesn't define any value
for that attribute.

 - Function: face-foreground face &optional frame
 - Function: face-background face &optional frame
     These functions return the foreground color (or background color,
     respectively) of face FACE, as a string.

 - Function: face-stipple face &optional frame
     This function returns the name of the background stipple pattern
     of face FACE, or `nil' if it doesn't have one.

 - Function: face-font face &optional frame
     This function returns the name of the font of face FACE.

 - Function: face-bold-p face &optional frame
     This function returns `t' if FACE is bold--that is, if it is
     bolder than normal.  It returns `nil' otherwise.

 - Function: face-italic-p face &optional frame
     This function returns `t' if FACE is italic or oblique, `nil'
     otherwise.

 - Function: face-underline-p face &optional frame
     This function returns the `:underline' attribute of face FACE.

 - Function: face-inverse-video-p face &optional frame
     This function returns the `:inverse-video' attribute of face FACE.