Function: set-face-attribute

set-face-attribute is a byte-compiled function defined in faces.el.gz.

Signature

(set-face-attribute FACE FRAME &rest ARGS)

Documentation

Set attributes of FACE on FRAME from ARGS.

This function overrides the face attributes specified by FACE's face spec. It is mostly intended for internal use.

If FRAME is a frame, set the FACE's attributes only for that frame. If FRAME is nil, set attribute values for all existing frames, as well as the default for new frames. If FRAME is t, change the default values of attributes for new frames.

ARGS must come in pairs ATTRIBUTE VALUE. ATTRIBUTE must be a valid face attribute name and VALUE must be a value that is valid for ATTRIBUTE, as described below for each attribute.

In addition to the attribute values listed below, all attributes can also be set to the special value unspecified, which means the face doesn't by itself specify a value for the attribute.

When a new frame is created, attribute values in the FACE's defface spec normally override the unspecified values in the FACE's default attributes. To avoid that, i.e. to cause ATTRIBUTE's value be reset to unspecified when creating new frames, disregarding what the FACE's face spec says, call this function with FRAME set to t and the ATTRIBUTE's value set to unspecified.

The following attributes are recognized:

:family

VALUE must be a string specifying the font family
(e.g. "Monospace").

:foundry

VALUE must be a string specifying the font foundry, e.g., "adobe". If a font foundry is specified, wild-cards * and ? are allowed.

:width

VALUE specifies the relative proportionate width of the font to use. It must be one of the symbols ultra-condensed, extra-condensed, condensed, semi-condensed, normal, semi-expanded, expanded, extra-expanded, or ultra-expanded.

:height

VALUE specifies the relative or absolute height of the font. An absolute height is an integer, and specifies font height in units of 1/10 pt. A relative height is either a floating point number, which specifies a scaling factor for the underlying face height; or a function that takes a single argument (the underlying face height) and returns the new height. Note that for the default face, you must specify an absolute height (since there is nothing for it to be relative to).

:weight

VALUE specifies the weight of the font to use. It must be one of the symbols ultra-bold, extra-bold, bold, semi-bold, normal, semi-light, light, extra-light, ultra-light.

:slant

VALUE specifies the slant of the font to use. It must be one of the symbols italic, oblique, normal, reverse-italic, or reverse-oblique.

:foreground, :background

VALUE must be a color name, a string.

:underline

VALUE specifies whether characters in FACE should be underlined. If VALUE is t, underline with foreground color of the face. If VALUE is a string, underline with that color. If VALUE is nil, explicitly don't underline.

Otherwise, VALUE must be a property list of the form:

(:color COLOR :style STYLE).

COLOR can be either a color name string or foreground-color. STYLE can be either line or wave. If a keyword/value pair is missing from the property list, a default value will be used for the value. The default value of COLOR is the foreground color of the face. The default value of STYLE is line.

:overline

VALUE specifies whether characters in FACE should be overlined. If VALUE is t, overline with foreground color of the face. If VALUE is a string, overline with that color. If VALUE is nil, explicitly don't overline.

:strike-through

VALUE specifies whether characters in FACE should be drawn with a line striking through them. If VALUE is t, use the foreground color of the face. If VALUE is a string, strike-through with that color. If VALUE is nil, explicitly don't strike through.

:box

VALUE specifies whether characters in FACE should have a box drawn around them. If VALUE is nil, explicitly don't draw boxes. If VALUE is t, draw a box with lines of width 1 in the foreground color of the face. If VALUE is a string, the string must be a color name, and the box is drawn in that color with a line width of 1. Otherwise, VALUE must be a property list of the form (:line-width WIDTH
:color COLOR :style STYLE). If a keyword/value pair is missing from
the property list, a default value will be used for the value, as specified below. WIDTH specifies the width of the lines to draw; it defaults to 1. If WIDTH is negative, the absolute value is the width of the lines, and draw top/bottom lines inside the characters area, not around it. COLOR is the name of the color to draw in, default is the foreground color of the face for simple boxes, and the background color of the face for 3D boxes. STYLE specifies whether a 3D box should be draw. If STYLE is released-button, draw a box looking like a released 3D button. If STYLE is pressed-button draw a box that appears like a pressed button. If STYLE is nil, the default if the property list doesn't contain a style specification, draw a 2D box.

:inverse-video

VALUE specifies whether characters in FACE should be displayed in inverse video. VALUE must be one of t or nil.

:stipple

If VALUE is a string, it must be the name of a file of pixmap data. The directories listed in the x-bitmap-file-path variable are searched. Alternatively, VALUE may be a list of the form (WIDTH HEIGHT DATA) where WIDTH and HEIGHT are the size in pixels, and DATA is a string containing the raw bits of the bitmap. VALUE nil means explicitly don't use a stipple pattern.

For convenience, attributes :family, :foundry, :width,
:height, :weight, and :slant may also be set in one step
from an X font name:

:extend

VALUE specifies whether the FACE should be extended after EOL. VALUE must be one of t or nil.

:font

Set font-related face attributes from VALUE. VALUE must be a valid font name or font object. It can also be a fontset name. Setting this attribute will also set the :family, :foundry, :width, :height, :weight, and :slant attributes.

:inherit

VALUE is the name of a face from which to inherit attributes, or a list of face names. Attributes from inherited faces are merged into the face like an underlying face would be, with higher priority than underlying faces.

For backward compatibility, the keywords :bold and :italic can be used to specify weight and slant respectively. This usage is considered obsolete. For these two keywords, the VALUE must be either t or nil. A value of t for :bold is equivalent to setting :weight to bold, and a value of t for :italic is equivalent to setting :slant to italic. But if :weight is specified in the face spec, :bold is ignored, and if :slant is specified, :italic is ignored.

Probably introduced at or before Emacs version 21.1.

Source Code

;; Defined in /usr/src/emacs/lisp/faces.el.gz
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; Setting face attributes.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;


(defun set-face-attribute (face frame &rest args)
  "Set attributes of FACE on FRAME from ARGS.
This function overrides the face attributes specified by FACE's face spec.
It is mostly intended for internal use.

If FRAME is a frame, set the FACE's attributes only for that frame.  If
FRAME is nil, set attribute values for all existing frames, as well as
the default for new frames.  If FRAME is t, change the default values
of attributes for new frames.

ARGS must come in pairs ATTRIBUTE VALUE.  ATTRIBUTE must be a valid face
attribute name and VALUE must be a value that is valid for ATTRIBUTE,
as described below for each attribute.

In addition to the attribute values listed below, all attributes can
also be set to the special value `unspecified', which means the face
doesn't by itself specify a value for the attribute.

When a new frame is created, attribute values in the FACE's `defface'
spec normally override the `unspecified' values in the FACE's
default attributes.  To avoid that, i.e. to cause ATTRIBUTE's value
be reset to `unspecified' when creating new frames, disregarding
what the FACE's face spec says, call this function with FRAME set to
t and the ATTRIBUTE's value set to `unspecified'.

The following attributes are recognized:

`:family'

VALUE must be a string specifying the font family
\(e.g. \"Monospace\").

`:foundry'

VALUE must be a string specifying the font foundry,
e.g., \"adobe\".  If a font foundry is specified, wild-cards `*'
and `?' are allowed.

`:width'

VALUE specifies the relative proportionate width of the font to use.
It must be one of the symbols `ultra-condensed', `extra-condensed',
`condensed', `semi-condensed', `normal', `semi-expanded', `expanded',
`extra-expanded', or `ultra-expanded'.

`:height'

VALUE specifies the relative or absolute height of the font.  An
absolute height is an integer, and specifies font height in units
of 1/10 pt.  A relative height is either a floating point number,
which specifies a scaling factor for the underlying face height;
or a function that takes a single argument (the underlying face
height) and returns the new height.  Note that for the `default'
face, you must specify an absolute height (since there is nothing
for it to be relative to).

`:weight'

VALUE specifies the weight of the font to use.  It must be one of the
symbols `ultra-bold', `extra-bold', `bold', `semi-bold', `normal',
`semi-light', `light', `extra-light', `ultra-light'.

`:slant'

VALUE specifies the slant of the font to use.  It must be one of the
symbols `italic', `oblique', `normal', `reverse-italic', or
`reverse-oblique'.

`:foreground', `:background'

VALUE must be a color name, a string.

`:underline'

VALUE specifies whether characters in FACE should be underlined.
If VALUE is t, underline with foreground color of the face.
If VALUE is a string, underline with that color.
If VALUE is nil, explicitly don't underline.

Otherwise, VALUE must be a property list of the form:

`(:color COLOR :style STYLE)'.

COLOR can be either a color name string or `foreground-color'.
STYLE can be either `line' or `wave'.
If a keyword/value pair is missing from the property list, a
default value will be used for the value.
The default value of COLOR is the foreground color of the face.
The default value of STYLE is `line'.

`:overline'

VALUE specifies whether characters in FACE should be overlined.  If
VALUE is t, overline with foreground color of the face.  If VALUE is a
string, overline with that color.  If VALUE is nil, explicitly don't
overline.

`:strike-through'

VALUE specifies whether characters in FACE should be drawn with a line
striking through them.  If VALUE is t, use the foreground color of the
face.  If VALUE is a string, strike-through with that color.  If VALUE
is nil, explicitly don't strike through.

`:box'

VALUE specifies whether characters in FACE should have a box drawn
around them.  If VALUE is nil, explicitly don't draw boxes.  If
VALUE is t, draw a box with lines of width 1 in the foreground color
of the face.  If VALUE is a string, the string must be a color name,
and the box is drawn in that color with a line width of 1.  Otherwise,
VALUE must be a property list of the form `(:line-width WIDTH
:color COLOR :style STYLE)'.  If a keyword/value pair is missing from
the property list, a default value will be used for the value, as
specified below.  WIDTH specifies the width of the lines to draw; it
defaults to 1.  If WIDTH is negative, the absolute value is the width
of the lines, and draw top/bottom lines inside the characters area,
not around it.  COLOR is the name of the color to draw in, default is
the foreground color of the face for simple boxes, and the background
color of the face for 3D boxes.  STYLE specifies whether a 3D box
should be draw.  If STYLE is `released-button', draw a box looking
like a released 3D button.  If STYLE is `pressed-button' draw a box
that appears like a pressed button.  If STYLE is nil, the default if
the property list doesn't contain a style specification, draw a 2D
box.

`:inverse-video'

VALUE specifies whether characters in FACE should be displayed in
inverse video.  VALUE must be one of t or nil.

`:stipple'

If VALUE is a string, it must be the name of a file of pixmap data.
The directories listed in the `x-bitmap-file-path' variable are
searched.  Alternatively, VALUE may be a list of the form (WIDTH
HEIGHT DATA) where WIDTH and HEIGHT are the size in pixels, and DATA
is a string containing the raw bits of the bitmap.  VALUE nil means
explicitly don't use a stipple pattern.

For convenience, attributes `:family', `:foundry', `:width',
`:height', `:weight', and `:slant' may also be set in one step
from an X font name:

`:extend'

VALUE specifies whether the FACE should be extended after EOL.
VALUE must be one of t or nil.

`:font'

Set font-related face attributes from VALUE.
VALUE must be a valid font name or font object.  It can also
be a fontset name.  Setting this attribute will also set
the `:family', `:foundry', `:width', `:height', `:weight',
and `:slant' attributes.

`:inherit'

VALUE is the name of a face from which to inherit attributes, or
a list of face names.  Attributes from inherited faces are merged
into the face like an underlying face would be, with higher
priority than underlying faces.

For backward compatibility, the keywords `:bold' and `:italic'
can be used to specify weight and slant respectively.  This usage
is considered obsolete.  For these two keywords, the VALUE must
be either t or nil.  A value of t for `:bold' is equivalent to
setting `:weight' to `bold', and a value of t for `:italic' is
equivalent to setting `:slant' to `italic'.  But if `:weight' is
specified in the face spec, `:bold' is ignored, and if `:slant'
is specified, `:italic' is ignored."
  (setq args (purecopy args))
  (let ((where (if (null frame) 0 frame))
	(spec args)
	family foundry orig-family orig-foundry)
    ;; If we set the new-frame defaults, this face is modified outside Custom.
    (if (memq where '(0 t))
	(put (or (get face 'face-alias) face) 'face-modified t))
    ;; If family and/or foundry are specified, set it first.  Certain
    ;; face attributes, e.g. :weight semi-condensed, are not supported
    ;; in every font.  See bug#1127.
    (while spec
      (cond ((eq (car spec) :family)
	     (setq family (cadr spec)))
	    ((eq (car spec) :foundry)
	     (setq foundry (cadr spec))))
      (setq spec (cddr spec)))
    (when (or family foundry)
      (when (and (stringp family)
		 (string-match "\\([^-]*\\)-\\([^-]*\\)" family))
        (setq orig-foundry foundry
              orig-family family)
	(unless foundry
	  (setq foundry (match-string 1 family)))
	(setq family (match-string 2 family))
        ;; Reject bogus "families" that are all-digits -- those are some
        ;; weird font names, like Foobar-12, that end in a number.
        (when (string-match "\\`[0-9]*\\'" family)
          (setq family orig-family)
          (setq foundry orig-foundry)))
      (when (or (stringp family) (eq family 'unspecified))
	(internal-set-lisp-face-attribute face :family (purecopy family)
					  where))
      (when (or (stringp foundry) (eq foundry 'unspecified))
	(internal-set-lisp-face-attribute face :foundry (purecopy foundry)
					  where)))
    (while args
      (unless (memq (car args) '(:family :foundry))
	(internal-set-lisp-face-attribute face (car args)
					  (purecopy (cadr args))
					  where))
      (setq args (cddr args)))))