which allows it to have separate values in particular buffers, frames,
windows, and devices and to further vary according to device type
(X or TTY) and device class (color, mono, or grayscale).
-@xref{Specifiers} for more information.
+@xref{Specifiers}, for more information.
The face named @code{default} is used for ordinary text. The face named
@code{modeline} is used for displaying the modeline. The face named
@end defun
@defun facep object
-This function returns whether the given object is a face.
+This function returns @code{t} if @var{object} is a face, else @code{nil}.
@end defun
-@defun copy-face old-face new-name &optional locale how-to-add
+@defun copy-face old-face new-name &optional locale tag-set exact-p how-to-add
This function defines a new face named @var{new-name} which is a copy of
the existing face named @var{old-face}. If there is already a face
named @var{new-name}, then it alters the face to have the same
-properties as @var{old-face}. @var{locale} and @var{how-to-add}
-let you copy just parts of the old face rather than the whole face,
-and are as in @code{copy-specifier} (@pxref{Specifiers}).
+properties as @var{old-face}.
+
+@var{locale}, @var{tag-set}, @var{exact-p} and @var{how-to-add} let you
+copy just parts of the old face rather than the whole face, and are as
+in @code{copy-specifier} (@pxref{Specifiers}).
@end defun
@node Face Properties
@item background-pixmap
The pixmap displayed in the background of the face. Only used by faces
-on X devices.
+on GUI devices, currently X11, GTK, and Microsoft Windows.
@item underline
Underline all text covered by this face.
locale-specific values.
@end table
-@defun set-face-property face property value &optional locale tag how-to-add
+@defun set-face-property face property value &optional locale tag-set how-to-add
This function changes a property of a @var{face}.
For built-in properties, the actual value of the property is a specifier
specifier.
@end defun
-@defun face-property face property &optional locale
+@defun remove-face-property face property &optional locale tag-set exact-p
+This function removes a property of a @var{face}.
+
+For built-in properties, this is analogous to @code{remove-specifier}.
+For more information, @xref{Other Specification Functions}.
+
+When @var{property} is not a built-in property, this function will just
+remove its value if @var{locale} is @code{nil} or @code{all}. However,
+if @var{locale} is other than that, this function will attempt to remove
+@var{value} as the instantiator for the given @var{locale} with
+@code{remove-specifier}. If the value of the property is not a
+specifier, it will be converted into a @code{generic} specifier
+automatically.
+@end defun
+
+@defun face-property face property &optional locale tag-set exact-p
This function returns @var{face}'s value of the given @var{property}.
If @var{locale} is omitted, the @var{face}'s actual value for
@node Face Convenience Functions
@subsection Face Convenience Functions
-@defun set-face-foreground face color &optional locale tag how-to-add
-@defunx set-face-background face color &optional locale tag how-to-add
+@deffn Command set-face-foreground face color &optional locale tag-set how-to-add
+@deffnx Command set-face-background face color &optional locale tag-set how-to-add
These functions set the foreground (respectively, background) color of
face @var{face} to @var{color}. The argument @var{color} should be a
string (the name of a color) or a color object as returned by
@code{make-color} (@pxref{Colors}).
-@end defun
+@end deffn
-@defun set-face-background-pixmap face pixmap &optional locale tag how-to-add
+@deffn Command set-face-background-pixmap face pixmap &optional locale tag-set how-to-add
This function sets the background pixmap of face @var{face} to
@var{pixmap}. The argument @var{pixmap} should be a string (the name of
a bitmap or pixmap file; the directories listed in the variable
be a list of the form @code{(@var{width} @var{height} @var{data})} where
@var{width} and @var{height} are the size in pixels, and @var{data} is a
string, containing the raw bits of the bitmap.
-@end defun
-@defun set-face-font face font &optional locale tag how-to-add
+Similarly to how the glyph's image specifier works @xref{Creating
+Glyphs}, you don't create your own image specifier, but rather add
+specifications to the existing one. Note that the image instance that is
+generated in order to actually display the background pixmap is of type
+@code{mono-pixmap}, meaning that it's a two-color image and the
+foreground and background of the image get filled in with the
+corresponding colors from the face. (#### Is this still true?)
+@end deffn
+
+@deffn Command set-face-font face font &optional locale tag-set how-to-add
This function sets the font of face @var{face}. The argument @var{font}
should be a string or a font object as returned by @code{make-font}
(@pxref{Fonts}).
-@end defun
+@end deffn
-@defun set-face-underline-p face underline-p &optional locale tag how-to-add
+@deffn Command set-face-underline-p face underline-p &optional locale tag-set how-to-add
This function sets the underline property of face @var{face}.
-@end defun
+@end deffn
-@defun face-foreground face &optional locale
-@defunx face-background face &optional locale
+@defun face-foreground face &optional locale tag-set exact-p
+@defunx face-background face &optional locale tag-set exact-p
These functions return the foreground (respectively, background) color
specifier of face @var{face}.
@xref{Colors}.
@end defun
-@defun face-background-pixmap face &optional locale
-This function return the background-pixmap glyph object of face
+@defun face-background-pixmap face &optional locale tag-set exact-p
+This function returns the background-pixmap image specifier of face
@var{face}.
@end defun
-@defun face-font face &optional locale
+@defun face-font face &optional locale tag-set exact-p
This function returns the font specifier of face @var{face}. (Note:
This is not the same as the function @code{face-font} in FSF Emacs.)
+
@xref{Fonts}.
@end defun
@node Other Face Display Functions
@subsection Other Face Display Functions
-@defun invert-face face &optional locale
+@deffn Command invert-face face &optional locale
Swap the foreground and background colors of face @var{face}. If the
face doesn't specify both foreground and background, then its foreground
and background are set to the default background and foreground.
-@end defun
+@end deffn
@defun face-equal face1 face2 &optional domain
This returns @code{t} if the faces @var{face1} and @var{face2} will
@code{nil} otherwise.
@end defun
+@defun make-font-specifier spec-list
+
+Return a new @code{font} specifier object with the given specification
+list. @var{spec-list} can be a list of specifications (each of which is
+a cons of a locale and a list of instantiators), a single instantiator,
+or a list of instantiators. @xref{Specifiers}, for more information
+about specifiers.
+
+Valid instantiators for font specifiers are:
+
+@itemize @bullet
+
+@item
+A string naming a font (e.g. under X this might be
+"-*-courier-medium-r-*-*-*-140-*-*-*-*-iso8859-*" for a 14-point
+upright medium-weight Courier font).
+@item
+A font instance (use that instance directly if the device matches,
+or use the string that generated it).
+@item
+A vector of no elements (only on TTY's; this means to set no font
+at all, thus using the "natural" font of the terminal's text).
+@item
+A vector of one element (a face to inherit from).
+@end itemize
+@end defun
+
@node Font Instances
@subsection Font Instances
@cindex italic
@cindex oblique
-@defun font-instance-properties font
+@defun font-instance-properties font-instance
This function returns the properties (an alist or @code{nil}) of
@var{font-instance}.
@end defun
This function returns non-@code{nil} if @var{object} is a color specifier.
@end defun
+@defun make-color-specifier spec-list
+
+Return a new @code{color} specifier object with the given specification
+list. @var{spec-list} can be a list of specifications (each of which is
+a cons of a locale and a list of instantiators), a single instantiator,
+or a list of instantiators. @xref{Specifiers}, for a detailed
+description of how specifiers work.
+
+Valid instantiators for color specifiers are:
+
+@itemize @bullet
+@item
+A string naming a color (e.g. under X this might be "lightseagreen2" or
+"#F534B2").
+
+@item
+A color instance (use that instance directly if the device matches,
+or use the string that generated it).
+
+@item
+A vector of no elements (only on TTY's; this means to set no color at
+all, thus using the "natural" color of the terminal's text).
+
+@item
+A vector of one or two elements: a face to inherit from, and optionally
+a symbol naming which property of that face to inherit, either
+@code{foreground} or @code{background} (if omitted, defaults to the same
+property that this color specifier is used for; if this specifier is not
+part of a face, the instantiator would not be valid).
+@end itemize
+@end defun
+
+@defun make-face-boolean-specifier spec-list
+
+Return a new @code{face-boolean} specifier object with the given spec
+list. @var{spec-list} can be a list of specifications (each of which is
+a cons of a locale and a list of instantiators), a single instantiator,
+or a list of instantiators. @xref{Specifiers}, for a detailed
+description of how specifiers work.
+
+Valid instantiators for face-boolean specifiers are
+
+@itemize @bullet
+@item
+t or nil.
+@item
+A vector of two or three elements: a face to inherit from, optionally a
+symbol naming the property of that face to inherit from (if omitted,
+defaults to the same property that this face-boolean specifier is used
+for; if this specifier is not part of a face, the instantiator would not
+be valid), and optionally a value which, if non-@code{nil}, means to invert the
+sense of the inherited property.
+@end itemize
+
+@end defun
+
+
@node Color Instances
@subsection Color Instances
@cindex color instances
color of the @code{default} face is displayed in the next window after
the selected one.
-@defun color-instance-p object
+@defun color-instance-p object
This function returns non-@code{nil} if @var{object} is a color-instance.
@end defun
@subsection Color Instance Properties
@defun color-instance-name color-instance
-This function returns the name used to allocate @var{color-instance}.
+This function returns the name used to allocate @var{color-instance}.
@end defun
@defun color-instance-rgb-components color-instance
@end defun
@defun color-rgb-components color &optional domain
-This function returns the @sc{RGB} components of the @var{color} in the
+This function returns the @sc{rgb} components of the @var{color} in the
specified @var{domain}, if any. @var{color} should be a color specifier
object and @var{domain} is normally a window and defaults to the
selected window if omitted. This is equivalent to using
projects / chise / xemacs-chise.git.1 / blobdiff