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 only.
If FRAME is nil, set the attributes for all existing frames, as
well as the default for new frames. If FRAME is t, change the
default for new frames only.
ARGS must come in pairs ATTRIBUTE VALUE. ATTRIBUTE must be a
valid face attribute name. All attributes can be set to
`unspecified'; this fact is not further mentioned below.
The following attributes are recognized:
`:family'
VALUE must be a string specifying the font family
(e.g. "Monospace") or a fontset.
`: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 a 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:
`:font'
Set font-related face attributes from VALUE. VALUE must be a
valid font name or font object. 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.