Next: , Previous: Defining Faces, Up: Faces

38.12.3 Face Attribute Functions

This section describes the functions for accessing and modifying the attributes of an existing named face.

— Function: set-face-attribute face frame &rest arguments

This function sets one or more attributes of face for frame. The attributes you specify this way override whatever the defface says.

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 values. Thus,

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

sets the attribute :width to extended and the attribute :weight to bold.

If frame is t, this function sets the default attributes for new frames. Default attribute values specified this way override the defface for newly created frames.

If frame is nil, this function sets the attributes for all existing frames, and the default for new frames.

— Function: face-attribute face attribute &optional frame inherit

This returns the value of the attribute attribute of face on frame. If frame is nil, that means the selected frame (see Input Focus).

If frame is t, this returns whatever new-frames default value you previously specified with set-face-attribute for the attribute attribute of face. If you have not specified one, it returns nil.

If inherit is nil, only attributes directly defined by face are considered, so the return value may be unspecified, or a relative value. If inherit is non-nil, face's definition of attribute is merged with the faces specified by its :inherit attribute; however the return value may still be unspecified or relative. If inherit is a face or a list of faces, then the result is further merged with that face (or faces), until it becomes specified and absolute.

To ensure that the return value is always specified and absolute, use a value of default for inherit; this will resolve any unspecified or relative values by merging with the default face (which is always completely specified).

For example,

          (face-attribute 'bold :weight)
               ⇒ bold
— Function: face-attribute-relative-p attribute value

This function returns non-nil if value, when used as the value of the face attribute attribute, is relative. This means it would modify, rather than completely override, any value that comes from a subsequent face in the face list or that is inherited from another face.

unspecified is a relative value for all attributes. For :height, floating point and function values are also relative.

For example:

          (face-attribute-relative-p :height 2.0)
               ⇒ t
— Function: face-all-attributes face &optional frame

This function returns an alist of attributes of face. The elements of the result are name-value pairs of the form (attr-name . attr-value). Optional argument frame specifies the frame whose definition of face to return; if omitted or nil, the returned value describes the default attributes of face for newly created frames.

— Function: merge-face-attribute attribute value1 value2

If value1 is a relative value for the face attribute attribute, returns it merged with the underlying value value2; otherwise, if value1 is an absolute value for the face attribute attribute, returns value1 unchanged.

The following commands and functions mostly provide compatibility with old versions of Emacs. They work by calling set-face-attribute. Values of t and nil for their frame argument are handled just like set-face-attribute and face-attribute. The commands read their arguments using the minibuffer, if called interactively.

— Command: set-face-foreground face color &optional frame
— Command: set-face-background face color &optional frame

These set the :foreground attribute (or :background attribute, respectively) of face to color.

— Command: set-face-stipple face pattern &optional frame

This sets the :stipple attribute of face to pattern.

— Command: set-face-font face font &optional frame

This sets the :font attribute of face to font.

— Function: set-face-bold-p face bold-p &optional frame

This sets the :weight attribute of face to normal if bold-p is nil, and to bold otherwise.

— Function: set-face-italic-p face italic-p &optional frame

This sets the :slant attribute of face to normal if italic-p is nil, and to italic otherwise.

— Function: set-face-underline face underline &optional frame

This sets the :underline attribute of face to underline.

— Function: set-face-inverse-video-p face inverse-video-p &optional frame

This sets the :inverse-video attribute of face to inverse-video-p.

— Command: invert-face face &optional frame

This swaps the foreground and background colors of face face.

The following functions examine the attributes of a face. If you don't specify frame, they refer to the selected frame; t refers 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 inherit
— Function: face-background face &optional frame inherit

These functions return the foreground color (or background color, respectively) of face face, as a string.

If inherit is nil, only a color directly defined by the face is returned. If inherit is non-nil, any faces specified by its :inherit attribute are considered as well, and if inherit is a face or a list of faces, then they are also considered, until a specified color is found. To ensure that the return value is always specified, use a value of default for inherit.

— Function: face-stipple face &optional frame inherit

This function returns the name of the background stipple pattern of face face, or nil if it doesn't have one.

If inherit is nil, only a stipple directly defined by the face is returned. If inherit is non-nil, any faces specified by its :inherit attribute are considered as well, and if inherit is a face or a list of faces, then they are also considered, until a specified stipple is found. To ensure that the return value is always specified, use a value of default for inherit.

— 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 a non-nil value if the :weight attribute of face is bolder than normal (i.e., one of semi-bold, bold, extra-bold, or ultra-bold). Otherwise, it returns nil.

— Function: face-italic-p face &optional frame

This function returns a non-nil value if the :slant attribute of face is italic or oblique, and nil otherwise.

— Function: face-underline-p face &optional frame

This function returns non-nil if face face specifies a non-nil :underline attribute.

— Function: face-inverse-video-p face &optional frame

This function returns non-nil if face face specifies a non-nil :inverse-video attribute.