elisp: Attribute Functions
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 omitted or ‘nil’, that means the selected frame (
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 (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’ (or omitted) 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. If the color is
unspecified, they return ‘nil’.
-- 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.
Info Catalog
elisp: Defining Faces
elisp: Faces
elisp: Displaying Faces