38.12.3 Face Attribute Functions

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

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

This function sets one or more attributes of face face for frame 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 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.

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 face on frame. If frame is nil, that means the selected frame (voir la section 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 values are also relative.

For example:

(face-attribute-relative-p :height 2.0) ⇒ t

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 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. They use values of t and nil for frame just like set-face-attribute and face-attribute.

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 actual bitmap data (voir la section Face Attributes), 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. This actually sets the attributes :family, :width, :height, :weight, and :slant according to the font name font.

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. This actually sets the :weight 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. This actually sets the :slant attribute.

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

This function sets the underline attribute of face face. Non-nil means do underline; nil means don't. If underline is a string, underline with that color.

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

This function sets the :inverse-video attribute of face face.

Function: invert-face face &optional frame

This function swaps the foreground and background colors of face face.

These 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 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.

Ce document a été généré par Eric Reinbold le 13 Octobre 2007 en utilisant texi2html 1.78.