Next: Displaying Faces, Previous: Defining Faces, Up: Faces [Contents][Index]

#### 37.12.3 Face Attribute Functions

This section describes functions for directly accessing and modifying the attributes of a named face.

Function: face-attribute face attribute &optional frame inherit

  This function returns the value of the attribute attribute for face on frame.

  If frame is `nil`, that means the selected frame (see Input Focus). If frame is `t`, this function returns the value of the specified attribute for newly-created frames (this is normally `unspecified`, unless you have specified some value using `set-face-attribute`; see below).

  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.

Normally, Emacs uses the face specs of each face to automatically calculate its attributes on each frame (see Defining Faces). The function `set-face-attribute` can override this calculation by directly assigning attributes to a face, either on a specific frame or for all frames. This function is mostly intended for internal usage.

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

  This function sets one or more attributes of face for frame. The attributes specifies in this way override the face spec(s) belonging to face.

  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 :weight 'bold :slant 'italic)

  sets the attribute `:weight` to `bold` and the attribute `:slant` to `italic`.

  If frame is `t`, this function sets the default attributes for newly created frames. If frame is `nil`, this function sets the attributes for all existing frames, as well as for newly created frames.

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 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 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 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. They mostly provide compatibility with old versions of Emacs. If you don’t specify frame, they refer to the selected frame; `t` refers to the default data for new frames. They return `unspecified` if the face doesn’t define any value for that attribute. If inherit is `nil`, only an attribute 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 attribute is found. To ensure that the return value is always specified, use a value of `default` for inherit.

Function: face-font face &optional frame character

  This function returns the name of the font of face face.

  If the optional argument frame is specified, it returns the name of the font of face for that frame. If frame is omitted or `nil`, the selected frame is used. And, in this case, if the optional third argument character is supplied, it returns the font name used for character.

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.

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.

Function: face-bold-p face &optional frame inherit

  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 inherit

  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 inherit

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

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

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

Next: Displaying Faces, Previous: Defining Faces, Up: Faces [Contents][Index]