Faces
=====

   XEmacs has objects called extents and faces.  An "extent" is a
region of text and a "face" is a collection of textual attributes, such
as fonts and colors.  Every extent is displayed in some face;
therefore, changing the properties of a face immediately updates the
display of all associated extents.  Faces can be frame-local: you can
have a region of text that displays with completely different
attributes when its buffer is viewed from a different X window.

   The display attributes of faces may be specified either in Lisp or
through the X resource manager.

Customizing Faces
-----------------

   You can change the face of an extent with the functions in this
section.  All the functions prompt for a FACE as an argument; use
completion for a list of possible values.

`M-x invert-face'
     Swap the foreground and background colors of the given FACE.

`M-x make-face-bold'
     Make the font of the given FACE bold.  When called from a program,
     returns `nil' if this is not possible.

`M-x make-face-bold-italic'
     Make the font of the given FACE bold italic.  When called from a
     program, returns `nil' if not possible.

`M-x make-face-italic'
     Make the font of the given FACE italic.  When called from a
     program, returns `nil' if not possible.

`M-x make-face-unbold'
     Make the font of the given FACE non-bold.  When called from a
     program, returns `nil' if not possible.

`M-x make-face-unitalic'
     Make the font of the given FACE non-italic.  When called from a
     program, returns `nil' if not possible.

`M-x make-face-larger'
     Make the font of the given FACE a little larger.  When called from
     a program, returns `nil' if not possible.

`M-x make-face-smaller'
     Make the font of the given FACE a little smaller.  When called
     from a program, returns `nil' if not possible.

`M-x set-face-background'
     Change the background color of the given FACE.

`M-x set-face-background-pixmap'
     Change the background pixmap of the given FACE.

`M-x set-face-font'
     Change the font of the given FACE.

`M-x set-face-foreground'
     Change the foreground color of the given FACE.

`M-x set-face-underline-p'
     Change whether the given FACE is underlined.

   You can exchange the foreground and background color of the selected
FACE with the function `invert-face'. If the face does not specify both
foreground and background, then its foreground and background are set
to the background and foreground of the default face.  When calling
this from a program, you can supply the optional argument FRAME to
specify which frame is affected; otherwise, all frames are affected.

   You can set the background color of the specified FACE with the
function `set-face-background'.  The argument `color' should be a
string, the name of a color.  When called from a program, if the
optional FRAME argument is provided, the face is changed only in that
frame; otherwise, it is changed in all frames.

   You can set the background pixmap of the specified FACE with the
function `set-face-background-pixmap'.  The pixmap argument NAME should
be a string, the name of a file of pixmap data.  The directories listed
in the `x-bitmap-file-path' variable are searched.  The bitmap may also
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.  If the optional FRAME argument is provided, the face is
changed only in that frame; otherwise, it is changed in all frames.

   The variable `x-bitmap-file-path' takes as a value a list of the
directories in which X bitmap files may be found.  If the value is
`nil', the list is initialized from the `*bitmapFilePath' resource.

   If the environment variable XBMLANGPATH is set, then it is consulted
before the `x-bitmap-file-path' variable.

   You can set the font of the specified FACE with the function
`set-face-font'.  The FONT argument should be a string, the name of a
font.  When called from a program, if the optional FRAME argument is
provided, the face is changed only in that frame; otherwise, it is
changed in all frames.

   You can set the foreground color of the specified FACE with the
function `set-face-foreground'.  The argument COLOR should be a string,
the name of a color.  If the optional FRAME argument is provided, the
face is changed only in that frame; otherwise, it is changed in all
frames.

   You can set underline the specified FACE with the function
`set-face-underline-p'. The argument UNDERLINE-P can be used to make
underlining an attribute of the face or not. If the optional FRAME
argument is provided, the face is changed only in that frame;
otherwise, it is changed in all frames.