Commit cd542620 authored by Chong Yidong's avatar Chong Yidong
Browse files

Improve Lisp manual documentation on setting faces.


* display.texi (Faces): Minor clarifications.
(Defining Faces): Clarify default vs custom face specs.  Document
face-spec-set.

* display.texi (Overlay Properties):
* text.texi (Special Properties): Use the "anonymous face"
terminology.  Describe foreground-color and background-color forms
as compatibility-only.
parent 8ead3901
2013-04-06 Chong Yidong <cyd@gnu.org>
* display.texi (Faces): Minor clarifications.
(Defining Faces): Clarify default vs custom face specs. Document
face-spec-set.
* display.texi (Overlay Properties):
* text.texi (Special Properties): Use the "anonymous face"
terminology. Describe foreground-color and background-color forms
as compatibility-only.
2013-03-24 Eli Zaretskii <eliz@gnu.org>
* compile.texi (Byte-Code Objects): Add index entry.
......
......@@ -1510,31 +1510,31 @@ of the symbol serve as defaults for the properties of the overlay.
@item face
@kindex face @r{(overlay property)}
This property controls the way text is displayed---for example, which
font and which colors. @xref{Faces}, for more information.
In the simplest case, the value is a face name. It can also be a list;
then each element can be any of these possibilities:
This property controls the appearance of the text (@pxref{Faces}).
The value of the property can be the following:
@itemize @bullet
@item
A face name (a symbol or string).
@item
A property list of face attributes. This has the form (@var{keyword}
@var{value} @dots{}), where each @var{keyword} is a face attribute
name and @var{value} is a meaningful value for that attribute. With
this feature, you do not need to create a face each time you want to
specify a particular attribute for certain text. @xref{Face
Attributes}.
An anonymous face: a property list of the form @code{(@var{keyword}
@var{value} @dots{})}, where each @var{keyword} is a face attribute
name and @var{value} is a value for that attribute.
@item
A cons cell, of the form @code{(foreground-color . @var{color-name})}
or @code{(background-color . @var{color-name})}. These elements
specify just the foreground color or just the background color.
A list of faces. Each list element should be either a face name or an
anonymous face. This specifies a face which is an aggregate of the
attributes of each of the listed faces. Faces occurring earlier in
the list have higher priority.
@code{(foreground-color . @var{color-name})} has the same effect as
@code{(:foreground @var{color-name})}; likewise for the background.
@item
A cons cell of the form @code{(foreground-color . @var{color-name})}
or @code{(background-color . @var{color-name})}. This specifies the
foreground or background color, similar to @code{(:foreground
@var{color-name})} or @code{(:background @var{color-name})}. This
form is supported for backward compatibility only, and should be
avoided.
@end itemize
@item mouse-face
......@@ -1901,44 +1901,39 @@ height.
@section Faces
@cindex faces
A @dfn{face} is a collection of graphical @dfn{attributes} for
displaying text: font, foreground color, background color, optional
underlining, etc. Faces control how Emacs displays text in buffers,
as well as other parts of the frame such as the mode line.
A @dfn{face} is a collection of graphical attributes for displaying
text: font, foreground color, background color, optional underlining,
etc. Faces control how Emacs displays text in buffers, as well as
other parts of the frame such as the mode line.
@cindex anonymous face
One way to represent a face is as a property list of attributes,
like @code{(:foreground "red" :weight bold)}. For example, you can
assign such an @dfn{anonymous face} as the value of the @code{face}
text property; this causes Emacs to display the underlying text with
the specified attributes. @xref{Special Properties}.
like @code{(:foreground "red" :weight bold)}. Such a list is called
an @dfn{anonymous face}. For example, you can assign an anonymous
face as the value of the @code{face} text property, and Emacs will
display the underlying text with the specified attributes.
@xref{Special Properties}.
@cindex face name
More commonly, a face is referred to via a @dfn{face name}: a Lisp
symbol which is associated with a set of face attributes. Named faces
are defined using the @code{defface} macro (@pxref{Defining Faces}).
Emacs defines several standard named faces; @xref{Standard Faces,,,
emacs, The GNU Emacs Manual}.
Many parts of Emacs require named faces, and do not accept anonymous
faces. These include the functions documented in @ref{Attribute
Functions}, and the variable @code{font-lock-keywords}
symbol associated with a set of face attributes@footnote{For backward
compatibility, you can also use a string to specify a face name; that
is equivalent to a Lisp symbol with the same name.}. Named faces are
defined using the @code{defface} macro (@pxref{Defining Faces}).
Emacs comes with several standard named faces (@pxref{Basic Faces}).
Many parts of Emacs required named faces, and do not accept
anonymous faces. These include the functions documented in
@ref{Attribute Functions}, and the variable @code{font-lock-keywords}
(@pxref{Search-based Fontification}). Unless otherwise stated, we
will use the term @dfn{face} to refer only to named faces.
For backward compatibility, you can also use a string to specify a
face name; that is equivalent to a Lisp symbol with the same name.
@defun facep object
This function returns a non-@code{nil} value if @var{object} is a
named face: a Lisp symbol or string which serves as a face name.
Otherwise, it returns @code{nil}.
@end defun
By default, each face name corresponds to the same set of attributes
in all frames. But you can also assign a face name a special set of
attributes in one frame (@pxref{Attribute Functions}).
@menu
* Face Attributes:: What is in a face?
* Defining Faces:: How to define a face.
......@@ -2178,32 +2173,47 @@ suitable for use with @code{:stipple} (see above). It returns
@node Defining Faces
@subsection Defining Faces
@cindex face spec
The usual way to define a face is through the @code{defface} macro.
This macro defines a face name, and associates that name with a set of
face attributes. It also sets up the face so that the user can
customize it via the Customize interface (@pxref{Customization}).
This macro associates a face name (a symbol) with a default @dfn{face
spec}. A face spec is a construct which specifies what attributes a
face should have on any given terminal; for example, a face spec might
specify one foreground color on high-color terminals, and a different
foreground color on low-color terminals.
People are sometimes tempted to create a variable whose value is a
face name. In the vast majority of cases, this is not necessary; the
usual procedure is to define a face with @code{defface}, and then use
its name directly.
@defmac defface face spec doc [keyword value]@dots{}
This macro declares @var{face} as a customizable face whose default
attributes are given by @var{spec}. You should not quote the symbol
@var{face}, and it should not end in @samp{-face} (that would be
redundant). The argument @var{doc} is a documentation string for the
face. The additional @var{keyword} arguments have the same meanings
as in @code{defgroup} and @code{defcustom} (@pxref{Common Keywords}).
When @code{defface} executes, it defines the face according to
@var{spec}, then uses any customizations that were read from the
init file (@pxref{Init File}) to override that specification.
When you evaluate a @code{defface} form with @kbd{C-M-x} in Emacs
Lisp mode (@code{eval-defun}), a special feature of @code{eval-defun}
overrides any customizations of the face. This way, the face reflects
exactly what the @code{defface} says.
@cindex face specification
The @var{spec} argument is a @dfn{face specification}, which states
how the face should appear on different kinds of terminals. It should
be an alist whose elements each have the form
This macro declares @var{face} as a named face whose default face spec
is given by @var{spec}. You should not quote the symbol @var{face},
and it should not end in @samp{-face} (that would be redundant). The
argument @var{doc} is a documentation string for the face. The
additional @var{keyword} arguments have the same meanings as in
@code{defgroup} and @code{defcustom} (@pxref{Common Keywords}).
If @var{face} already has a default face spec, this macro does
nothing.
The default face spec determines @var{face}'s appearance when no
customizations are in effect (@pxref{Customization}). If @var{face}
has already been customized (via Custom themes or via customizations
read from the init file), its appearance is determined by the custom
face spec(s), which override the default face spec @var{spec}.
However, if the customizations are subsequently removed, the
appearance of @var{face} will again be determined by its default face
spec.
As an exception, if you evaluate a @code{defface} form with
@kbd{C-M-x} in Emacs Lisp mode (@code{eval-defun}), a special feature
of @code{eval-defun} overrides any custom face specs on the face,
causing the face to reflect exactly what the @code{defface} says.
The @var{spec} argument is a @dfn{face spec}, which states how the
face should appear on different kinds of terminals. It should be an
alist whose elements each have the form
@example
(@var{display} . @var{plist})
......@@ -2275,7 +2285,8 @@ terminal must match one of the @var{value}s specified for it in
@end table
@end defmac
Here's how the standard face @code{highlight} is defined:
For example, here's the definition of the standard face
@code{highlight}:
@example
(defface highlight
......@@ -2294,65 +2305,56 @@ terminal must match one of the @var{value}s specified for it in
:group 'basic-faces)
@end example
Internally, Emacs stores the face's default specification in its
Internally, Emacs stores each face's default spec in its
@code{face-defface-spec} symbol property (@pxref{Symbol Properties}).
The @code{saved-face} property stores the face specification saved by
the user, using the customization buffer; the @code{customized-face}
property stores the face specification customized for the current
session, but not saved; and the @code{theme-face} property stores an
alist associating the active customization settings and Custom themes
with their specifications for that face. The face's documentation
string is stored in the @code{face-documentation} property. But
normally you should not try to set any of these properties directly.
@xref{Applying Customizations}, for the @code{custom-set-faces}
function, which is used to apply customized face settings.
People are sometimes tempted to create variables whose values
specify a face to use. In the vast majority of cases, this is not
necessary; it is preferable to simply use faces directly.
The @code{saved-face} property stores any face spec saved by the user
using the customization buffer; the @code{customized-face} property
stores the face spec customized for the current session, but not
saved; and the @code{theme-face} property stores an alist associating
the active customization settings and Custom themes with the face
specs for that face. The face's documentation string is stored in the
@code{face-documentation} property.
Normally, a face is declared just once, using @code{defface}, and
any further changes to its appearance are applied using the Customize
framework (e.g., via the Customize user interface or via the
@code{custom-set-faces} function; @pxref{Applying Customizations}), or
by face remapping (@pxref{Face Remapping}). In the rare event that
you need to change a face spec directly from Lisp, you can use the
@code{face-spec-set} function.
@defun face-spec-set face spec &optional spec-type
This function applies @var{spec} as a face spec for @code{face}.
@var{spec} should be a face spec, as described in the above
documentation for @code{defface}.
@cindex override spec @r{(for a face)}
The argument @var{spec-type} determines which spec to set. If it is
@code{nil} or @code{face-override-spec}, this function sets the
@dfn{override spec}, which overrides over all other face specs on
@var{face}. If it is @code{face-defface-spec}, this function sets the
default face spec (the same one set by @code{defface}). If it is
@code{reset}, this function clears out all customization specs and
override specs from @var{face} (in this case, the value of @var{spec}
is ignored). Any other value of @var{spec-type} is reserved for
internal use.
@end defun
@node Attribute Functions
@subsection Face Attribute Functions
This section describes the functions for accessing and modifying the
attributes of an existing named face.
@defun set-face-attribute face frame &rest arguments
This function sets one or more attributes of @var{face} for
@var{frame}. The attributes you specify this way override whatever
the @code{defface} says.
The extra arguments @var{arguments} specify the attributes to set, and
the values for them. They should consist of alternating attribute
names (such as @code{:family} or @code{:underline}) and values. Thus,
@example
(set-face-attribute 'foo nil
:width 'extended
:weight 'bold)
@end example
@noindent
sets the attribute @code{:width} to @code{extended} and the attribute
@code{:weight} to @code{bold}.
If @var{frame} is @code{t}, this function sets the default attributes
for new frames. Default attribute values specified this way override
the @code{defface} for newly created frames.
If @var{frame} is @code{nil}, this function sets the attributes for
all existing frames, and the default for new frames.
@end defun
This section describes functions for directly accessing and
modifying the attributes of a named face.
@defun face-attribute face attribute &optional frame inherit
This returns the value of the @var{attribute} attribute of @var{face}
on @var{frame}. If @var{frame} is @code{nil}, that means the selected
frame (@pxref{Input Focus}).
This function returns the value of the @var{attribute} attribute for
@var{face} on @var{frame}.
If @var{frame} is @code{t}, this returns whatever new-frames default
value you previously specified with @code{set-face-attribute} for the
@var{attribute} attribute of @var{face}. If you have not specified
one, it returns @code{nil}.
If @var{frame} is @code{nil}, that means the selected frame
(@pxref{Input Focus}). If @var{frame} is @code{t}, this function
returns the value of the specified attribute for newly-created frames
(this is normally @code{unspecified}, unless you have specified some
value using @code{set-face-attribute}; see below).
If @var{inherit} is @code{nil}, only attributes directly defined by
@var{face} are considered, so the return value may be
......@@ -2409,6 +2411,36 @@ If @var{value1} is a relative value for the face attribute
@var{attribute}, returns it merged with the underlying value
@var{value2}; otherwise, if @var{value1} is an absolute value for the
face attribute @var{attribute}, returns @var{value1} unchanged.
@end defun
Normally, Emacs uses the face specs of each face to automatically
calculate its attributes on each frame (@pxref{Defining Faces}). The
function @code{set-face-attribute} can override this calculation by
directly assigning attributes to a face, either on a specific frame or
for all frames. This function is mostly intended for internal usage.
@defun set-face-attribute face frame &rest arguments
This function sets one or more attributes of @var{face} for
@var{frame}. The attributes specifies in this way override the face
spec(s) belonging to @var{face}.
The extra arguments @var{arguments} specify the attributes to set, and
the values for them. They should consist of alternating attribute
names (such as @code{:family} or @code{:underline}) and values. Thus,
@example
(set-face-attribute 'foo nil :weight 'bold :slant 'italic)
@end example
@noindent
sets the attribute @code{:weight} to @code{bold} and the attribute
@code{:slant} to @code{italic}.
If @var{frame} is @code{t}, this function sets the default attributes
for newly created frames. If @var{frame} is @code{nil}, this function
sets the attributes for all existing frames, as well as for newly
created frames.
@end defun
The following commands and functions mostly provide compatibility
......@@ -2457,16 +2489,17 @@ This sets the @code{:inverse-video} attribute of @var{face} to
This swaps the foreground and background colors of face @var{face}.
@end deffn
The following functions examine the attributes of a face. If you
don't specify @var{frame}, they refer to the selected frame; @code{t}
refers to the default data for new frames. They return the symbol
@code{unspecified} if the face doesn't define any value for that
attribute. If @var{inherit} is @code{nil}, only an attribute directly
defined by the face is returned. If @var{inherit} is non-@code{nil},
any faces specified by its @code{:inherit} attribute are considered as
well, and if @var{inherit} is a face or a list of faces, then they are
also considered, until a specified attribute is found. To ensure that
the return value is always specified, use a value of @code{default} for
The following functions examine the attributes of a face. They
mostly provide compatibility with old versions of Emacs. If you don't
specify @var{frame}, they refer to the selected frame; @code{t} refers
to the default data for new frames. They return @code{unspecified} if
the face doesn't define any value for that attribute. If
@var{inherit} is @code{nil}, only an attribute directly defined by the
face is returned. If @var{inherit} is non-@code{nil}, any faces
specified by its @code{:inherit} attribute are considered as well, and
if @var{inherit} is a face or a list of faces, then they are also
considered, until a specified attribute is found. To ensure that the
return value is always specified, use a value of @code{default} for
@var{inherit}.
@defun face-font face &optional frame
......@@ -2576,13 +2609,13 @@ The value of this variable is an alist whose elements have the form
any text having the face @var{face} with @var{remapping}, rather than
the ordinary definition of @var{face}.
@var{remapping} may be any face specification suitable for a
@code{face} text property: either a face (i.e., a face name or a
property list of attribute/value pairs), or a list of faces. For
details, see the description of the @code{face} text property in
@ref{Special Properties}. @var{remapping} serves as the complete
specification for the remapped face---it replaces the normal
definition of @var{face}, instead of modifying it.
@var{remapping} may be any face spec suitable for a @code{face} text
property: either a face (i.e., a face name or a property list of
attribute/value pairs), or a list of faces. For details, see the
description of the @code{face} text property in @ref{Special
Properties}. @var{remapping} serves as the complete specification for
the remapped face---it replaces the normal definition of @var{face},
instead of modifying it.
If @code{face-remapping-alist} is buffer-local, its local value takes
effect only within that buffer.
......@@ -2629,7 +2662,7 @@ and @code{face-remap-reset-base} functions; it is intended for major
modes to remap faces in the buffers they control.
@defun face-remap-add-relative face &rest specs
This functions adds the face specifications in @var{specs} as relative
This functions adds the face spec in @var{specs} as relative
remappings for face @var{face} in the current buffer. The remaining
arguments, @var{specs}, should form either a list of face names, or a
property list of attribute/value pairs.
......
......@@ -3008,27 +3008,31 @@ character.
@item face
@cindex face codes of text
@kindex face @r{(text property)}
The @code{face} property controls the appearance of the character,
such as its font and color. @xref{Faces}. The value of the property
can be the following:
The @code{face} property controls the appearance of the character
(@pxref{Faces}). The value of the property can be the following:
@itemize @bullet
@item
A face name (a symbol or string).
@item
A property list of face attributes. This has the form (@var{keyword}
@var{value} @dots{}), where each @var{keyword} is a face attribute
name and @var{value} is a meaningful value for that attribute. With
this feature, you do not need to create a face each time you want to
specify a particular attribute for certain text.
An anonymous face: a property list of the form @code{(@var{keyword}
@var{value} @dots{})}, where each @var{keyword} is a face attribute
name and @var{value} is a value for that attribute.
@item
A list of faces. This specifies a face which is an aggregate of the
A list of faces. Each list element should be either a face name or an
anonymous face. This specifies a face which is an aggregate of the
attributes of each of the listed faces. Faces occurring earlier in
the list have higher priority. Each list element must have one of the
two above forms (i.e., either a face name or a property list of face
attributes).
the list have higher priority.
@item
A cons cell of the form @code{(foreground-color . @var{color-name})}
or @code{(background-color . @var{color-name})}. This specifies the
foreground or background color, similar to @code{(:foreground
@var{color-name})} or @code{(:background @var{color-name})}. This
form is supported for backward compatibility only, and should be
avoided.
@end itemize
Font Lock mode (@pxref{Font Lock Mode}) works in most buffers by
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment